YouTube API v2.0 - Movies and Shows

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

Movies and trailers

Videos must meet special metadata requirements to be included in YouTube's Movies and Trailers categories. Feed entries for those videos accordingly contain several extra tags to reflect the enhanced metadata available for movies and trailers. Note, however, that movie and trailer entries are both types of video feed entries and could be returned in any feed that contains video entries, including search result feeds.

In addition, the YouTube API lets you retrieve several movie charts, which are standard feeds that only contain videos that appear in YouTube's Movies category.

The following subsections explain the special metadata fields included in movie and trailer entries as well as the movie charts that the API supports.

Special metadata fields in movie and trailer entries

Video and chart entries might contain several extra tags to reflect the enhanced metadata available for movies and trailers. These enhanced metadata fields are listed below:

  • The <yt:availability> tag specifies the date range when the movie or trailer will be available on YouTube.

  • The <yt:firstReleased> tag specifies the movie's original release date.

  • The entry may contain one or more additional <media:category> tags in addition to the standard one that indicates that the video is in the Movies or Trailers category:

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/mediatypes.cat indicates whether a video is a feature film, a short film, or a trailer. The following values are valid for this scheme:

      • 1 – Feature-length film
      • 2 – Short film
      • 3 – Full episode
      • 4 – Show clip
      • 5 – Trailer

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/moviegenres.cat specifies a genre (e.g. "Action & Adventure" or "Comedy") that describes the movie. A movie may be associated with multiple genres. The following values are valid for this scheme:

      • 1 – Action & Adventure
      • 2 – Animation & Cartoons
      • 3 – Classics
      • 4 – Comedy
      • 5 – Crime
      • 6 – Drama
      • 7 – Documentary & Biography
      • 8 – Family
      • 9 – Foreign
      • 10 – Horror
      • 11 – Mystery & Suspense
      • 12 – Romance
      • 13 – Science Fiction
      • 15 – Sports
      • 18 – Indian Cinema
      • 19 – Nigerian Cinema

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/releasemediums.cat specifies the original release medium for the movie. For example, a movie may have been originally released in theaters or on a premium cable channel. The following values are valid for this scheme:

      • 1 – Theatrical or festival film releases
      • 2 – Premium cable or satellite subscription channels, such as HBO
      • 3 – Basic cable and satellite channels, such as Comedy Central or MTV
      • 4 – Broadcast TV networks and local TV stations
      • 5 – Promotional clips and trailers
      • 6 – Original web content
      • 7 – Direct-to-video release

  • The <media:credit> tag can identify a contributor (actor, director, producer, or writer) to the movie, and an entry can include multiple <media:credit> tags.

  • The <media:rating> tag can specify an MPAA (Motion Picture Association of America) or V-Chip rating for a movie. The tag's scheme attribute identifies the type of rating, and the tag's value specifies the movie's rating under that scheme.

  • A <media:thumbnail> tag with a yt:name attribute value of poster specifies the URL for an image of the movie's poster art.

  • A trailer entry may contain a <link> tag that specifies a link to the YouTube Data API feed for the movie featured in the trailer. The tag will have a rel attribute value of http://gdata.youtube.com/schemas/2007#video.trailer-for:

    <link rel='http://gdata.youtube.com/schemas/2007#video.trailer-for'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/lJD3ABBCSrc?v=2'/>

Retrieving a movie chart

To retrieve a movie chart, send a GET request to the URL associated with that chart. Note that you must be using version 2 of the YouTube API to retrieve any of these charts. You can specify the API version using either the v parameter or the GData-Version HTTP request header.

The following table identifies the URL associated with each chart:

Chart name Feed ID URL and Description
Featured movies featured URL: https://gdata.youtube.com/feeds/api/charts/movies/featured?region=US
Description: This feed lists movies that are featured on the YouTube Movies category home page or in the Google Play Store. This feed will be empty if you do not specify a value for the region parameter. In addition, this feed does not support the movie-genre parameter.
Most popular movies most_popular URL: https://gdata.youtube.com/feeds/api/charts/movies/most_popular?region=US
Description: This feed lists the most popular videos in YouTube's Movies category.
Most recent movies most_recent URL: https://gdata.youtube.com/feeds/api/charts/movies/most_recent?region=US
Description: This feed lists videos that were recently added to YouTube's Movies category.
Trending movies trending URL: https://gdata.youtube.com/feeds/api/charts/movies/trending?region=US
Description: This feed lists videos that have recently experienced the greatest increases in popularity. You must specify a value for the region parameter to retrieve this feed.

API requests to retrieve movie charts can specify any of the following parameters:

  • The hl parameter specifies the movie's primary language.
  • The movie-genre parameter filters a chart to only include movies that are in a particular genre. The featured movie chart does not support this parameter.
  • The paid-content parameter filters a chart to only include either paid content or free content. If the parameter is not set, a chart can include both paid and free content.
  • The region parameter filters a chart to only include movies that are viewable in a particular territory. The parameter value is an ISO 3166-1 alpha-2 code that identifies the country where videos must be viewable to be included in search results. The featured movie chart returns an empty feed if you do not specify a value for this parameter.

You can use the following URL to retrieve the top selling or top free movies listed on http://www.youtube.com/movies. Set the paid-content parameter to true for movie rentals and to false for free movies. Note that you also need to provide the appropriate parameter values for the hl (e.g. en) and region (e.g. US) parameters.

http://gdata.youtube.com/feeds/api/charts/movies/trending?v=2
    &max-results=10
    &paid-content=(true|false)
    &hl=<LANGUAGE>
    &region=<REGION_CODE>

Shows, seasons, and episodes

As for movies, videos must meet special metadata requirements to be included in YouTube's Shows category. Feed entries for those videos accordingly contain several extra tags to reflect the enhanced metadata available for shows content. However, these entries are still video feed entries and could be returned in any feed that contains video entries, including search result feeds.

Videos for shows can be either full episodes or clips from an episode. Each video is associated with a particular season of a particular show, and the API provides feeds for retrieving shows, seasons of a show, and episodes (and clips) associated with a season of a show. The API also lets you retrieve show-related charts, which are standard feeds that only contain lists of shows.

In addition, videos in YouTube's Shows category are each associated with a particular season of a specific show. The API provides feeds for retrieving shows, seasons of a show, and episodes (and clips) associated with a specific season of a show. While only the episode/clip feed is a video feed, the other feeds are also explained below.

The following subsections explain these topics in more detail:

  1. Show feeds and entries
  2. Season entries
  3. Special metadata fields in episode (and clip) video entries
  4. Show charts

Show feeds and entries

A show feed contains a list of show entries, in which each entry contains information about one show. Each show is associated with one or more seasons.

A feed entry that represents a show contains a <category> tag that has a scheme attribute value of http://schemas.google.com/g/2005#kind and a term attribute value of http://gdata.youtube.com/schemas/2007#show.

<category scheme='http://schemas.google.com/g/2005#kind'
    term='https://gdata.youtube.com/schemas/2007#show'/>

You can retrieve shows owned by a particular user account by sending a GET request to the following URL:

https://gdata.youtube.com/feeds/api/users/username/shows?v=2

The sample shows feed below demonstrates the feed format. Only one feed entry is shown:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
      xmlns:gd='http://schemas.google.com/g/2005'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'
      gd:etag='W/&quot;A04GQXczeSp7I2A9WhRXFUQ.&quot;'>
  <id>tag:youtube.com,2008:user:CBA:shows</id>
  <updated>2011-12-23T00:25:20.981Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' term='https://gdata.youtube.com/schemas/2007#show'/>
  <title>Shows of CBA</title>
  <logo>http://www.gstatic.com/youtube/img/logo.png</logo>
  <link rel='alternate' type='text/html' href='http://www.youtube.com'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?start-index=26&max-results=25&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.1' uri='https://gdata.youtube.com'>YouTube data API</generator>
  <openSearch:totalResults>53</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;CkUMQH47eCp7I2A9WhdQFkk.&quot;'>
    <id>tag:youtube.com,2008:show:UzSpI-rPrUY</id>
    <published>2011-08-18T04:04:41.000Z</published>
    <updated>2011-08-18T04:04:41.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
        term='http://gdata.youtube.com/schemas/2007#show'/>
    <title>Widespread Hilarity</title>
    <summary>Widespread hilarity features Don and Flo getting laughs.</summary>
    <content type='application/atom+xml;type=feed'
        src='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'/>
    <link rel='alternate' type='text/html'
        href='http://www.youtube.com/show/widespreadhilarity'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/CBA/shows/UzSpI-rPrUY?v=2'/>
    <author>
      <name>CBA</name>
      <uri>https://gdata.youtube.com/feeds/api/users/CBA</uri>
    </author>
    <yt:countHint>2</yt:countHint>
    <media:group>
      <media:category scheme='http://gdata.youtube.com/schemas/2007/showgenres.cat'>4</media:category>
      <media:description>Widespread hilarity features Don and Flo getting laughs.</media:description>
      <media:keywords>widespread hilarity</media:keywords>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/market_thumb.jpg'
          height='72' width='128' yt:name='market'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter_thumb.jpg'
          height='150' width='150' yt:name='poster'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/market.jpg'
          height='243' width='432' yt:name='hqmarket'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter.jpg'
          height='300' width='300' yt:name='hqposter'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter_hq.jpg'
          height='600' width='600' yt:name='hqposterlarge'/>
      <media:title>Widespread Hilarity</media:title>
    </media:group>
    <yt:schedule country="US" dayOfWeek="1" hour="22" minute="0" second="0"
        timezone="EST" type="weekly"/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#video.season'
        href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'
        countHint='2'/>
  </entry>
</feed>

Note the following tags in the show entry:

  • The <gd:feedLink> tag provides a link to the seasons feed for the show. That tag's countHint attribute specifies the number of seasons in that feed. (The <yt:countHint> tag, which is also included in the entry, specifies the same number.)

  • A <media:category> tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/showgenres.cat specifies a genre (e.g. "Action & Adventure" or "Comedy") that describes the show. A show may be associated with multiple genres. The following values are valid for this scheme:

    • 1 – Action & Adventure
    • 2 – Animation & Cartoons
    • 3 – Classic TV
    • 4 – Comedy
    • 5 – Drama
    • 6 – Home & Garden
    • 7 – News
    • 8 – Reality & Game Shows
    • 9 – Science & Tech
    • 10 – Science Fiction
    • 11 – Soaps
    • 13 – Sports
    • 14 – Travel
    • 16 – Entertainment
    • 17 – Documentary
    • 20 – Nature
    • 21 – Beauty & Fashion
    • 23 – Food
    • 24 – Gaming
    • 25 – Health & Fitness
    • 26 – Learning & Education
    • 27 – Foreign Language

Season entries

A seasons feed lists seasons for a particular show for which the show owner has uploaded episodes (or clips) to YouTube. Each season is associated with either full episodes of the show, video clips from the show, or a combination of episodes and clips.

A feed entry that represents a season will contain a <category> tag that has a scheme attribute value of http://schemas.google.com/g/2005#kind and a term attribute value of http://gdata.youtube.com/schemas/2007#season.

<category scheme='http://schemas.google.com/g/2005#kind'
    term='https://gdata.youtube.com/schemas/2007#season'/>

To retrieve a feed of seasons for a particular show, first retrieve the entry for that show, and then extract the seasons feed URL from the gd:feedLink tag in the show entry.

The sample seasons feed below demonstrates the feed format. Only one feed entry is shown:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
      xmlns:gd='http://schemas.google.com/g/2005'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'
      gd:etag='W/&quot;CE4BQX0_fip7I2A9WhRWGEw.&quot;'>
  <id>tag:youtube.com,2008:show:UzSpI-rPrUY:content</id>
  <updated>2012-01-06T01:22:30.346Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#season'/>
  <title>Seasons of a show</title>
  <logo>http://www.gstatic.com/youtube/img/logo.png</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?alt=atom-service&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.1' uri='http://gdata.youtube.com'>YouTube data API</generator>
  <openSearch:totalResults>2</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;DUEGR347eCp7I2A9WhdbEkQ.&quot;'>
    <id>tag:youtube.com,2008:show:UzSpI-rPrUY:content:GZou3FaPdbw</id>
    <published>2011-07-22T16:59:10.000Z</published>
    <updated>2011-10-11T01:47:06.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
        term='http://gdata.youtube.com/schemas/2007#season'/>
    <title>2</title>
    <link rel='http://gdata.youtube.com/schemas/2007#video.show'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY?v=2'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content/GZou3FaPdbw?v=2'/>
    <author>
      <name>CBA</name>
      <uri>https://gdata.youtube.com/feeds/api/users/CBA</uri>
    </author>
    <media:group>
      <media:title>2</media:title>
    </media:group>
    <yt:season season='2'/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#season.clips'
        href='https://gdata.youtube.com/feeds/api/seasons/GZou3FaPdbw/clips?v=2'
        countHint='8'/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#season.episodes'
        href='https://gdata.youtube.com/feeds/api/seasons/GZou3FaPdbw/episodes?v=2'
        countHint='0'/>
  </entry>
</feed>

The feed entry contains two <gd:feedLink> tags. One provides the URL for a feed of full episodes and the other provides the URL for a feed of clips from the specified season of the show. Each tag's countHint attribute specifies the number of videos available in that feed. In addition, the <yt:season> tag specifies the season number.

Special metadata fields in episode (and clip) entries

A video feed entry that represents an episode or clip listed in YouTube's Shows category will contain a <category> tag that has a scheme attribute value of http://gdata.youtube.com/schemas/2007/categories.cat and a term attribute value of Shows.

<category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
            term='Shows' label='Shows'/>

In addition, feed entries for episodes and clips might also contain the following additional tags, which reflect enhanced metadata that is available for shows content:

  • The <yt:availability> tag specifies the date range when the content will be available on YouTube.

  • The <yt:episode> tag specifies the episode number for the video.

  • The <yt:firstReleased> tag specifies the content's original release date.

  • Several <media:category> tags, in addition to the standard one that indicates that the video is in the Shows category, can provide the following data:

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/mediatypes.cat indicates whether a video is a full episode or a clip from an episode. The following values are valid for this scheme:

      • 1 – Feature-length film
      • 2 – Short film
      • 3 – Full episode
      • 4 – Show clip
      • 5 – Trailer

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/releasemediums.cat specifies the original release medium for the content. For example, an episode may have been originally aired on a broadcast network or on a premium cable channel. The following values are valid for this scheme:

      • 1 – Theatrical or festival film releases
      • 2 – Premium cable or satellite subscription channels, such as HBO
      • 3 – Basic cable and satellite channels, such as Comedy Central or MTV
      • 4 – Broadcast TV networks and local TV stations
      • 5 – Promotional clips and trailers
      • 6 – Original web content
      • 7 – Direct-to-video release

  • The <media:credit> tag can identify a contributor (actor, director, producer, or writer) to the episode, and an entry can include multiple <media:credit> tags.

  • The <media:rating> tag can specify a rating, such as a V-Chip rating, for an episode. The tag's scheme attribute identifies the type of rating, and the tag's value specifies the episode's rating under that scheme.

  • A <media:thumbnail> tag with a yt:name attribute value of poster specifies the URL for an image of the show's poster art.

  • Two <link> tags provide the URLs of the show and season entries associated with the video content.

    <link rel='http://gdata.youtube.com/schemas/2007#video.show'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/SHOW_ID?v=2'/>
<link rel='http://gdata.youtube.com/schemas/2007#video.season'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/seasons/SEASON_ID?v=2'/>

Show charts

To retrieve a show chart, send a GET request to the URL associated with that chart. Note that you must be using version 2 of the YouTube API to retrieve any of these charts. You can specify the API version using either the v parameter or the GData-Version HTTP request header.

The following table identifies the URL associated with each chart:

Chart name Feed ID URL and Description
Most popular shows most_popular URL: https://gdata.youtube.com/feeds/api/charts/shows/most_popular?v=2
Description: This feed, which is updated daily, lists the most popular shows in YouTube's Shows category over the previous seven-day period.
Most recently updated shows latest URL: https://gdata.youtube.com/feeds/api/charts/shows/latest?region=US
Description: This feed, which is updated daily, lists shows that have the latest new content.

API requests to retrieve show charts can specify any of the following parameters:

  • The genre parameter filters a chart to only include shows that are in a particular genre.
  • The region parameter filters a chart to only include shows that are viewable in a particular territory. The parameter value is an ISO 3166-1 alpha-2 code that identifies the country where shows must be viewable to be included in search results.
pagination links

« Previous
Providing Captions for a Video 		Next »
YouTube EDU

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.