My favorites | English | Sign in

Faster apps faster - GWT 2.0 with Speed Tracer New!

YouTube APIs and Tools

YouTube logo

Developer's Guide: Data API Protocol – Messages and Video Sharing

Video messages enable YouTube users to easily share videos with other YouTube users. On the YouTube website, a video page displays a link, allowing the user to share that video with one or more people from the user's contact list or with other YouTube users.

The YouTube Data API enables you to retrieve video messages sent to the currently logged-in user's inbox, send a video message from that user to another user, and delete video messages from that user's inbox. Note that the API does not retrieve other types of messages in the user's inbox.

Retrieving messages from a user's inbox
 
 Sending a video message
 
 Deleting a message
 

Retrieving messages from a user's inbox

To retrieve a feed containing a list of the messages in the currently logged-in user's inbox, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. This restriction ensures that a user can only retrieve messages from her own inbox. The authentication token enables YouTube to identify the user.

http://gdata.youtube.com/feeds/api/users/default/inbox

An API response to a request for an inbox feed contains a series of <entry> tags. Each entry contains information about a video message sent to the user, and inbox feed entries are very similar to entries in a video feed. Inbox entries contain the following key differences:

  • The <name> tag identifies the sender of the message rather than the owner of the video being sent.

  • The <title> tag contains the subject of the message rather than the video title. The video title still appears in the <media:title> tag.

  • The <summary> tag is included in an inbox feed entry. The tag contains the text of the message.

  • The <content> tag contains the text of the message. This tag contains the same value as the <summary> tag.

  • The <published> tag specifies the date and time that the message was sent rather than the date and time that a video was uploaded.

  • The <link> tag that has a rel attribute value of alternate specifies the URL for the video sent in the message. The user can watch the video at that URL.

  • The <link> tag that has a rel attribute value of edit specifies the edit URL for the message. You would send an HTTP DELETE request to this URL to delete the message.

The following XML shows a sample API response containing an inbox feed:


<?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:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:media='http://search.yahoo.com/mrss/'
  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/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
  <id>tag:youtube,2008:user:andyland74:inbox</id>
  <updated>2008-07-21T17:54:30.236Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
  <title>Inbox of andyland74</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/my_messages?folder=inbox&amp;filter=videos'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
    <id>tag:youtube,2008:user:andyland74:inbox:D_uaXzLRX1U</id>
    <published>2008-06-10T13:55:32.000-07:00</published>
    <updated>2008-06-10T13:55:32.000-07:00</updated>
    <app:edited
  xmlns:app='http://www.w3.org/2007/app'>2008-06-10T20:55:32.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
      term='surfing'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
      term='People' label='People &amp; Blogs'/>
    <title>andyland74sFriend sent you a video!</title>
    <summary>Check out this video!</summary>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/watch?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/responses?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/ratings?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/complaints?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#mobile'
      type='text/html' href='http://m.youtube.com/details?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.related'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/related?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55?v=2'/>
    <author>
      <name>andyland74sFriend</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74sFriend</uri>
    </author>
    <media:group>
      <media:title type='plain'>Learning the ABCs</media:title>
      <media:description type='plain'>
        A great method for teaching kids the alphabet.
      </media:description>
      <media:keywords>alphabet, teaching, children</media:keywords>
      <yt:duration seconds='202'/>
      <yt:videoid>jXE6G9CYcJs</yt:videoid>
      <media:credit role='uploader' scheme='urn:youtube'>andyland74sFriend</media:credit>
      <media:category label='Education'
        scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>
        Education</media:category>
      <media:content url='http://www.youtube.com/v/jXE6G9CYcJs'
        type='application/x-shockwave-flash' medium='video' isDefault='true'
        expression='full' duration='202' yt:format='5'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySANFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='1'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySARFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='6'/>
      <media:player url='http://www.youtube.com/watch?v=jXE6G9CYcJs'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/2.jpg'
        height='97' width='130' time='00:01:41'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/1.jpg'
        height='97' width='130' time='00:00:50.500'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/3.jpg'
        height='97' width='130' time='00:02:31.500'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/0.jpg'
        height='240' width='320' time='00:01:41'/>
    </media:group>
    <yt:statistics viewCount='286355' favoriteCount='201'/>
    <gd:rating min='1' max='5' numRaters='877' average='3.88'/>
    <gd:comments>
      <gd:feedLink
        href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/comments'
        countHint='1088'/>
    </gd:comments>
  </entry>
</feed>

Sending a video message

To send a message, you will send an authenticated HTTP POST request that identifies the user to whom the message is being sent. The XML sent in the request body specifies the <yt:videoid> of the video being sent and the text of the message.

The following sample request demonstrates how to send a video through the API:

POST /feeds/api/users/MESSAGE_RECIPIENT_USER_ID/inbox HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY


<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <id>Qm6znjThL2Y</id>
  <summary>sending a message from the api</summary>
</entry>

Note: A user can only send videos to users in his contact list.

The following steps describe a common use case for sending a message:

  1. This use case begins with a request to retrieve information about a specific video.

  2. After watching the video, the user clicks a link to share the video.

  3. Your application submits a request to retrieve the contact list for the currently authenticated user.

  4. Your application displays a form that allows the user to select one or more contacts to send the video to. The form could also display a text area to allow the user to write a message to those contacts.

  5. After the user submits the completed form, your application loops through the list of selected contacts and submits an API request to send the video to each user.

Deleting a message

The following sample API request demonstrates how to delete a message:

DELETE /feeds/api/users/default/inbox/MESSAGE_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

The following steps describe a common use case for deleting a message:

  1. This use case begins with a request to retrieve the video messages in a user's inbox.

  2. Your application displays the list of video messages as well as a checkbox next to each message allowing the user to delete that message from her inbox.

  3. The user checks one or more messages and submits her changes.

  4. Your application loops through the messages and sends an HTTP DELETE request to delete each selected message. Your application would send each API request to the edit URL for the corresponding message.