YouTube

YouTube API v2.0 – Using Batch Processing

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

The YouTube Data API supports batch processing, enabling you to execute up to 50 operations with a single API request rather than submit a separate request for each individual operation. A batch processing request can combine multiple query (GET), insert (POST), update (PUT) and delete (DELETE) operations. Each operation is contained within an <entry> tag in the request. This section explains how to format batch processing requests and handle the API responses to those requests.

Batch operations are available for all YouTube feeds, and different types of feeds support different types of batch operations. For example, you can update, insert or delete playlists. However, you can only insert or delete favorite videos since favorite videos cannot be updated.

Please note the following characteristics of batch processing requests:

  • Batch processing requests support query (GET) operations for feed entries but not for entire feeds. For example, if you are sending a batch request for a playlist, you can include one or more entries that retrieve information about individual playlist entries. However, the batch request cannot retrieve the playlist feed that contains those entries.

  • When you submit a batch processing request, the API server will try to perform each requested operation even if some of the operations in the request are not completed successfully.

  • Submitting requests in a batch process does not reduce the amount of quota that your application uses and, therefore, does not reduce the likelihood that your application will exceed our limits on API calls.

  • Some of the API's client libraries may not support batch processing.

This page contains the following sections:

  1. Submitting a batch processing request
  2. Batch processing guidelines
  3. Sample batch processing request
  4. Handling the API response for a batch processing request
  5. Tracking operations in a batch processing request
  6. Identifying interrupted batch processing

Submitting a batch processing request

To submit a batch processing request, you send a POST request to a batch URL. Each feed has its own batch URL, and when you submit a request to that URL, you can execute API operations on any entry in that feed. The batch URL for a feed appears in a <link> tag with a rel attribute value of http://schemas.google.com/g/2005#batch. The <link> tag is a subtag of the <feed> tag for that feed.

<feed xmlns='http://www.w3.org/2005/Atom' ...>
  <id>https://gdata.youtube.com/feeds/users/USER_ID/playlists</id>
  ...
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/USER_ID/playlists/batch?v=2'/>
  ...

In the example above, the batch URL for the user's playlists feed is https://gdata.youtube.com/feeds/api/users/USER_ID/playlists/batch?v=2.

Important: Every entry in the batch request must be associated with the same batch URL. As such, you cannot use a single batch processing request to insert videos to a playlist and to flag those videos as a user's favorite videos since the playlist's feed has a different batch URL than the favorite videos feed.

In a batch processing request, <batch:operation> tags specify the type(s) of API requests that you want to execute. The <batch:operation> tag can be a subtag of either <feed> or <entry>. As a subtag of <feed>, the <batch:operation> tag specifies the default type of operation (query, insert, update or delete) that you are requesting for each entry in the feed. As a subtag of <entry>, the <batch:operation> tag specifies the type of operation that you want to perform on that particular entry.

Batch processing guidelines

This section lists several important guidelines for batch processing requests. Some of these guidelines highlight specific ways that YouTube Data API's batch processing functionality differs from the batch processing functionality for other Google Data APIs.

  • Batch processing requests may contain up to 50 entries. Other Google Data APIs may allow requests to contain more than 50 entries.

  • Batch processing requests must be 1MB or smaller.

  • In your batch processing request, entries that are for query, update or delete operations should include both the <id> and the edit URL for the resource that is being queried, updated or deleted.

Sample batch processing request

The following batch processing request performs the following operations on a playlist:

  1. Insert one video.
  2. Delete two videos.
  3. Update the playback order of three videos.

In the example, the <feed> tag has a <batch:operation> subtag that indicates that the default API operation for the batch processing request is update. Each entry in the request that does not correspond to an update operation contains a <batch:operation> tag that overrides this default setting.

<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      xmlns:batch='http://schemas.google.com/gdata/batch'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'>
  <batch:operation type="update"/>
  <entry>
    <batch:operation type="insert"/>
    <id>tag:youtube,2008:video:ZTUVgYoeN_b</id>
    <batch:id>InsertedVideo1</batch:id>
  </entry>
  <entry>
    <batch:operation type="delete"/>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:F1A9BE54EF1EBD7A</id>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/77473B5FB369B676?v=2'/>
  </entry>
  <entry>
    <batch:operation type="delete"/>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:FE7E71CC9E49DB43</id>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B21A4EE5CD829174?v=2'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:77773B5FB389A676</id>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B7D3D08BD2F219CF?v=2'/>
    <yt:position>1</yt:position>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B7D8D08CD2F119CF</id>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/E7F3D18BA3E217CB?v=2'/>
    <yt:position>2</yt:position>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:E2C8AD924E46577B</id>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/C1A3B17AC5E587AB?v=2'/>
    <yt:position>3</yt:position>
  </entry>
</feed>

The activity feeds section also includes a sample batch processing request that retrieves a list of video entries.

Handling the API response for a batch processing request

When you submit a batch processing request, the API will return an XML response that contains one <entry> for each operation in your request. The order of the entries in the response will correspond to the order of the entries in the request. The <batch:status> tag in each entry identifies the HTTP response code that the API returned for the corresponding entry in the batch request, indicating whether YouTube processed the entry successfully.

Note: You may receive a response that indicates that some operations were completed successfully while other operations failed.

The XML below shows the API response to the sample batch processing request shown in the previous section. Some tags in the entries for the inserted and updated entries have been omitted to highlight the tags that are specifically used for batch processing or the values that were updated in the batch processing request.

<?xml version='1.0' encoding='UTF-8'?>
<feed
  xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <updated>2008-07-11T19:37:13.547Z</updated>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:A5B2B2C5FFCF79AB</id>
    <yt:position>11</yt:position>
    <batch:id>InsertedVideo1</batch:id>
    <batch:status code='201' reason='Created'/>
    <batch:operation type='insert'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:77473B5FB369B676</id>
    <updated>2008-07-11T19:37:13.970Z</updated>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='delete'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B21A4EE5CD829174</id>
    <updated>2008-07-11T19:37:13.970Z</updated>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='delete'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B7D3D08BD2F219CF</id>
    ...
    <yt:position>1</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:E7F3D18BA3E217CB</id>
    ...
    <yt:position>2</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:C1A3B17AC5E587AB</id>
    ...
    <yt:position>3</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
</feed>

Tracking operations in a batch processing request

You can use the following mechanisms to track the success or failure or operations in a batch processing request:

  • For update, delete and query operations, you can use the value of the <id> tag to identify the resource that was updated, deleted or retrieved.

  • You can specify a <batch:id> to identify an entry in your batch processing request. The API response will return this ID in the response entry that corresponds to the request entry. This tracking method is particularly useful for insert operations because newly inserted resources are assigned new ID values that are not known when the batch processing API requests are submitted.

    The sample batch processing request contains one entry that adds a video to a playlist. That entry contains an <id> tag with the value tag:youtube,2008:video:ZTUVgYoeN_b. But in the sample response, the <id> tag for that entry has the value tag:youtube,2008:playlist:8BCDD04DE8F771B2:A5B2B2C5FFCF79AB. The values are different because the entry in the request specifies the ID of a video that is being added to a playlist, but the entry in the response specifies the ID for the playlist entry. However, both entries include the <batch:id> tag with the value InsertedVideo1, simplifying efforts to track the insert operation. (See how the <batch:id> tag is used in the sample request or response.)

  • The order of the entries in the API response corresponds to the order of the entries in the request. Thus, your application could use a numeric index to track failures identified in the API response and then correlate that index to the batch processing request to identify the specific operations that failed.

Identifying interrupted batch processing

If your request did not contain properly formed XML, then the API response may not contain the same number of entries as the original batch processing request. In such cases, the API response will use the <batch:interrupted> tag to identify the entry with the malformed XML. That entry might be the last one in the API response, and other entries after the one with the malformed XML might not have been processed. (The API server will attempt to indicate in the response how many entries were not processed.)

<batch:interrupted
  reason="[Line 14, Column 34, element entry] Invalid type for batch:operation: 'PUT'"
  success="8" failures="3" parsed="14"/>
pagination links

« Previous
Using the Simple Update Protocol (SUP)
Next »
Partial Responses

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.