YouTube API v2.0 - Partial Updates

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.

This section explains how to send a PATCH request to only update specific metadata fields for an entry in a YouTube API feed. You can send a single PATCH request to add, replace and/or delete specific fields for a particular resource.

  1. Submitting a partial update request
  2. Formatting a partial update request
  3. Handling the response to a partial feed update

Note: Please read this documentation thoroughly before implementing partial updates to ensure that your updates do not inadvertently delete optional data fields. We also recommend that you test your partial update implementation on our staging server before launching the feature to production.

Submitting a partial update request

To add, update or delete specific metadata fields for a resource, your application will send a PATCH request to the same URL that you would normally use to update the resource with a PUT request. The body of the PATCH request is an <entry> that only contains the fields that you want to update.

The example below shows the format for a request to update the title and keywords for a video without changing any other video metadata:

PATCH /feeds/api/users/default/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY


<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:media='http://search.yahoo.com/mrss/'
    gd:fields='media:group(media:title,media:keywords)'>
  <title>New title</title>
  <media:group>
    <media:title type="plain">New title</media:title>
    <media:keywords>new, keywords, fancy multi-word keyword</media:keywords>
  </media:group>
</entry>

Formatting a partial update request

The body of the PATCH request is an XML document that identifies the metadata that you are adding, updating or deleting, and a single PATCH request can perform any combination of these operations at once. In a PATCH request, you can modify any of the following elements:

The guidelines below explain the format of a PATCH request. Also see the Changing access controls with partial updates section below for more details about updating access controls.

  1. If you identify an element in the <entry> tag's gd:fields attribute value, the element will be deleted from the resource. For example, the following request deletes the location and geographic coordinates associated with a video:

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:gml="http://www.opengis.net/gml'
    xmlns:georss="http://www.georss.org/georss'
    gd:fields='yt:location,georss:where'/>

    In this example, the gd:fields attribute specifies that the <georss:where> element should be deleted even though the <gml:pos> element actually contains the geographic coordinates for the video. However, since <gml:pos> is a required child element of <gml:Point>, which, in turn, is a required child element of <georss:where>, you must delete the full contents of <georss:where> to delete the coordinates associated with a video.

    You also cannot delete required elements, such as <media:title>, unless you replace them with new values.

    If the gd:fields attribute value in your request specifies an element that has child elements, then the API will try to delete the element and all of its children. For example, to delete the geographic coordinates associated with a video, which are specified in the <gml:pos> element, you can set the gd:fields value to georss:where. In processing the request, the API server will delete the <georss:where> element from the resource as well as its child element, <gml:Point>, and that element's child element, which is <gml:pos>.

  2. If you identify an element in the <entry> tag's gd:fields attribute value, and you also include that element in the XML request, then the element in the XML request will replace the existing element. For example, the following request replaces the title of a video:

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='media:group/media:title'>
  <media:group>
    <media:title type='plain'>New video title</media:title>
  </media:group>
</entry>

    Note: To avoid any ambiguity in your request, we recommend that you always use the gd:fields attribute to list the specific elements that you want to replace.

    This syntax also lets you add a metadata field to a resource. For example, the following request makes a video private:

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='media:group/yt:private'>
  <media:group>
    <yt:private/>
  </media:group>
</entry>

  3. Elements that appear in the XML request but that are not identified in the <entry> element's gd:fields attribute value are merged into the existing metadata for the resource according to the following rules:

    1. If the resource does not already contain an element that appears in the PATCH request, then the new element – including its content, attributes, and child elements – is added to the resource. For example, if a video is not associated with a set of geographic coordinates, and your PATCH request contains a <gml:pos> tag, the coordinates specified in that tag are associated with the video.

    2. If a non-repeating element in the PATCH request already appears in the resource, and the element does not have child elements, then the new element in the request replaces the existing element in the resource. For example, a video can only be associated with one location. As such, if a video is associated with a location, and your PATCH request contains a <yt:location> tag, the location specified in the request replaces the one already associated with the video. As a result, the following request has the same effect even if you do not include the <entry> tag's gd:fields attribute.

      <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <yt:location>New location</yt:location>
</entry>

      All of the fields that can be updated in the YouTube API are non-repeating elements with the exception of <yt:accessControl>, which is discussed in the Changing access controls with partial updates section below.

    3. If a non-repeating element in the PATCH request already appears in the resource, and the element has child elements, then the child elements included in the request will replace the corresponding child elements in the resource. However, child elements that are not included in the PATCH request will not be affected by the update. For the YouTube API, this rule only applies to partial updates of the <media:group> element and its children.

      For example, the request below does not specify a value for the <entry> element's gd:fields attribute. As a result, the API server would handle this request by only replacing child elements of the <media:group> element that are specified in the PATCH request. In this case, the request would update the video's title and make the video private. The request would not affect the existing values of the <media:category>, <media:description> or <media:keywords> elements.

      <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <media:group>
    <media:title type='plain'>New video title</media:title>
    <yt:private/>
  </media:group>
</entry>

Changing access controls with partial updates

Following the guidelines in the previous section, the examples below demonstrate how to update access controls for a video. Access controls, which are specified in the <yt:accessControl> element, determine whether users are allowed to rate a video, add comments about the video, rate comments about the video, or embed the video on third-party websites. Another setting indicates whether YouTube can show the video on Youtube properties other than the YouTube.com website.

Note: Each access control specifies a default setting. As a result, if you delete an access control but do not provide a new setting for it, the control will revert to its default setting. See the Uploading Videos section for more information about default access control settings.

  • To delete the access controls for a video and insert new controls, use the <entry> tag's gd:fields attribute to remove the existing controls. Then specify the new control settings in the XML that you submit for the request as shown below:

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='yt:accessControl'>
  <yt:accessControl action='comment' permission='allowed'/>
  <yt:accessControl action='commentVote' permission='allowed'/>
  <yt:accessControl action='embed' permission='allowed'/>
  <yt:accessControl action='rate' permission='allowed'/>
  <yt:accessControl action='list' permission='allowed'/>
  <yt:accessControl action='syndicate' permission='allowed'/>
</entry>

  • To replace one access control without changing other control settings, use the <entry> tag's gd:fields attribute to identify the setting you want to replace. In this case, you need to define the gd:fields value narrowly to avoid deleting other tag values that you want to keep.

    The request below updates a video so that it can be embedded on other websites. The request does not affect other access controls for the video. The gd:fields value instructs the API to delete the <yt:accessControl> tag that has an action of embed. The <yt:accessControl> tag in the XML request specifies a new embed setting that replaces the deleted one.

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='yt:accessControl[@action="embed"]'>
  <yt:accessControl action='embed' permission='allowed'/>
</entry>

Alternate notation for applications that do not handle PATCH method

If your application cannot properly handle the PATCH method, then you can send a POST request and set the X-HTTP-Method-Override request header to PATCH. For example, Flash applications must send a POST request to be able to set an Authorization header. (See the Authenticating Requests from Flash Applications section for more details.) Since all PATCH requests require authentication, to submit a PATCH request from a Flash application you would send an authenticated POST request and set the X-HTTP-Method-Override request header to PATCH as shown below. This alternate notation does not affect the formatting of either the request body or other request headers.

POST /feeds/api/videos/ HTTP/1.1
X-HTTP-Method-Override: PATCH
Host: gdata.youtube.com
Content-Type: application/xml
...

Handling the response to a partial feed update

When you submit a partial feed update request, the API will return a 200 HTTP response code. The body of the response will be the complete entry that you updated unless your PATCH request specified a value for the fields parameter. If it did specify a fields parameter value, then the API response will only contain the fields that you specified. See the Formatting the fields parameter value for instructions on how to specify the data fields that you want to be included in an API response.

If the body of your partial update request contained invalid XML, or if you specified an invalid value for the fields, the API will return a 400 (Bad Request) response code.

Error handling for partial update (PATCH) requests

The list below explains specific types of errors that may cause a YouTube API PATCH request to fail. In general, please see the Understanding API error responses section for more information about specific error messages that the API returns. Also see the reference guide for more information about the HTTP response codes that the API returns.

  • If a resource specifies a deprecated value for a specific element, the PATCH request will fail unless it updates that value. In this case, the API returns a yt:validation error with the <code> value of deprecated. For YouTube API requests, this error is most likely to occur if you try to do a partial update of a video that is associated with a deprecated category. This type of error can be confusing because the API response identifies the element containing the deprecated value as the location of the error in your PATCH request even if the request did not actually include that element.

    For example, the YouTube category document indicates that the "Short Movies" video category has been deprecated. As such, if you attempt to update the title of a video in that category, the update will fail unless you also update the video's category. In addition, the API response will identify the <media:category> tag as the location of the error in your API request even though your request may not have included that element.

    The sample response below shows the format of this error:

    <?xml version='1.0' encoding='UTF-8'?>
<errors>
  <error>
    <domain>yt:validation</domain>
    <code>deprecated</code>
    <location type='xpath'>
      media:group/media:category[@scheme='http://gdata.youtube.com/schemas/2007/categories.cat']/text()
    </location>
  </error>
</errors>

    See the Category list for uploaded videos section of the reference guide for more information about assignable video categories.

  • If the gd:fields attribute value and the contents of the <entry> element provide conflicting instructions as to which fields should be updated, the API server will return a 422 (Unprocessable Entity) HTTP response code. For example, in the following request, the gd:fields attribute specifies that only the <media:title> element should be replaced. However, the XML request also contains a <media:keywords> element, and the API server cannot determine whether to update (i) the <media:title> element; (ii) the <media:title> and <media:keywords> elements; or (iii) all of the child elements of <media:group>.

    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='media:group/media:title'>
  <media:group>
    <media:title type='plain'>New video title</media:title>
    <media:keywords>new,keywords,here</media:keywords>
  </media:group>
</entry>

  • If you try to update the access controls for a video, the API will return a too_many validation error unless you use the gd:fields attribute to identify the controls that you are updating. This error occurs because the <yt:accessControl> tag is a repeating element. As such, if you include the tag in a PATCH request, the API will add any access controls that you specify to the existing set of controls for a video. However, a video cannot specify more than one access control for a specific action ("embed", "rate", etc.).

    The API response below shows an error resulting from an attempt to update the access control setting that determines whether a video can be embedded on other websites. This error would occur if the original PATCH request did not use the <entry> tag's gd:fields attribute to identify the embed setting as the one being replaced.

    <?xml version='1.0' encoding='UTF-8'?>
<errors>
  <error>
    <domain>yt:validation</domain>
    <code>too_many</code>
    <location type='xpath'>yt:accessControl[@action='embed']</location>
  </error>
</errors>

    There are two ways to indicate that you want to update an access control setting for a video:

    • To update an individual setting or a specific group of settings, use the gd:fields value to explicitly identify the settings that you want to replace. For example, the following request updates the access control settings for comments and ratings:

      <?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
          xmlns:yt="http://gdata.youtube.com/schemas/2007"
          xmlns:gd="http://schemas.google.com/g/2005"
          gd:fields="yt:accessControl[@action='comment' or @action='rate']">
  <yt:accessControl action="comment" permission="moderated"/>
  <yt:accessControl action="rate" permission="allowed"/>
</entry>

    • To update all access controls, you would set the gd:fields value to yt:accessControl. Any access controls that are defined in the XML request will be applied to the video, and all other access controls will return to their default settings. For example, the following request sets the access control setting for comments to moderated and reverts all other access controls to their default settings:

      <?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
          xmlns:yt="http://gdata.youtube.com/schemas/2007"
          xmlns:gd="http://schemas.google.com/g/2005"
          gd:fields="yt:accessControl">
  <yt:accessControl action="comment" permission="moderated"/>
</entry>
pagination links

« Previous
Partial Responses 		Next »
Testing and Troubleshooting

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.