The YouTube API allows users to rate videos, and it also returns rating information in any feed entry that contains information about a video. As such, ratings information appears in video feed entries, favorite videos feed entries, playlist feed entries, and so forth. (Playlist feed entries identify individual videos in a specific playlist.) Ratings information also appears in user event feeds when an event describes a user's rating of a video.

YouTube currently uses a rating system that lets users indicate whether they like or dislike a video. However, until March 2010, YouTube used a 1-5 rating system in which 1 was the lowest rating that could be given. The YouTube API currently supports both rating systems and uses different XML elements to provide rating information for each system:

• The <yt:rating> element contains information about the number of users who gave the video a positive or negative rating as well as the total number of ratings that the video received. The totals do account for ratings that were given using the 1-5 rating system. This element is only returned if the video has been rated.

  The XML excerpt below shows how this element appears in an API response:

  <feed>
    <entry>
      ...
      <yt:rating numDislikes='28' numLikes='143'/>
    </entry>
  </feed>
  

• The <gd:rating> element identifies the rating scale (1-5), the number of ratings that the video received, and the video's average rating. Again, the figures also account for ratings that were submitted using the like-or-dislike system, with positive and negative ratings equating to scores of 5 and 1, respectively. This element is only returned if the video has been rated.

  The XML excerpt below shows how this element appears in an API response:

  <feed>
    <entry>
      ...
      <gd:rating average='4.24' max='5' min='1' numRaters='171'
          rel='http://schemas.google.com/g/2005#overall'/>
    </entry>
  </feed>
  

  Note: The <gd:rating> element has been deprecated. The API will stop supporting the 1-5 rating system at the end of the deprecation period explained in our Terms of Service.

Adding a rating

Every feed entry that describes a video contains a <link> element that identifies the URL to use to add a rating to that video. Since each entry includes several <link> element, you must use the URL from the element 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.ratings'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
  </entry>
</feed>

To add a rating to a video, send an authenticated POST request to the video's ratings URL. The user who is rating the video must be identified by the authentication token. To change a user's rating of a video, send another POST request that identifies the new rating. The API does not support rating changes via PUT requests. The API also does not let users delete ratings.

The following sections explain how to add ratings using either the like-or-dislike rating system (<yt:rating>) or the numeric rating system (<gd:rating>). If you include both types of ratings in a request to add a rating, YouTube will ignore the numeric rating unless the <gd:rating> tag or one of its attributes specifies an invalid value, which will instead generate an error.

Adding a 'like' or 'dislike' video rating

The following XML demonstrates how to add a rating to a video using the like-or-dislike rating system. Please note that the <yt:rating> element's value attribute can be set to either like or dislike.

POST /feeds/api/videos/VIDEO_ID/ratings
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:rating value="like"/>
</entry>

If YouTube successfully handles your request, the API will return a 201 HTTP response code. YouTube will return an error if your request specifies an invalid value for the <yt:rating> element's value attribute.

Adding a numeric (1-5) video rating

The following XML demonstrates how to add a rating to a video using the 1-5 rating system. Please note that the <gd:rating> element's value attribute must be an integer between 1 and 5 that identifies the rating being given. As noted above, the <gd:rating> element has been deprecated.

POST /feeds/api/videos/VIDEO_ID/ratings
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: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. The API will return an error if your original request specifies an invalid value for the <gd:rating> element's value attribute, a value other than 1 for the min attribute or a value other than 5 for the max attribute.

Last updated July 18, 2012.