My favorites ▼ | English ▼ | Sign in

Sign up for Google I/O 2010 today!

YouTube APIs and Tools

YouTube logo

Developer's Guide: Data API Protocol – Searching for Channels

This section explains how to use the API to retrieve a list of channels matching a user-specified search term. YouTube could match the search term to the channel name, description or other channel-related fields. To search for channels, submit an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/channels

YouTube supports the following API query parameters for channel search:

Note: Since the query term could be matched against the channel description, the q parameter value could contain multiple words. You can also search for an exact phrase as described in the q parameter definition. However, for channel search requests, the q parameter does not support the Boolean NOT (-) and OR (|) operators.

Sample channel search request

The following API request searches for the second set of 10 channels matching the query term "soccer":

http://gdata.youtube.com/feeds/api/channels?
    q=soccer
    &start-index=11
    &max-results=10
    &v=2

This request yields the following response:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"CEEERnk_fCp7ImA9WxRUEU4."'>
  <id>tag:youtube.com,2008:channels</id>
  <updated>2008-11-19T14:10:07.744-08:00</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#channel'/>
  <title>YouTube Channels matching query: soccer</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?q=soccer&start-index=11&max-results=10&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/channels?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?q=soccer&start-index=21&max-results=10&v=2'/>   
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>6141</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>    
  <entry gd:etag='W/"CEEERnk_fCp7ImA9WxRUEU4."'>
    <id>tag:youtube.com,2008:channel:dXNzb2NjZXJkb3Rjb20</id>
    <updated>2008-11-19T14:10:07.744-08:00</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#channel'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat'
      term='director'/>
    <title>U.S. Soccer</title>
    <summary>
      ussoccer.com's comprehensive coverage of the U.S. National Teams welcomes
      fans to our YouTube channel - including interviews, press conferences...
    </summary>
    <link rel='http://gdata.youtube.com/schemas/2007#featured-video'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/bYKugypF8HA?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile?user=ussoccerdotcom'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/channels/dXNzb2NjZXJkb3Rjb20?v=2'/>
    <author>
      <name>ussoccerdotcom</name>
      <uri>http://gdata.youtube.com/feeds/api/users/ussoccerdotcom</uri>
    </author>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#channel.content'
      href='http://gdata.youtube.com/feeds/api/users/ussoccerdotcom/uploads?v=2'
      countHint='513'/>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Each entry in the response contains information about a YouTube channel that matches the search request. Entries contain the following information:

  • The <title> and <summary> tags specify a name and description of the channel, respectively.

  • The <author> tag identifies the owner of the channel, and the <uri> tag within the <author> tag specifies the feed URL that you would use to retrieve more information about the channel owner.

  • The <gd:feedLink> tag, which has a rel attribute value of http://gdata.youtube.com/schemas/2007#channel.content, identifies the URL that you would use to retrieve a feed of the videos in the channel.

  • The <link> tags contain links relevant to the channel, including a link to the channel's featured video and a link to the channel owner's profile page.

  • One <category> tag specifies that the entry contains information about a channel. An additional <category> tag may be present indicating that the type of channel that the entry describes. Channel types include director, guru and musician. See http://gdata.youtube.com/schemas/2007/channeltypes.cat for a complete list of channel types.