YouTube

Developer's Guide: JSON-C / JavaScript

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

When submitting a YouTube Data API request, you can use the alt query parameter to specify the format of the API response. The API can return responses in a number of formats, including Atom (XML), RSS (XML), JSON (JavaScript Object Notation) and JSON-C, which is a variant of JSON.

This document describes the JSON-C response format, which is designed to allow developers a basic level of API access to API responses from JavaScript and other clients. This document contains the following sections:

Understanding the JSON-C format

Unlike other YouTube API feed formats, JSON-C feeds do not adhere to either the Atom or RSS standard for syndicated feeds. Instead, JSON-C feeds seek to present the same information available in other feed formats in a customized, compact format. As such, JSON-C feeds exclude data that is redundant, irrelevant, or easily calculated by the client code. In addition, since the JSON-C feeds are customized specifically for the YouTube API, they structure data in a more natural, logical way than other feed formats.

The JSON-C feed below shows the basic format of the API's JSON-C responses. The example shows a search results feed with one item. The feed is a JSON object that contains a number of properties. The value of the items property is an array of objects in which each object identifies a result in the feed.

{"apiVersion":"2.0",
 "data":{
    "updated":"2010-01-07T19:58:42.949Z",
    "totalItems":800,
    "startIndex":1,
    "itemsPerPage":1,
    "items":[
        {"id":"hYB0mn5zh2c",
         "uploaded":"2007-06-05T22:07:03.000Z",
         "updated":"2010-01-07T13:26:50.000Z",
         "uploader":"GoogleDeveloperDay",
         "category":"News",
         "title":"Google Developers Day US - Maps API Introduction",
         "description":"Google Maps API Introduction ...",
         "tags":[
            "GDD07","GDD07US","Maps"
         ],
         "thumbnail":{
            "default":"http://i.ytimg.com/vi/hYB0mn5zh2c/default.jpg",
            "hqDefault":"http://i.ytimg.com/vi/hYB0mn5zh2c/hqdefault.jpg"
         },
         "player":{
            "default":"https://www.youtube.com/watch?v\u003dhYB0mn5zh2c",
            "mobile":"https://m.youtube.com/details?v\u003dhYB0mn5zh2c"
         },
         "content":{
            "1":"rtsp://v5.cache3.c.youtube.com/CiILENy.../0/0/0/video.3gp",
            "5":"http://www.youtube.com/v/hYB0mn5zh2c?f...",
            "6":"rtsp://v1.cache1.c.youtube.com/CiILENy.../0/0/0/video.3gp"
         },
         "duration":2840,
         "aspectRatio":"widescreen",
         "likeCount":171,
         "rating":4.63,
         "ratingCount":68,
         "viewCount":220101,
         "favoriteCount":201,
         "commentCount":22,
         "status":{
            "value":"restricted",
            "reason":"limitedSyndication"
         },
         "accessControl":{
            "syndicate":"allowed",
            "commentVote":"allowed",
            "rate":"allowed",
            "list":"allowed",
            "comment":"allowed",
            "embed":"allowed"
         }
        }
    ]
 }
}

Our live JSON-C demo lets you see the structure of the YouTube API JSON-C response for a particular API query. The demo lets you use a search form to customize and execute an API query. It will display the API request URL for the query as well as a formatted response that shows how information is presented in the API response.

Appendix A - Comparing JSON and JSON-C feeds examines the differences between these two feed formats in more detail. This section may be useful to developers who are selecting a feed format to use in their applications or to developers who are already familiar with other feed formats and want to understand the differences in the JSON-C feeds.

Requesting JSON-C feeds

To request a JSON-C response, set the alt parameter value to jsonc in your API request. For example, the request below retrieves a JSON-C feed listing search results matching the term "surfing":

https://gdata.youtube.com/feeds/api/videos?q=surfing&v=2&alt=jsonc

If you want to have the API response sent directly to a callback function, also include the callback parameter in your request as shown below:

https://gdata.youtube.com/feeds/api/videos?q=surfing&v=2&alt=jsonc&callback=functionName

When requesting JSON-C responses, you can use any of the standard Google Data API query parameters or custom YouTube API parameters described in the YouTube API Reference Guide.

Specifying an API version number

JSON-C responses are only supported in version 2 of the API. As such, any request to retrieve a JSON-C feed must either set the v query parameter value to 2 (v=2) or set the GData-Version HTTP request header to 2.

Supported feed types

GET operations

The API is capable of returning a JSON-C response for any GET operation. However, even though the API can return a JSON-C feed for any GET operation, only the feed types listed below are currently fully supported. The JSON-C formats of other feed types are likely to change without notice before those feeds are officially supported.

  • Video feeds – This category includes video search results, related videos, and user uploads.
  • Playlist feeds – This category includes playlist search results, feeds that list all of a user's playlists, and feeds that list the entries in a single playlist.
  • Favorite video feeds – This category includes feeds that list a user's favorite videos.
Important: The only officially supported JSON-C feeds are video feeds, playlist feeds and favorite video feeds. The API server should return an error if you try to retrieve an unsupported feed in JSON-C format.

POST and PUT operations

You can also use JSON-C to perform the following POST or PUT operations:

  • Inserting or updating a video
  • Adding a favorite video
  • Inserting or updating a playlist
  • Inserting a playlist entry

If a user is authorized to post new entries to a feed, the feed will contain the canPost property, which will have a value of true. In addition, if a user is authorized to update an entry in a feed, the entry will contain the canEdit property, which will have a value of true.

Note that a video entry will only contain the canEdit property if you retrieve the currently authorized user's uploaded videos feed or if you directly retrieve a video entry from that feed. For example, if the currently authorized user is the owner of the video with the id value of 0123456789Z, the feed entry for that video will contain the canEdit property when it is retrieved from either of these URLs:

https://gdata.youtube.com/feeds/api/users/default/uploads?v=2&alt=jsonc
https://gdata.youtube.com/feeds/api/users/default/uploads/0123456789Z?v=2&alt=jsonc

However, the entry for the video will not contain the canEdit property if the entry appears in another video feed, such as a search results feed, or if you retrieve the entry directly from another URL:

https://gdata.youtube.com/feeds/api/videos?q=0123456789Z&v=2&alt=jsonc
https://gdata.youtube.com/feeds/api/videos/0123456789Z&v=2&alt=jsonc

DELETE operations

Finally, your JSON-C application can perform any DELETE operation. While the API returns an HTTP 200 response code for successful DELETE requests, it does not include a document in the body of the API response regardless of the requested response format (XML, JSON-C, etc.). As such, the response format is only relevant for a DELETE request if the request fails, in which case any error message that the API returns will be in the requested response format.

Processing JSON-C feeds

The following sections show sample API responses for the different operations that support JSON-C feeds. The Using JSON with Google Data APIs document provides additional guidelines for processing API responses.

  1. Videos
  2. Variables in the upload request
  3. Favorite videos
  4. Playlists feeds (lists of playlists)
  5. Playlist feeds (contents of a single playlist)

In the feeds, each JSON property links to the XML element definition in the YouTube API Reference Guide that most closely correlates with that property and its value. Please note the following characteristics of these links:

  • A JSON-C property's name may differ from the name of the XML tag that it resembles. For example, in a playlist search feed, the JSON-C description and size properties correspond to the <summary> and <yt:countHint> tags in XML responses.

  • A JSON-C property may correspond to an attribute of an XML tag and not to the tag itself. For example, in a video search result, the favoriteCount property corresponds to the <yt:statistics> tag's favoriteCount attribute.

  • A JSON-C property name may map to the value of one XML element, and that property's value may, in turn, map to another XML element. For example, the JSON-C content property's value is an object that maps a key to a URL. The key is the value of the <media:content> tag's yt:format attribute, and the URL is the value of the same tag's url attribute.

This section explains the YouTube API's JSON-C format for video feeds. Video feeds include video search results, related video feeds, standard feeds, and feeds of a specific user's uploaded videos.

The API request below retrieves a search results feed. It queries for the first video matching the query term "GoogleDevelopers". For more information about the API's video search functionality, see the Developer's Guide section explaining API Query Parameters.

https://gdata.youtube.com/feeds/api/videos?
    q=GoogleDevelopers
    &max-results=1
    &v=2
    &alt=jsonc

This request yields the following response:

{"apiVersion":"2.0",
 "data":{
    "updated":"2010-01-07T19:58:42.949Z",
    "totalItems":800,
    "startIndex":1,
    "itemsPerPage":1,
    "items":[
        {"id":"hYB0mn5zh2c",
         "uploaded":"2007-06-05T22:07:03.000Z",
         "updated":"2010-01-07T13:26:50.000Z",
         "uploader":"GoogleDeveloperDay",
         "category":"News",
         "title":"Google Developers Day US - Maps API Introduction",
         "description":"Google Maps API Introduction ...",
         "tags":[
            "GDD07","GDD07US","Maps"
         ],
         "thumbnail":{
            "default":"http://i.ytimg.com/vi/hYB0mn5zh2c/default.jpg",
            "hqDefault":"http://i.ytimg.com/vi/hYB0mn5zh2c/hqdefault.jpg"
         },
         "player":{
            "default":"https://www.youtube.com/watch?v\u003dhYB0mn5zh2c",
            "mobile":"https://m.youtube.com/details?v\u003dhYB0mn5zh2c"
         },
         "content":{
            "1":"rtsp://v5.cache3.c.youtube.com/CiILENy.../0/0/0/video.3gp",
            "5":"http://www.youtube.com/v/hYB0mn5zh2c?f...",
            "6":"rtsp://v1.cache1.c.youtube.com/CiILENy.../0/0/0/video.3gp"
         },
         "duration":2840,
         "aspectRatio":"widescreen",
         "likeCount":171,
         "rating":4.63,
         "ratingCount":68,
         "viewCount":220101,
         "favoriteCount":201,
         "commentCount":22,
         "status":{
            "value":"restricted",
            "reason":"limitedSyndication"
         },
         "accessControl":{
            "syndicate":"allowed",
            "commentVote":"allowed",
            "rate":"allowed",
            "list":"allowed",
            "comment":"allowed",
            "embed":"allowed"
         }
        }
    ]
 }
}

Adding a video

The following steps explain how to add a video using the API's direct, resumable uploading process. Please see the Resumable uploads section of the Developer's Guide for more information about resumable uploads. Note that browser-based uploading is currently not supported for JSON-C applications.

Step 1 – Uploading video metadata

To begin a resumable upload, send a POST request that contains the video filename and the metadata for the video to the following URL. The authentication token that you submit with the request needs to identify the currently logged-in user.

http://uploads.gdata.youtube.com/resumable/feeds/api/users/default/uploads?alt=jsonc&v=2

The example below shows the format of an API request that uses the OAuth 2.0 authentication scheme for resumable uploading:

POST /resumable/feeds/api/users/default/uploads?alt=jsonc&v=2 HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY
Content-Length: CONTENT_LENGTH
Content-Type: application/json; charset=UTF-8
Slug: VIDEO_FILENAME

API_request

You must provide several values in the POST request. Those values are highlighted in bold text in the example above. The following list explains how to populate each value:

  • ACCESS_TOKEN - This value contains the authentication token for your request. The token will either be an OAuth 2.0 access token, an OAuth 1.0 access token, a ClientLogin token, an AuthSub single-use token, or an AuthSub session token.

  • DEVELOPER_KEY - This value uniquely identifies the application that is submitting the request to upload the video. Please visit http://code.google.com/apis/youtube/dashboard/ to get a developer key.

  • CONTENT_LENGTH - This value contains the length, in bytes, of the entire body of the POST request.

  • API_Request - This value contains information about the uploaded video file in the form of a JSON-C entry.

The following example shows a POST request that has all of these values populated with the exception of the access (authentication) token:

POST /resumable/feeds/api/users/default/uploads?alt=jsonc&v=2 HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 1941255
Slug: my_file.mp4

{
  "data":{
    "privacy":"private",
    "title":"Updated video category",
    "category":"Comedy",
    "description":"The old description was not as good as this one.",
    "tags":["updating","videos"],
    "recorded":"2007-01-24",
    "location":"San Francisco, CA",
    "geoCoordinates":{
      "latitude":37.80558,
      "longitude": -122.423315
    },
    "accessControl":{
      "syndicate":"allowed",
      "embed":"allowed",
      "rate":"allowed",
      "list":"allowed",
      "comment":"moderated",
      "commentVote":"allowed",
      "group":{
        "friends":{
          "comment":"allowed"
        }
      }
    }
  }
}

Step 2 – Extracting the upload URL from the API response

When you submit an API request to upload video metadata, the API response will contain a Location header, which identifies the URL that you will use to upload the actual video file. You need to extract this URL and use it to upload the video file.

The example below shows a sample API response to a request to upload video metadata for a resumable upload:

HTTP/1.1 200 OK
Location: http://uploads.gdata.youtube.com/resumableupload/AF8GKF...0Glpk0Aw
Date: Fri, 04 Dec 2009 16:14:30 GMT
Pragma: no-cache
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

Step 3 – Uploading the video file

After extracting the upload URL from the API response, you need to upload the actual video file content. You will upload the video content to the URL extracted in step 2. The example below demonstrates the format of the video upload request. Note that you do not need to provide any authentication headers in this step.

PUT <upload_url> HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: <video_content_type>
Content-Length: <content_length>

<Binary_file_data>

Variables in the upload request

You must provide several values in the PUT request. Those values are highlighted in bold text in the example above. The following list explains how to populate each value:

  • upload_url – This value is the URL that you extracted in step 2 from the Location header of the API response for the metadata upload request.

  • video_content_type – This value specifies the MIME type of the uploaded video file. The MIME type can be a video media type, such as video/mpeg or video/mp4, or it can be application/octet-stream.

  • content_length – This value specifies the length, in bytes, of the entire body of the PUT request.

  • Binary File Data – This value contains the binary code for the video file that you are uploading.

The following example shows a PUT request that has all of these values populated with the exception of the binary file data:

PUT /resumableupload/AF8GKF...0Glpk0Aw HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: video/mpeg
Content-Length: 124905
<Binary File Data>

Step 4 - Completing the upload process

When you submit a request to upload the video content for a resumable upload, one of two scenarios could occur:

  • If the upload completes, then the API returns a response indicating whether the upload succeeded or failed.

    • For a successful upload, the API returns an Atom entry that contains information about the uploaded video. The entry has the same format as an entry in a user's uploaded videos feed, and the response may contain properly escaped HTML tags. The Checking the status of an uploaded video section explains how to check the status of the uploaded video.

    • For an unsuccessful upload, the response contains an error response that helps to explain the cause of the upload failure.

  • If the upload fails because the connection between the YouTube server and your application is lost, then your application will not receive an API response. In this case, you may be able to resume the upload from the point of the interruption. The following steps explain how to resume a video upload:

    1. Checking the current status of an upload
    2. Resuming a resumable upload

For more information about resumable uploads, including instructions for checking the status of a resumable upload and for resuming an interrupted upload, please see the Developer's Guide.

Updating a video

To update a video, send an authenticated PUT request to the following URL, replacing VIDEO_ID with the appropriate value:

https://gdata.youtube.com/feeds/api/users/default/uploads/VIDEO_ID

The body of the PUT request is a JSON document that contains information about the video. You can include any of the following properties in your request. Required properties are marked with an asterisk (*). Note that each property name links to the

Note that excluding a property will delete the information that already exists for that video. For example, if a video is marked as private and your request does not include the privacy property, the video will become public. Similarly, if you do not specify access control settings when updating a video, YouTube will restore the default access control settings for that video. If you only specify some access control settings in an update, the unspecified controls will be restored to their default settings.

Note: To avoid the inadvertent loss of data, we recommend that when updating a video, you retrieve the video data, modify the properties that you are updating, and then include the complete set of video data in the body of your PUT request.

The following sample request shows the format of a JSON-C request to update a private video:

Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "privacy":"private",
    "title":"Updated video category",
    "category":"Comedy",
    "description":"The old description was not as good as this one.",
    "tags":["updating","videos"],
    "recorded":"2007-01-24",
    "location":"San Francisco, CA",
    "geoCoordinates":{
      "latitude":37.80558,
      "longitude": -122.423315
    },
    "accessControl":{
      "syndicate":"allowed",
      "embed":"allowed",
      "rate":"allowed",
      "list":"allowed",
      "comment":"moderated",
      "commentVote":"allowed",
      "group":{
        "friends":{
          "comment":"allowed"
        }
      }
    }
  }
}

Deleting a video

To delete a video, send an authenticated DELETE request to the following URL, replacing VIDEO_ID with the appropriate value:

https://gdata.youtube.com/feeds/api/users/default/uploads/VIDEO_ID

The sample request below would delete the video that has an ID of 914IMX9RSTE.

DELETE /feeds/api/users/default/uploads/914IMX9RSTE HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Deleted videos are typically removed from a user's public uploaded videos feed within a couple of hours.

Favorite videos

This section explains the YouTube API's JSON-C format for favorite video feeds. While favorite video feeds are almost identical to other video feeds, there are a few important differences:

  • For each favorite video, the created property specifies the date and time when the user marked the video as a favorite.
  • For each favorite video, the author property identifies the user who added the favorite video.
  • Each item in the feed contains a video property, and all other information about the item itself are nested below that property.

The following API request retrieves the first video in a particular user's favorite videos feed. For more information about retrieving favorite videos via the API, see the Favorite Videos section of the Developer's Guide.

https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/favorites?
    &v=2
    &max-results=1
    &alt=jsonc

The request above yields the following response:

{"apiVersion":"2.0",
 "data":{
    "totalResults":9,
    "startIndex":1,
    "itemsPerPage":1,
    "items":[
       {"id": "vjVQa1PpcFP9NzIof2dlerf1uOCvDpkm9zDBp7nuzOo",
        "created":"2009-07-24T19:15:20.000Z",
        "author":"GoogleDevelopers",
        "video":{
           "id":"S5aJAaGZIvk",
           "uploaded":"2009-05-29T18:34:08.000Z",
           "updated":"2010-01-07T19:14:37.000Z",
           "uploader":"GoogleDevelopers",
           "category":"Tech",
           "title":"Google I/O 2009 - Keynote Day 1 (full)",
           "description":"Google I/O 2009 - Keynote Day 1 full version",
           "tags":["google","Google I/O","developer conference","javascript"],
           "thumbnail":{
              "default":"http://i.ytimg.com/vi/S5aJAaGZIvk/default.jpg",
              "hqDefault":"http://i.ytimg.com/vi/S5aJAaGZIvk/hqdefault.jpg"
           },
           "player":{
              "default":"https://www.youtube.com/watch?..."
           },
           "content":{
              "1":"rtsp://v2.cache2.c.youtube.com/CioLENy.../0/0/0/video.3gp",
              "5":"http://www.youtube.com/v/s0Pw7vKtqpo?f...",
              "6":"rtsp://v8.cache2.c.youtube.com/CioLENy.../0/0/0/video.3gp"
           },
           "duration":204,
           "likeCount":11231,
           "rating":4.86,
           "ratingCount":6267,
           "viewCount":5263380,
           "favoriteCount":16008,
           "commentCount":4555,
           "accessControl":{
              "syndicate":"allowed",
              "commentVote":"allowed",
              "rate":"allowed",
              "list":"allowed",
              "comment":"allowed",
              "embed":"allowed"
           }
        }
       }
    ]
 }
}

Adding a favorite video

To add a favorite video, you must provide the video ID that YouTube uses to uniquely identify that video. The following request shows the URL and format of a JSON-C request to add a video to the logged-in user's list of favorite videos:

POST /feeds/api/users/default/favorites?alt=jsonc HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "video":{
      "id":"6aiCJubxiGI"
    }
  }
}

Deleting a favorite video

In a favorite videos feed, the FAVORITE_VIDEO_ID is specified in each feed item's id property. You need to use that value to delete the favorite video. (The id property contained with each feed item's video property specifies the YouTube video ID of the favorite video.) The feed excerpt below shows the correct value to use when deleting a favorite video:

"items": [
 {
  "id": "vjVQa1PpcFP9NzIof2dlerf1uOCvDpkm9zDBp7nuzOo", // Yes! Favorite video ID!
  "created": "2010-04-01T19:12:04.000Z",
  "author": "YTUser",
  "video": {
    "id": "dTCm8tdHkfI", // No. This is the video ID. :(
    "uploaded": "2010-02-06T00:12:19.000Z",
    ...

To delete a favorite video, send an authenticated DELETE request to the following URL, replacing FAVORITE_VIDEO_ID with the appropriate value:

https://gdata.youtube.com/feeds/api/users/default/favorites/FAVORITE_VIDEO_ID

The sample request below would delete the favorite video that has an ID of vjVQa1PpcFP9NzIof2dlepBZXMLpGfPV9cVwl1YEuyM.

DELETE /feeds/api/users/default/favorites/vjVQa1PpcFP9NzIof2dlepBZXMLpGfPV9cVwl1YEuyM HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

A playlist is a collection of videos that can be viewed sequentially and shared with other users. A playlist can contain up to 200 videos, and YouTube does not limit the number of playlists that each user creates. A user can view and edit his list of playlists on his account page. Playlists can be public or private. A playlist will be publicly visible to other users unless it has been explicitly been designated as a private playlist.

The YouTube Data API enables users to retrieve, create, modify and delete playlists.

Retrieving a playlists feed

This section explains the YouTube API's JSON-C format for playlists feeds. A playlists feeds contain a list of playlists. They include playlist search results as well as feeds that contain a specific user's playlists.

The following API request searches for the first two playlists matching the query term "GoogleDevelopers". For more information about the API's playlist search functionality, including a list of query parameters that you can use in a playlist search request, see the Searching for Playlists section of the Developer's Guide.

https://gdata.youtube.com/feeds/api/playlists/snippets?
    q=GoogleDevelopers
    &max-results=2
    &v=2
    &alt=jsonc

This request yields the following response:

{"apiVersion":"2.0",
 "data":{
    "totalResults":347,
    "startIndex":1,
    "itemsPerPage":2,
    "items":[
       {"id":"4DAEFAF23BB3CDD0",
        "created":"2008-12-09T20:23:06.000Z",
        "updated":"2010-01-04T02:56:19.000Z",
        "author":"GoogleDevelopers",
        "title":"Google Web Toolkit Developers",
        "description":"Developers talk about using Google Web Toolkit ...",
        "tags":[
           "google","web","toolkit","developers","gwt"
        ],
        "size":12
       },
       {"id":"586D322B5E2764CF",
        "created":"2007-11-13T19:41:21.000Z",
        "updated":"2010-01-04T17:41:16.000Z",
        "author":"GoogleDevelopers",
        "title":"Android",
        "description":"Demos and tutorials about the new Android platform.",
        "tags":[
           "android","google","developers","mobile"
        ],
        "size":32
       }
    ]
 }
}

You can also retrieve a specific user's playlists in JSON-C format:

  • To request a feed of the currently logged-in user's playlists, send a GET request to the following URL. Note: For this request, you must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.

    https://gdata.youtube.com/feeds/api/users/default/playlists?v=2&alt=jsonc
  • To request a feed of another user's playlists, send a GET request to the following URL. This request does not require user authorization.

    https://gdata.youtube.com/feeds/api/users/userId/playlists?v=2&alt=jsonc

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

Adding a playlist

To create a playlist, you must provide a title and description for the playlist. The private tag, which is optional, indicates whether the playlist will be publicly visible. (By default, playlists are visible to other users.)

The following request provides the URL and shows the JSON-C format for creating a new playlist:

POST /feeds/api/users/default/playlists?alt=jsonc HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "title":"Sample foo playlist",
    "description":"This is not a real foo playlist, but a sample foo playlist.",
    "tags":["dumptruck","airbag"],
    "privacy":"private"
  }
}

The API will return an HTTP 201 response code if the request is successful, and the response will include the playlist ID of the new playlist:

{
  "apiVersion": "2.0",
  "data": {
    "privacy": "private",
    "id": "FDC7BD87F75C7752",
    "created": "2010-03-04T01:08:04.000Z",
    "updated": "2010-03-04T01:08:04.000Z",
    "author": "GoogleDevelopers",
    "title": "Sample foo playlist",
    "description": "This is not a real foo playlist, but a sample foo playlist.,
    "tags": [
      "dumptruck",
      "airbag"
    ],
    "size": 0
  }

Updating a playlist

A playlist owner can update the title, description, and public/private status of that playlist. To update a playlist, send an authenticated PUT request to the following URL, replacing PLAYLIST_ID with the appropriate value:

https://gdata.youtube.com/feeds/api/users/default/playlists/PLAYLIST_ID

The following sample request illustrates the format of a JSON-C request to modify a playlist:

PUT /feeds/api/users/default/playlists/PLAYLIST_ID?alt=jsonc HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "title":"New Foo Title",
    "description":"New foo description",
    "tags":["beanbag","baseball"],
    "privacy":"private"
  }
}

Deleting a playlist

When you retrieve a list of a user's playlists, each item in the result set encapsulates information about a single playlist. The id property for each item identifies the playlist ID that YouTube uses to uniquely identify the playlist.

To delete a playlist, send an authenticated DELETE request to the following URL, replacing PLAYLIST_ID with the appropriate value:

https://gdata.youtube.com/feeds/api/users/default/playlists/PLAYLIST_ID

The sample request below would delete the playlist that has an ID of FDC7BD87F75C7752.

DELETE /feeds/api/users/default/playlists/FDC7BD87F75C7752 HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Playlist feeds (contents of a single playlist)

This section explains the YouTube API's JSON-C format for a playlist feed, which lists the videos in a playlist. It also explains how to add videos to a playlist or remove videos from a playlist.

Retrieving a playlist feed

The API request below retrieves the first video from a specific playlist. (To retrieve all of the videos in the playlist, the request would omit the max-results query parameter.)

https://gdata.youtube.com/feeds/api/playlists/4DAEFAF23BB3CDD0?
    alt=jsonc
    &v=2

The request above yields the following response:

{"apiVersion":"2.0",
 "data":{
    "id":"4DAEFAF23BB3CDD0",
    "author":"GoogleDevelopers",
    "title":"Google Web Toolkit Developers",
    "description":"Developers talk about Google Web Toolkit ...",
    "tags":[
       "google","web","toolkit","developers","gwt"
    ],
    "thumbnail":{
       "sqDefault","http://i.ytimg.com/ELox9yPRu9c/default.jpg",
       "hqDefault","http://i.ytimg.com/ELox9yPRu9c/hqdefault.jpg"
    },
    "content":{
       "5":"http://www.youtube.com/ep.swf?id\u003d4DAEFAF23BB3CDD0"
    },
    "totalResults":12,
    "startIndex":1,
    "itemsPerPage":1,
    "items":[
       {"id":"3EF9D101C681F3EA",
        "position":1,
        "author":"GoogleDevelopers",
        "video":{
           "id":"ELox9yPRu9c",
           "uploaded":"2008-12-09T22:00:54.000Z",
           "updated":"2010-01-07T12:33:40.000Z",
           "uploader":"GoogleDevelopers",
           "category":"Education",
           "title":"GWT Developers - Whirled",
           "description":"Michael talks about Whirled ...",
           "tags":[
              "google","web","toolkit","developers","plidC94A1F02A95E9A2A"
           ],
           "thumbnail":{
              "default":"http://i.ytimg.com/vi/ELox9yPRu9c/default.jpg",
              "hqDefault":"http://i.ytimg.com/vi/ELox9yPRu9c/hqdefault.jpg"
           },
           "player":{
              "default":"https://www.youtube.com/watch?..."
           },
           "content":{
              "1":"rtsp://v8.cache7.c.youtube.com/CiULENy.../0/0/0/video.3gp",
              "5":"http://www.youtube.com/v/ELox9yPRu9c?f...",
              "6":"rtsp://v6.cache6.c.youtube.com/CiULENy.../0/0/0/video.3gp"
           },
           "duration":160,
           "aspectRatio":"widescreen",
           "rating":5.0,
           "ratingCount":36,
           "likeCount":64,
           "viewCount":12169,
           "favoriteCount":25,
           "commentCount":115,
           "contentRating": {
             "HK":"1",
             "KR":"1"
           },
           "accessControl":{
              "syndicate":"allowed",
              "commentVote":"allowed",
              "rate":"allowed",
              "list":"allowed",
              "comment":"allowed",
              "embed":"allowed"
           }
        }
       }
    ]
 }
}

For more information about retrieving playlist information, see the Playlists section of the Developer's Guide.

Adding a video to a playlist

To add a video to a playlist, send an API request that identifies the unique ID that YouTube assigned to the playlist as well as the unique ID that YouTube assigned to the video. By default, the newly added video will be added to the end of a playlist. To insert a video into a different spot in the playlist, include the position property in your request and set its value to the position where the video should appear in the playlist.

The following request provides the URL and illustrates the JSON-C format for adding a video to the beginning of a playlist:

POST /feeds/api/playlists/PLAYLIST_ID?alt=jsonc HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "video":{
      "id":"6aiCJubxiGI",
      "position": 1
    }
  }
}

Editing video information in a playlist

A user can update the order in which a video appears in a playlist that the user created. To update the position of a playlist entry, send an authenticated PUT request to the following URL, replacing PLAYLIST_ID and PLAYLIST_ENTRY_ID with the appropriate values:

https://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID

In a playlist feed, the id property of the data property specifies the PLAYLIST_ID. The id property of each item in the items array specifies the PLAYLIST_ENTRY_ID for a video in that playlist. The JSON-C feed excerpt below illustrates this point:

{"apiVersion":"2.0",
 "data":{
    "id":"4DAEFAF23BB3CDD0", <!-- PLAYLIST_ID -->
    "author":"GoogleDevelopers",
    "title":"Google Web Toolkit Developers",
    ...
    "items":[
       {"id":"3EF9D101C681F3EA",  <!-- PLAYLIST_ENTRY_ID -->
        "position":1,
        "author":"GoogleDevelopers",
        "video":{
           "id":"ELox9yPRu9c", <!-- VIDEO_ID -->
           ..."uploaded":"2008-12-09T22:00:54.000Z",
        }
       }
    ]
  }
}

For example, the following request would move a video to the third spot in a playlist:

PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID?alt=jsonc HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

{
  "data":{
    "position":3
  }
}

Deleting a video from a playlist

When you retrieve a list of videos in a playlist, each item in the result set encapsulates information about a single video in the playlist. The id property for the feed identifies the playlist ID that YouTube uses to uniquely identify the playlist. In addition, the id property for each item identifies the playlist entry ID that YouTube uses to uniquely identify that entry.

To delete a video from a playlist, send an authenticated DELETE request to the following URL, replacing PLAYLIST_ID and PLAYLIST_ENTRY_ID with the appropriate values:

https://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID

The JSON-C feed excerpt below is from a playlist feed. It shows these two values in bold text:

{
 'apiVersion': '2.0',
 'data': {
   'id': '4DAEFAF23BB3CDD0', // This is the playlist ID
   'author': 'GoogleDevelopers',
   'title': 'Google Web Toolkit Developers',
   'description': 'Hear developers talk ...',
   'tags': ['google','web','toolkit','developers','gwt'],
   'content': {
     '5': 'http://www.youtube.com/ep.swf?id=4DAEFAF23BB3CDD0'
   },
   'totalItems': 12,
   'startIndex': 1,
   'itemsPerPage': 25,
   'items': [
     {
       'id': '3EF9D101C681F3EA', // This is the playlist entry ID
       'position': 1,
       'author': 'GoogleDevelopers',
       'video': {
         'id': 'ELox9yPRu9c', // This is not the ID you are looking for
       ...

For example, the following request would delete the video from the playlist shown in the JSON-C feed excerpt above:

DELETE /feeds/api/playlists/4DAEFAF23BB3CDD0/3EF9D101C681F3EA HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Appendix A - Comparing JSON and JSON-C feeds

Like other Google Data APIs, the YouTube API offers JSON-formatted responses to allow developers a basic level of access to API responses from JavaScript and other clients. The API generates a JSON feed by converting an XML feed according to the rules explained in the Using JSON with Google Data APIs document. During this process, all of the information in the Atom feed is preserved in the generated feed, and so the Atom-to-JSON conversion is characterized as a lossless conversion.

Like its JSON feeds, the API's JSON-C feeds enable applications to integrate YouTube functionality without having to parse XML. However, JSON-C feeds differ from JSON feeds in a number of important ways:

  • Whereas all Google Data APIs use the same process to convert Atom feeds to JSON, the Atom-to-JSON-C conversion process is customized on an API-by-API basis. In addition, the process is not a lossless conversion, which means that JSON-C feeds can exclude duplicate, irrelevant or easily calculated values. As a result, JSON-C responses are more compact and can be processed more efficiently than JSON responses.

  • Unlike the API's JSON feeds, the JSON-C feeds do not preserve XML namespaces or schema information. The JSON-C feeds also do not preserve the relationships between XML tags and attributes. These differences allow information in JSON-C feeds to be structured more logically than in JSON responses.

  • JSON-C feeds minimize the number of JSON objects that are created in favor of simple properties. This benefit stems from the fact that JSON-C feeds classify values (as objects, arrays or primitives) based on the way that the values are actually used by a particular service. By reducing the number of JSON objects, JSON-C feeds again realize a more natural, logical structure than JSON feeds while reducing overall memory footprint.

The following sections discuss these differences in more detail and provide examples to illustrate the differences between JSON-C feeds and JSON (or Atom) responses:

  1. Excluding duplicate, irrelevant or easily calculated values
  2. Avoiding XML namespaces, schemas and element relationships
  3. Reducing JSON objects to limit memory footprint

Excluding duplicate, irrelevant or easily calculated values

Since the Atom-to-JSON-C conversion is not a lossless one, JSON-C feeds may exclude elements to avoid both verbosity and repetition. This rule is evident in the way that the categories and keywords for a video are identified in API responses. Whereas Atom and JSON feeds specify the category and keywords for a video twice, the JSON-C feed only provides that information once, as shown in the examples below:

Atom (XML):
<category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
  term='Sports' label='Sports'/>
<category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat' term='dog'/>
<category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat' term='catch'/>
<category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat' term='frisbee'/>
...
<media:group>
  <media:category label='Sports'
    scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Sports</media:category>
  <media:keywords>dog, catch, frisbee</media:keywords>
  ...
<media:group>

JSON:
"category":[
  {"scheme":"http://gdata.youtube.com/schemas/2007/categories.cat",
   "term":"Sports", "label":"Sports"},
  {"scheme":"http://gdata.youtube.com/schemas/2007/keywords.cat", "term":"dog"},
  {"scheme":"http://gdata.youtube.com/schemas/2007/keywords.cat", "term":"catch"},
  {"scheme":"http://gdata.youtube.com/schemas/2007/keywords.cat", "term":"frisbee"}
],
"media$group": {
  "media$category":[{"$t":"Sports", "label":"Sports",
    "scheme":"http://gdata.youtube.com/schemas/2007/categories.cat"],
  "media$keywords":{"$t":"dog, catch, frisbee"}
}

JSON-C:
"category":"Sports",
"tags":["dog", "catch", "frisbee"]

Avoiding XML namespaces, schemas and element relationships

JSON-C feeds do not preserve XML namespaces or schema information. This fact is evident in the way that Atom, JSON and JSON-C feeds identify the YouTube user who uploaded a video:

Atom:
<media:group>
  <media:credit role='uploader' scheme='urn:youtube'>GoogleDevelopers</media:credit>
</media:group>

JSON:
"media$group":{
  "media$credit":[{"$t":"GoogleDevelopers", "role":"uploader", "scheme":"urn:youtube"}]
}

JSON-C:
"uploader":"GoogleDevelopers"

In addition, JSON-C feeds do not always preserve the relationship between XML tags and attributes during the conversion process. The conversion of the <media:content> XML tag, which is defined in the Media RSS schema, illustrates this behavior. In the YouTube API's Atom feed, this XML tag identifies the URL for a video file, the format of the video file, the length of the video and so forth:

<media:content url='http://www.youtube.com/v/fcqssn8JuX0&amp;f=videos...'
    type='application/x-shockwave-flash' medium='video' isDefault='true'
    expression='full' duration='108' yt:format='5'/>
<media:content url='rtsp://rtsp2.youtube.com/ckQLENy73w...==/0/0/0/video.3gp'
    type='video/3gpp' medium='video'
    expression='full' duration='108' yt:format='1'/>

As shown, the values of the medium, expression and duration attributes may be the same for each <media:content> tag. This information is all preserved in the JSON feed since the Atom-to-JSON conversion is a lossless one:

"media$content":[
  {"url":"http://www.youtube.com/v/fcqssn8JuX0...",
   "type":"application/x-shockwave-flash",
   "medium":"video",
   "isDefault":"true",
   "expression":"full",
   "duration":"108",
   "yt$format":"5"},
  {"url":"rtsp://rtsp2.youtube.com/ckQLENy73w...==/0/0/0/video.3gp",
   "type":"video/3gpp",
   "medium":"video",
   "expression":"full",
   "duration":"108",
   "yt$format":"1"}]

The JSON-C feed formats the information much differently:

"content":{
  "5":"http://www.youtube.com/v/fcqssn8JuX0..."
  "1":"rtsp://rtsp2.youtube.com/ckQLENy73w...==/0/0/0/video.3gp"
},
"duration":"108"

The JSON-C feed shows a number of differences:

  • It uses the value of the yt:format XML attribute as a key for the different content URLs available for the video. These values map to specific video formats as described in the Reference Guide, so the type attribute is superfluous.

  • In the Atom and JSON responses, the <media:content> tag's duration attribute is repeated for each content URL. However, in the JSON-C response, the value is communicated only once as the value of the duration property.

  • In addition to the type attribute, the medium, isDefault and expression values are also excluded from the JSON-C response since they are always the same for every video. (The default media resource is always the embeddable player SWF URL for the video, and the values of the medium and expression attributes are always video and full, respectively.)

Reducing JSON objects to limit memory footprint

Since JSON-C feeds do not mirror the structure of Atom feeds, they can flatten some complex elements to minimize the size of the JSON-C feed in browser memory. The example presented earlier that showed how the JSON-C feed avoids repeating the category and keyword tags for a video reflects this behavior.

The JSON feed's category property contains an array of objects, where each object identifies either the category or a single keyword associated with the video. In addition, the response also contains the media$group property, and its value is an object that, in turn, contains the media$category and media$keywords properties. And those properties repeat the category and keywords already identified by the category property.

By contrast, the JSON-C feed contains only two properties, category and tags. The value of the category property is a string, and the value of the tags is an array of strings.

This difference between the JSON and JSON-C feeds is also evident in the way that the feeds identify the owner (author) of a video. In JSON feeds, each author property is an object that contains name and uri properties. In JSON-C feeds, however, this code is reduced to the author property and its string value.

JSON:
"author":[
 {
   "name":{"$t":"GoogleDevelopers"},
   "uri":{"$t":"https://gdata.youtube.com/feeds/api/users/GoogleDevelopers"}
 }
]

JSON-C:
"author":"GoogleDevelopers"

Appendix B - Video ratings in JSON-C feeds

YouTube currently uses a rating system that lets users indicate whether they like or dislike a video. However, until March 2010, YouTube used a 1-5 rating system in which 1 was the lowest rating that could be given. The YouTube API currently supports both rating systems and uses different XML elements to provide rating information for each system:

The API communicates video ratings using the following properties:

  • likeCount – The number of voters who liked the video. This tally includes ratings submitted using the 1-5 rating system.
  • ratingCount – The total number of voters who have rated the video using either rating system. The number of voters who disliked the video can be calculated by subtracting the likeCount from the ratingCount.
  • rating – The average rating, calculated on a 1-5 scale, for the video. For ratings submitted using the like-or-dislike system, positive ratings are assigned a score of 5, and negative ratings are assigned a score of 1.

The JSON-C excerpt below shows how these properties will appear in a JSON-C video feed entry. The same properties also appear in favorite video feed entries and playlist feed entries.

{
 "data": {
   "id": "XrMTsMDUle8",
   ...
   "likeCount": 143,
   "ratingCount": 171,
   "rating": 4.24,
   ...
 }
}

Revision History

September 11, 2013

This update contains the following changes:

  • All standard video feeds except the most_popular feed have been deprecated. In response to requests for other feeds, the API will return the most_popular feed with a default time parameter value of today. The most_popular feed also supports a time parameter value of all_time, so if you try to retrieve a deprecated feed for that time period, the API will return a feed of the most popular videos of all time. In addition, if your request for another feed specifies a region or category, the API will return the most_popular feed for that region or category.

  • YouTube's video responses feature has been retired as explained in this announcement.

February 21, 2012

This update contains the following changes:

  • The supported feed types section has been updated to more clearly explain when a video entry might contain the canEdit property, which indicates that the currently authenticated user is able to edit that video. Specifically, a video entry will only contain the canEdit property if you retrieve the currently authorized user's uploaded videos feed or if you directly retrieve a video entry from that feed.

December 15, 2011

This update contains the following changes:

  • The sample feed in the Retrieving a playlist feed section has been updated to show that the feed will include a thumbnail property that identifies the thumbnail images for the playlist.

  • The Adding a video to a playlist section has been updated to note that you can now send a single request to add a video to a playlist and specify the position where the video should appear in that list. Previously, you needed to add the video to the playlist, and then update the playlist entry to specify the desired playlist position.

August 2, 2011

This update contains the following changes:

  • The example in the Retrieving a playlist feed section has been updated to show that each item in the items array will contain an id property. Each item in the array identifies a video in the playlist, and the id property itself specifies the playlist entry ID for that video. You need to specify the playlist entry ID (as well as the playlist ID) to either update or delete a playlist entry.

  • The Editing video information in a playlist section contains a feed excerpt that highlights the playlist ID and playlist entry ID that would need to be extracted to update a playlist entry.

June 17, 2011

This update contains the following changes:

  • The document has been updated to reflect the fact that the API supports HTTPS for nearly all API requests. If you send an API request to https://gdata.youtube.com, then the API response will also specify HTTPS URLs in property values that point to other API feeds.

    However, please note that HTTPS is not supported for the following requests:

    • Requests to upload videos to the production API servers should still be sent to http://uploads.gdata.youtube.com.
    • Requests to upload videos to the staging server should still be sent to http://uploads.stage.gdata.youtube.com.
    • All other API requests to the staging server should still be sent to http://stage.gdata.youtube.com.

    In addition, note that AuthSub and OAuth authentication tokens for the http://gdata.youtube.com and https://gdata.youtube.com scopes are interchangeable. As such, if you have already obtained an AuthSub or OAuth token for the http://gdata.youtube.com scope, you can use that same token to authenticate requests to https://gdata.youtube.com.

July 13, 2010

  • The XML examples throughout the document have been updated to include a new access control setting that indicates whether a video is unlisted. Unlisted videos are not included in search results or displayed in any other way, and a user can only reach an unlisted video by entering or linking directly to the video's watch page URL.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.