YouTube API v2.0 – Testing and Troubleshooting

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information. Please use the YouTube Data API (v3) for new integrations and migrate applications still using the v2 API to the v3 API as well.

This section explains two resources, the interactive API demo and the YouTube API staging server, that YouTube provides to help you implement the API. In addition, this section discusses several aspects of an API implementation that developers may find challenging. It provides an overview of each issue and explains how to handle the issue correctly.


  1. Using the Interactive API Demo
  2. Using the staging server
  3. Troubleshooting common API challenges
    1. Filtering API responses
    2. Calculating the content-length for direct upload requests
    3. Identifying a video for a particular operation
    4. Uploading private videos
    5. Caching video metadata to avoid quota issues
    6. Uploading a large batch of videos

Using the Interactive API Demo

YouTube's interactive API demo lets you explore the YouTube Data API by generating and executing different types of API requests and viewing the API responses for those requests. The following steps, which also appear on the demo page, explain how the demo works:

  1. You select an API operation that you want to perform. For example, you could search for (query) videos, create favorite videos or delete complaints. The demo supports almost all of the operations available in the API.

    When you select an operation, the forms on the page will update to enter the categories and keywords, request parameters, and request headers appropriate for that type of operation. For example, you do not need to enter a user name or have an authentication token to search for videos, but you can filter results using a number of request parameters (format, location, etc.). On the other hand, when you create a playlist, the request parameters are irrelevant but you do need to provide a username and an authentication token.

  2. Construct the API request.

    • If you are performing a query (search) operation, enter search parameters and then edit the resulting request URL.
    • If you are inserting, updating or deleting a resource, enter information about that resource and then tweak the XML in the body of the generated request.

  3. Click the Submit button. The XML response will display at the bottom of the page.

Using the staging server

YouTube posts updated versions of the API, which could include new features or bug fixes, to a staging server before those updates are released to production. The staged API instance helps YouTube ensure that API releases do not include any unexpected or undesired changes before the API is released to production. The staged API instance offers you the opportunity to test your applications before API releases affect your live site, and it should only be used for testing. Please do not use it in any live, publicly available application.

Warning: The staged API instance is not a sandboxed environment. It uses live data and you could lose information in your YouTube account if you use it when testing against the staging server.

In addition, the default API version used on the staging server is version 2. As such, you do not need to use the v parameter or the GData-Version HTTP request header to use version 2 of the API on the staging server. However, you do still need to use the v parameter or the GData-Version request header to use version 2 of the API on the production API servers.

We recommend that you create a test account and only use that account when running queries against the staging server.

To use the staged API instance, you need to submit API requests to a different hostname. You also need to use a different hostname to test video uploads to the staged instance. The URLs for the production and staged versions of the API are listed below:

All queries except uploads:


Each release that is released to the staging server will be announced in the YouTube APIs Announcement Forum. You can subscribe to the group to receive email updates about new API releases.

Troubleshooting common API challenges

The following sections discuss several aspects of the API that many developers find challenging. Each section presents an overview of a specific issue and explains how to confirm that your code handles the issue correctly.

  1. Filtering API responses
  2. Calculating the content-length for direct upload requests
  3. Identifying a video for a particular operation
  4. Uploading private videos
  5. Caching video metadata to avoid quota issues
  6. Uploading a large batch of videos

Filtering API responses

Like the YouTube website, the YouTube API does not support search parameters, including the category, format and orderby parameters, in requests for feeds that aggregate videos. For those feeds, the YouTube API also does not filter videos that are not available in the user's territory or that have been removed or blocked from appearing on the YouTube website. This policy affects the following types of feeds:

The impact of this policy is that a feed may contain information about videos that are not actually playable for any of the following reasons:

  • It is not available in the selected format.
  • It is not playable in the user's location.
  • It has been removed from YouTube by the user who uploaded the video.
  • It has been claimed by a YouTube content partner, such as a record label or movie studio, and blocked from appearing on YouTube by that owner.

This policy benefits users because it ensures that feeds do not filter out removed or unavailable videos that the user might expect to see listed. For example, suppose a user creates a playlist with 10 videos and five of those videos are subsequently removed by their owners. If the user retrieves the playlist, she might be confused to see five videos listed instead of 10. In addition, this policy ensures that the number of videos in a feed, such as a playlist feed, does not change if a user tries to access the feed from different locations. As such, This policy ensures that all of the videos can be listed on the page even if some of the videos are not playable.

On the YouTube website, when a video is unavailable, YouTube still displays video metadata like the video's title and description. However, the video title does not link to a video watch page and the text "[video unavailable]" appears next to the title.

If a video is not playable, the entry for that video will not contain a <media:content> tag. In addition, the entry may contain an <app:control> tag that contains an explanation of why the video is not playable, as shown in the following example:

Example 1:
  <yt:state name="rejected" reasonCode="blocked"
    Blocked by content owner

Example 2:
  <yt:state name="restricted" reasonCode="requesterRegion">
    This video is not available in your country

Calculating the content-length for direct upload requests

Direct upload requests are multipart requests, in which one part of the request is the API XML request and another part is the actual media file. Developers frequently calculate Content-Length header values that are too small. Ultimately, the incorrect value causes the API server to ignore the part of the request that contains the file binary and respond with the following error:

Multipart must have Atom and media part

To calculate the proper Content-Length, you need to count the full string length of the POST request. However, in addition to the XML component and the file binary, a direct upload request also defines a boundary string that separates the different parts of the request. So the calculation of the Content-Length needs to account for the size of the XML and file binary as well as of the inserted boundary strings and newlines.

Identifying a video for a particular operation

A number of different API operations require you to identify a video to add or update a resource. These operations include adding a favorite video, rating a video, and adding a playlist entry.

To identify a video, use the <yt:videoid> for that video. Developers often substitute the <id> for the video, which is not always the same value. For example, the same video could appear in a search results feed, a playlist feed, and a favorite videos feed. In each of those feeds, the video would have a different <id> but the same <yt:videoid>.

For example, to add a video to a playlist you send a POST request to the following URL, with the string PLAYLIST_ID identifying the playlist to which you are adding the video:

The request includes the XML below, in which the string VIDEO_ID identifies the video that is being added to the playlist. That value is the <yt:videoid> value for that video.

<entry xmlns="http://www/">

Uploading private videos

When uploading or updating a video, you can use the <yt:private> tag to make the video a private video. Private videos are only visible to the video owner and to contacts with whom the owner has shared the video. Search results do not include private videos.

You can upload private videos and then later change those videos to be publicly visible. However, this process may delay the inclusion of those videos in the YouTube search index. This approach may also delay the availability of those videos in API responses.

Caching video metadata to avoid quota issues

The YouTube API enforces quotas to prevent problems associated with irregular API usage. Specifically, a too_many_recent_calls error indicates that the API servers have received too many calls from the same caller in a short amount of time. If you receive this type of error, then we recommend that you wait a few minutes and then try your request again.

To avoid quota errors, high-traffic websites should cache video metadata fetched through the API for one to two hours.

Uploading a large batch of videos

If you are uploading a large batch of videos, please do not upload more than one video every three to five minutes. This process helps to ensure that you will not receive a quota error for trying to upload too many videos in too short a time.

pagination links

« Previous
Partial Updates
Next »
Understanding API Error Responses