YouTube

YouTube API v2.0 – Retrieving a Partial Response

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

Note: This feature is not subject to the Deprecation Policy. Learn more.

The YouTube Data API, like several other GData APIs, enables you to submit an API request in which you specify the fields that will be included in the API response. By only requesting information that it will actually display, a client application can more efficiently use network, CPU and memory resources. By contrast, an application that retrieves a full API feed, parses it and then drops unused fields is likely to waste some resources along the way.

This section explains how to submit requests for partial feeds and also describes the format of the API responses to those requests.

This page contains the following sections:

  1. Submitting a request for a partial feed response
  2. Formatting the fields parameter value
  3. Requesting the 'gd:fields' attribute in partial responses
  4. Handling a partial feed response

Note: Partial feed requests are not supported for API requests that retrieve JSON-C responses.

Submitting a request for a partial feed response

To request a partial API response, add the fields parameter to the URL that you would use to retrieve the full API response. This parameter can be used for either or both of the following purposes:

  • It can specify the data fields that will be included in the API response. When used in this context, the parameter limits the data fields that are returned for the feed or for specific entries in the feed. However, it does not affect which entries are included in the result set.

  • It can filter the entries in the result set by ensuring that they match specific criteria. For example, you could use this parameter to specify that the API should only return entries for videos with more than 20 views, where the view count for each entry is identified in an XML element in the feed. In this case, the parameter does not necessarily affect the number of data fields that the API returns for an entry, but it can affect the number of entries actually returned.

    Note: The API handles filters identified in the fields parameter value differently than filters identified in other query parameters, such as the category or q parameters. The examples below demonstrate how the API processes the fields parameter value when it is used as a filter:

    • This example shows a simple query that retrieves the first 10 videos matching the keyword "surfing." It does not use the fields parameter to filter results.

      GET https://gdata.youtube.com/feeds/api/videos?q=surfing&max-results=10
      
    • This example uses the fields parameter to filter the results that would have been obtained in the previous example. The query specifies that the API should return videos that match the keyword "surfing" and that have more than 1,000,000 views:

           GET https://gdata.youtube.com/feeds/api/videos?q=surfing&max-results=10 \
             &fields=entry[yt:statistics/@viewCount > 1000000]
      

      In this case, the API retrieves the first 10 results matching the keyword "surfing" and then applies the view count filter. If two of the first 10 results have more than 1,000,000 views, then the API will only return two results. Since this example shows results ordered by relevance, which is the default behavior, there may be additional results with more than 1,000,000 views.

      You may be able to use the orderby parameter to avoid this behavior. For example, if you request videos matching the keyword "surfing" and order results by view count, then all videos with more than 1,000,000 views will appear at the beginning of the results feed.

The example below demonstrates how to request a feed of a user's uploaded videos that only contains the title, number of comments (and comment URL), and viewing statistics for each video:

https://gdata.youtube.com/feeds/api/users/default/uploads?
    fields=entry(title,gd:comments,yt:statistics)

Note: The fields parameter can be used with any API request that returns a feed, including GET, POST, and PUT requests. In the case of POST and PUT requests, the parameter only affects the API response. It does not affect the data that you are required to provide or the way that YouTube handles the request. For example, if you set the fields parameter value to title on a PUT request, you are not just updating the title of the associated entry. Rather, you will be updating the entire entry, but the API response will only contain the title of the updated entry.

Formatting the fields parameter value

The fields parameter value is formatted using a syntax inspired by XPath. Note, however, that this syntax does not support many expressions that are valid in XPath.

The guidelines below list several basic rules for formatting the parameter value and provide examples for each rule to explain how the parameter value affects the API response. The table below the list identifies all of the syntax that the API supports for the parameter value. The API will return a 400 HTTP response code (Bad Request) if the value uses unsupported syntax or is otherwise invalid.

  • The parameter value is a comma-delimited list of fields, and each field is specified relative to the root element in the API response. Thus, if you are retrieving a feed, fields are specified relative to the <feed> tag, and if you are retrieving a single entry, fields are specified relative to the <entry> tag. You can also use parentheses to filter a response so that it only contains a particular set of child elements.

    Example 1: Retrieve number of items in feed, index of
    first item in result set, and all entries in the feed:
    
        fields=openSearch:totalResults,openSearch:startIndex,entry
    
    Example 2: Retrieve the title, player URL, and thumbnail images for a single
    video entry. Note that this example uses parentheses to list the child elements
    of <media:group> that should be included in the API response.
    
        fields=title,media:group(media:player,media:thumbnail)
    
  • You can specify that an API response should only include the text content for a particular element or that it should only include certain attributes for that element. Just as you use parentheses to specify that a response should only contain particular child elements, you also use parentheses to specify whether the response should include the text content and/or attributes for a particular element. If you do not specify otherwise, the response will include the text content and all attributes for any element included in the response.

    Example 1: Retrieve all <entry> tags in feed, including any 
    attributes of the <entry> tag as well as all subtags in those entries,
    but do not retrieve other subtags of <feed>:
    
        fields=entry
    
    Example 2: Retrieve all <entry> tags in feed, but only include the
    <media:group> tag and all of its subtags in each entry. Do not
    retrieve attributes of the <entry> tag or other subtags of <feed>:
    
        fields=entry(media:group)
    
    Example 3: Retrieve all thumbnail URLs for the entries in the feed. The 
    response will be a feed of <entry> tags, each of which contains a
    <media:group> tag. Each <media:group> tag will contain a list of
    <media:thumbnail> tags that provide a value for their url attribute
    but do not include any other attributes:
    
        fields=entry(media:group(media:thumbnail(@url)))
    
    Example 4: Retrieve the <title>, <content> and <media:category>
    tags for videos in the result set. For each <media:category> tag, only
    return the tag's text content and the label attribute. The
    release notes discuss this feature and the evolution of the query syntax
    for partial responses in more detail.
    
        fields=entry(title,content,media:group(media:category(@label,text())))
    
  • By default, if your request specifies an element that occurs more than once, the partial response will include all instances of that element. However, you can also specify that the response should only include elements that have a particular attribute value as shown in the examples below.

    Example 1: Retrieve title as well as all link elements and
    all thumbnail images for all feed entries:
    
        fields=entry(title,link,media:group(media:thumbnail))
    
    Example 2: Retrieve title, edit link and
    all thumbnail images for all feed entries:
    
        fields=entry(title,link[@rel='edit'],media:group(media:thumbnail))
    
    Example 3: Retrieve title, self and edit links
    and all thumbnail images for all feed entries:
    
        fields=entry(title,link[@rel='self' or @rel='edit'],media:group(media:thumbnail))
    
    Example 4: Retrieve title, edit link and all
    90-pixel-high thumbnail images for all feed entries:
    
        fields=entry(title,link[@rel='edit']media:group(media:thumbnail[@height='90']))
    

Retrieving videos for playback on mobile devices

To ensure that an API response only contains videos that are suitable for playback on a mobile device, set the fields parameter to the following value. Note that the hash character (#) that appears in the parameter value must be escaped (%23).

fields=entry[link/@rel='http://gdata.youtube.com/schemas/2007%23mobile']

If you are developing an application for mobile devices, you may also want to specify the mobile projection in API requests.

Supported syntax

The following table shows a complete list of supported syntax for the fields parameter value:

Operator Syntax Example(s)
Filter elements (list elements to be returned in parentheses)
  • Return the <title>, <content> and <media:category> tags for videos in the result set.
        entry(title,content,media:group(media:category))

  • Return the <title>, <content> and <media:category> tags for videos in the result set, but only return the <media:category> tag's text value and do not include its attributes. This sample request differs from the previous one by adding an additional /text() path to the fields parameter value.
        entry(title,content,media:group(media:category/text()))
Existence [put conditions inside square brackets]
  • Filter the result set to only include video entries that contain a <yt:state> tag. For those videos, only return the <title>, <media:thumbnail>, and <yt:state> tags.
        entry[app:control/yt:state](title,media:group(media:thumbnail),app:control(yt:state))

    To filter results based on the presence of an element that does not contain text content, you must set the fields-language parameter value to r2. For example, the following example only returns entries that contain the <app:control> tag, which has subtags but does not contain text content.
        entry[app:control]&fields-language=r2
Equality comparison =
eq
!=
ne
  • Return entire entry if it contains a <link> element that has a rel attribute set to 'self':
        entry[link/@rel='self']

  • Return entire entry if it contains a <yt:aspectRatio> element with the value 'widescreen':
        entry[media:group/yt:aspectRatio = 'widescreen']
Logical comparison and
or
not
  • Return any entry that contains a <category> element that has a term attribute set to either 'ski' or 'snowboard':
        entry[category/@term = 'ski' or category/@term = 'snowboard']

  • Return <title> and <content> elements for each entry as well as any <media:thumbnail> elements that identify 90x120 images:
        entry(title,content,media:group(media:thumbnail[@height='90' and @width='120']))

  • Return <title> and <media:group> elements for entries that do not restrict playback in any way, which is indicated by the presence of the <yt:state> element:
        entry[not(app:control/yt:state)](title,media:group)
Numerical comparison > or gt
>= or ge
< or lt
<= or le
  • Return the <title>, <yt:statistics> and <media:group> elements for videos that have been viewed more than 20 times:
        entry[yt:statistics/@viewCount > 20](title,yt:statistics,media:group)

  • Return entries for videos that are less than two minutes long and have more than 20 views:
        entry[media:group/yt:duration/@seconds <= 120 and yt:statistics/@viewCount > 20]
Date comparison Use numerical operators for date and dateTime fields as shown.
  • Return entries for videos that were updated after 12 p.m. (UTC) on June 1, 2009. This is a dateTime comparison:
        entry[xs:dateTime(updated) > xs:dateTime('2009-06-01T12:00:00.000Z')]

  • Return <media:group> element and all of its child elements for videos that were recorded before June 1, 2009. Note that the <yt:recorded> tag is the only date (as opposed to dateTime) field in YouTube API feeds:
        entry[xs:date(yt:recorded) < xs:date('2009-06-01')](media:group)
Wildcard *
  • Return all elements in the media and yt namespaces.
        entry(media:*, yt:*)

Requesting the 'gd:fields' attribute in partial responses

The gd:fields attribute appears on the root element of partial API responses. The attribute value is the same as the fields query parameter value sent in the API request. In addition, each editable entry in the response will also have a gd:fields attribute, which identifies the elements that were specified in the fields query parameter value that might appear within the entry.

For example, the fields query parameter below requests the <title>, <content>, and <media:group> elements for each entry in a feed as well as all attributes in the gd namespace that appear on either the <feed> (root-level) tag or the <entry> tag.

fields=@gd:*,entry(@gd:*,title,content,media:group)

Note: You must explicitly specify that attributes in the gd namespace should be returned for the gd:etag and gd:fields attributes to be included in the response. You can also request an individual attribute rather than all attributes in the namespace:

fields=@gd:fields,entry(@gd:fields,title,content,media:group).

In the API response, the <feed> tag, which is the root element of the feed, will have the gd:fields attribute as shown below:

<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"Dk8BSHw9cSp7ImA9WxBWGE8."'
    gd:fields='@gd:*,entry(@gd:*,title,content,media:group)'>

In addition, each editable entry will also specify the gd:fields attribute:

<entry gd:etag='W/"A0MMRX47eCp7ImA9WxBWF04."'
    gd:fields='@gd:*,title,content,media:group'>

Note that your request needs to explicitly request edit links for entries if you want those links to be included in the partial API response.

Handling a partial feed response

When you submit a partial retrieval request, the API will return an XML response in which the root element is the <gd:partial> tag. That tag will contain the requested subset of the typical API response.

The following XML shows the sample request from the previous section and the API response to that request. (The request is for the titles, comment counts, and viewing statistics for the authenticated user's uploaded videos.)

Request:
GET /feeds/api/users/default/uploads?fields=@gd:*,entry(@gd:*,title,gd:comments,yt:statistics)
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Response:
<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/' 
    xmlns:gd='http://schemas.google.com/g/2005' 
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:etag='W/"Dk8BGDw9cSp7ImA9WxBWGE8."'
    gd:fields='entry(title,gd:comments,yt:statistics)'>
  <entry gd:etag='W/"Ef2SLAw9cSp7ImA9WxBWGE8."'
        gd:fields='@gd:*,title,gd:comments,yt:statistics'>
    <title>Why is Google Chrome Fast? Spotlight on DNS pre-resolution</title>
    <gd:comments>
      <gd:feedLink
          href='https://gdata.youtube.com/feeds/api/videos/FhDDwmOyRmk/comments?v=2'
          countHint='46'/>
    </gd:comments>
    <yt:statistics favoriteCount='25' viewCount='13050'/>
  </entry>
  <entry gd:etag='W/"L9UkCD19cSp7ImA9WxBWGE8."'
        gd:fields='@gd:*,title,gd:comments,yt:statistics'>
    <title>Why is Google Chrome Fast? Spotlight on DOM bindings</title>
    <gd:comments>
      <gd:feedLink
          href='https://gdata.youtube.com/feeds/api/videos/8QRTkPrFbVQ/comments?v=2'
          countHint='0'/>
    </gd:comments>
    <yt:statistics favoriteCount='37' viewCount='6888'/>
  </entry>
  <!-- more entries -->
</feed>
pagination links

« Previous
Using Batch Processing
Next »
Partial Updates

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.