Important: This is an experimental feature, which means that it might change unexpectedly.
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:
- Submitting a request for a partial feed response
- Formatting the fields parameter value
- Requesting the 'gd:fields' attribute in partial responses
- 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.
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:
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
urlattribute but do not include any other attributes: fields=entry(media:group(media:thumbnail(@url))) Example 4: Retrieve the
<media:category>tags for videos in the result set. For each
<media:category>tag, only return the tag's text content and the
labelattribute. 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 (
The following table shows a complete list of supported syntax for the fields parameter value:
|Filter elements||(list elements to be returned in parentheses)||
|Existence||[put conditions inside square brackets]||
|Numerical comparison||> or gt
>= or ge
< or lt
<= or le
|Date comparison||Use numerical operators for date and dateTime fields as shown.||
Requesting the 'gd:fields' attribute in partial responses
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
<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
Note: You must explicitly specify that attributes in the
gd namespace should be returned for the
gd:fields attributes to be included in the response. You can also request an individual attribute rather than all attributes in the namespace:
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
<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>