YouTube

YouTube API v2.0 – Browsing with Categories and Keywords

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

This section explains how to retrieve a feed of all of the videos that are in a particular category or that are associated with a particular keyword. (YouTube uses the term "tag" to identify a keyword relevant to a video.) The examples also demonstrate how you can retrieve videos that are associated with a category and one or more keywords as well as videos that are not associated with particular categories or keywords.

Each video entry in an API response contains a series of <category> elements. Each <category> element identifies a category or keyword with which the corresponding video is associated. The element's scheme attribute indicates whether the element identifies a category or a keyword. The element's term attribute specifies the category or keyword term that you would use to locate videos as described in this section.

The YouTube Data API supports two different methods for retrieving videos that are in a particular category or that are labeled with a specific keyword or developer tag.

  • Use the following URL to retrieve videos that are in a specific category or that are labeled with a specific keyword or developer tag. The hyphen (-) in the URL is a standard Google Data API notation that indicates that the rest of the URL consists of a series of one or more tags.

    https://gdata.youtube.com/feeds/api/videos/-/category_or_tag
    

    The following example shows the URL that you would use to request videos in the "Comedy" category:

    https://gdata.youtube.com/feeds/api/videos/-/Comedy
  • Specify the category, keyword or developer tags using the category parameter in the request URL. The following example shows the URL that you would use to request videos in the "Comedy" category:

    https://gdata.youtube.com/feeds/api/videos?category=Comedy

The following guidelines provide more detail about requesting videos associated with particular categories or tags:

  • If your request specifies a category and one or more keywords or if your request does not specify a category but does specify multiple keywords, separate each individual category and keyword name with a forward slash. (If you are using the category parameter, separate the different category and tag names with a comma. (The comma must be URL-encoded in your request.) For example, you could use either of the following URLs to request videos related to the keywords "bass" and "fishing":

    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2
    
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?category=bass%2Cfishing&v=2
    
  • Your request can use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several keywords or categories. For example, if you wanted to display videos related to "bass" and "music", the most effective search might be for videos associated with the keyword "bass" but not associated with the keywords "fish" or "fishing" as shown in the example below. (Searching for videos associated with the "Music" category and the keyword "bass" might exclude instructional videos about how to play bass.)

    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2
    
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?
    category=bass%2C%2Dfish%2Dfishing&v=2

    The following example shows how to search for videos that are tagged with the keywords "Jesse" and "Ventura" and that are in either the "News" or "Sports" categories. The category names are separated by the value "%7C", which represents a URL-encoded pipe (|) character specifying that the video must be associated with one of the two categories:

    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports?v=2
    
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?category=jesse%2Cventura%2CNews%7CSports&v=2
    
  • Capitalize the names of categories and lowercase the names of keywords. For example, the following query identifies videos associated with the keyword "comedy" that are not in the "Comedy" category:

    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy?v=2
    
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?category=comedy%2C%2DComedy&v=2
    
  • If you are generating category or keyword searches automatically based on the information in an API response, specify the schema as part of the category name to clearly differentiate YouTube categories from keyword tags or developer tags. The following URLs demonstrate how to specify the schema in the category name. (Note that each URL should actually appear on one line but has been split into multiple lines for printing purposes.)

    Categories:
      URL notation:
      https://gdata.youtube.com/feeds/api/videos/-/
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fcategories.cat%7DNews?v=2
    
      category parameter:
      https://gdata.youtube.com/feeds/api/videos?category=
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fcategories.cat%7DNews&v=2
    
    Keywords:
      URL notation:
      https://gdata.youtube.com/feeds/api/videos/-/
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fkeywords.cat%7Ddog?v=2
    
      category parameter:
      https://gdata.youtube.com/feeds/api/videos?category=
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fkeywords.cat%7Ddog&v=2
    
    Developer tags:
      URL notation:
      https://gdata.youtube.com/feeds/api/videos/-/
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fdevelopertags.cat%7Dexample.com?v=2
    
      category parameter:
      https://gdata.youtube.com/feeds/api/videos?category=
        %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
        %2Fdevelopertags.cat%7Dexample.com&v=2
    
  • Always specify the schema, as explained in the previous item, if you are requesting videos associated with a particular developer tag.

pagination links

« Previous
Retrieving and Searching for Videos
Next »
API Query Parameters

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.