YouTube

YouTube API v2.0 – Contacts

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

We are reworking YouTube's messaging functionality. While the v2 API has already been deprecated, some API functionality related to contacts will begin returning errors as early as March 31, 2014.

At that time, the API will return 403 (Forbidden) HTTP responses to requests to add, update, or delete contacts. The API will continue to support retrieval of a user's contacts for around six months after that date. After that time, the API will return an empty list in response to a request to retrieve a user's contacts.

We're excited to provide a new and better API for messaging and video sharing later this year.

The YouTube Data API enables a user to add, update or delete contacts.

  1. Retrieving a user's contacts
  2. Adding a contact
  3. Updating a contact
  4. Deleting a contact

Retrieving a user's contacts

To request the currently logged-in user's contact list, send a GET request to the following URL. Your request 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/contacts?v=2

If you try to retrieve contacts for the default user without providing proper authorization, the API returns a 401 (User authentication required) HTTP response.

Note: The API does not allow one user to retrieve another user's contacts.

An API response to a request for a contact list contains a series of <entry> tags. Note that the API returns a maximum of 100 contacts for any given contact feed request even if more contacts match the request parameters. Each entry in a contact feed contains the following information for an individual contact:

  • The edit URL, which you would use to update or delete the contact. The Identifying feeds related to a feed entry section explains how to identify the edit URL for a feed entry.

  • The <yt:username> tag and <yt:userId> tags both specify values that uniquely identify the contact. In addition, the <yt:username> tag's display attribute specifies a display name for the contact.

  • The <yt:status> tag indicates the contact's status. This tag only appears if you are retrieving the contacts of the currently authenticated user. This tag will have one of the following values:

    • accepted - The feed owner and another user have both added each other as contacts.
    • requested - Another user has added the authenticated user as a contact, but the authenticated user has not also added the other user as a contact.
    • pending - The authenticated user has added another user as a contact, but the other user has not also added the authenticated user as a contact.

The following XML shows a sample API response containing a contact:


<?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/&quot;Dk4MQX05fyp7ImA9WxRQGUk.&quot;'>
  <id>tag:youtube,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:contacts</id>
  <updated>2008-07-21T17:34:54.371Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#friend'/>
  <title>Contacts of GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='application/atom+xml'
    href='https://www.youtube.com'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
  </author>
  <generator version='2.1'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>4</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;Dk4MQX05fyp7ImA9WxRQGUk.&quot;'>
    <id>tag:youtube,2008:user:GoogleDevelopers:contact:GoogleTechTalks</id>
    <published>2007-10-17T10:45:41.000-07:00</published>
    <updated>2008-07-21T17:34:54.370Z</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-07-21T17:34:54.370Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#friend'/>
    <title>GoogleTechTalks</title>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/googletechtalks?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/channel/UCtXKDgv1AVoG88PLl8nGXmw'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/contacts/googletechtalks?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/googledevelopers/contacts/googletechtalks?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
    </author>
    <yt:status>accepted</yt:status>
    <yt:userId>tXKDgv1AVoG88PLl8nGXmw</yt:userId>
    <yt:username display='GoogleTechTalks'>googletechtalks</yt:username>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Adding a contact

To add a contact, send an API request that identifies the user who is adding the contact as well as the contact being added. The following example demonstrates the request format:

POST /feeds/api/users/default/contacts HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
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">
  <yt:username>CONTACT_ID</yt:username>
</entry>

Updating a contact

To update a contact, send a PUT request to the edit url for that contact. The XML excerpt below shows how the edit URL appears in a contact entry:

<entry>
  ...
  <link rel='edit' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/>
  ...
</entry>

The API enables a user to update a contact that has a status of requested by either accepting or rejecting the contact. To update the contact, set the value of the <yt:status> tag in your API request to either accepted or rejected.

The following sample request demonstrates how to accept a contact. Please note that in the example, the variable USER_ID refers to the user who is adding the contact and the variable CONTACT_ID refers to the contact being added.

PUT /feeds/api/users/default/contacts/CONTACT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
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">
  <status>accepted</status>
</entry>

The following use case describes a scenario where a user would modify a contact:

  1. This use case begins with a request to retrieve a user's list of contacts. Each <entry> tag in the API response encapsulates information about a single contact, and you would send an API request to a contact entry's edit URL to update or delete that contact.

  2. Your application displays the list of contacts as well as a way to accept or reject contacts that have a status of either pending or requested.

  3. The user modifies one or more contacts and submits his changes.

  4. Your application loops through the contacts and sends a PUT request to update each modified contact. Your application would send each API request to the edit URL for the contact being updated.

Deleting a contact

The following sample API request demonstrates how to delete a contact.

DELETE /feeds/api/users/default/contacts/CONTACT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following list describes a common use case for deleting a contact:

  1. As with the use case for modifying a contact, this use case begins with a request to retrieve a user's list of contacts.

  2. Your application displays the list of contacts as well as a checkbox next to each contact allowing the user to delete that contact.

  3. The user checks one or more contacts and submits his changes.

  4. Your application loops through the contacts and sends a DELETE request to delete each selected contact. Your application would send each API request to the edit URL for the corresponding contact.

pagination links

« Previous
Video Responses
Next »
Messages and Video Sharing

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.