Developer's Guide: Data API Protocol – Ratings

A user can add a rating to a video. YouTube uses a 1-5 rating system in which 1 is the lowest rating that can be given. Users cannot update or delete ratings. Typically, a user would rate a video after watching that video.

In an API response, each entry includes two tags that contain information relevant to user ratings:

• The <gd:rating> tag identifies the rating scale, the number of ratings of the video and the average rating for the video. This tag is only returned if the video has been rated. The XML excerpt below shows how this URL appears in an API response:

  <feed>
    <entry>
      ...
      <gd:rating min='1' max='5' numRaters='1914' average='4.24'/>
    </entry>
  </feed>
  

• A <link> tag identifies the URL to which you would post an API request to add a rating to a video. Since each entry includes several link tags, you must use the URL for the tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#video.ratings. The XML excerpt below shows how this URL appears in an API response:

  <feed>
    <entry>
      <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/responses'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
      ...
      <media:group>
    </entry>
  </feed>
  

To add a rating, send an HTTP POST request that identifies the video being rated and the rating itself. (The user who is rating the video is identified by the authentication token.)

The following XML demonstrates how to add a rating to a video. Please note that the value attribute of the <gd:rating> tag must be an integer between 1 and 5 that identifies the rating being given.

POST /feeds/api/videos/VIDEO_ID/ratings
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
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:gd="http://schemas.google.com/g/2005">
  <gd:rating value="4" min="1" max="5"/>
</entry>

If YouTube successfully handles your request, the API will return a 201 HTTP response code.

YouTube will return an error if your HTTP request specifies an invalid value for the <gd:rating> tag's value attribute, a value other than 1 for the min attribute or a value other than 5 for the max attribute.