Developer's Guide: Data API Protocol – Displaying a List of Videos

The following screenshot demonstrates how YouTube displays information in a video list. The screenshot is annotated, and the list following the screenshot explains how the display elements correspond to the information in an API response.

The screenshot displays the following information:

1. This element displays a title for the result set. In your application, this value could be the value of the <title> tag or you can select other text appropriate to the requested feed or search result set.

2. In the image, the text 1-20 of about 13,800 uses the following elements from the API response:

   • The value "1" equals the value of the <openSearch:startIndex> tag.
   • The value "20" can be calculated by adding the value of the <openSearch:startIndex> tag to the value of the <openSearch:itemsPerPage> tag and then subtracting one. For example, if the <openSearch:startIndex> value is 26 and the <openSearch:itemsPerPage> value is 25, then the result set will display items 26-50 – 50 = (26 + 25) - 1.
   • The value "13,800" equals the value of the <openSearch:totalResults> tag. Please note that the value of this tag is an approximation of the total number of results and not necessarily an exact figure.

3. The pulldown menus allow the user to select values for the orderby and time parameters. The API Query Parameters section provides a complete list of the query parameters that the YouTube Data API supports and explains the types of queries for which each parameter applies.

4. This element displays a thumbnail image of the video. YouTube API responses may contain multiple thumbnail images for a video, each of which is identified by a <media:thumbnail> tag. On the YouTube website, the thumbnail image links to a page that displays more information about the video, including comments and video responses, and also allows the user to watch the video. In a video entry, the <link> tag that has a rel attribute value of alternate identifies the URL for the YouTube page where the user could watch the video. On YouTube search result pages, thumbnail images link to that URL.

   To obtain information to display the target page in your application, you would submit an HTTP request to the edit URL for the video entry. The following section, Identifying feeds related to a video entry explains how to identify the edit URL in an entry.

5. The title next to the video is the value of the <media:title> tag for that video. The text below the title is the value of the <media:description> tag.

6. The right column displays the following values:

   • The first line displays text corresponding to the value of the <published> tag for the video. Note that the <published> tag contains a timestamp that could be converted into text to approximate the age of the video as shown in the screenshot -- e.g. added 5 months ago. However, you could also display a date -- e.g. 10/22/07 or Oct. 22 2007.

   • The second line identifies the YouTube username for the video's owner. This value is specified by the <name> tag encapsulated within the <author> tag for the video entry. On YouTube's website, this link directs the user to a page that displays the video owner's profile information. To retrieve this information on your site, you would submit a subsequent request to the value of the <uri> tag encapsulated within the <author> tag for the video entry.

   • The third line specifies the number of times the video has been viewed. The <yt:statistics> tag's viewCount attribute specifies this value.

   • The fourth line provides the average user rating for the video. The <gd:rating> tag's average attribute provides this rating. Note that on YouTube, the rating is adjusted to determine the proper star image to display. For example, ratings between 2.75 and 3.2499 display a three-star rating, while ratings between 3.25 and 3.7499 display a 3.5 rating.

   • The fifth line displays the length of the video. The <yt:duration> tag provides the length of the video in seconds. In the screenshot, the value has been adjusted to display in minutes and seconds (292 seconds = 04:52).

   • The sixth line displays the name of the category that describes the video. This value is contained in the <media:category> tag's label attribute. On YouTube's website, the category name also links to a page that displays more videos in that category. The Browsing with Categories and Keywords section explains how to request videos that are in a particular category.

To retrieve a feed about a single video in the result set, you would submit an HTTP GET request to the edit URL for that entry, as explained in the following section. For example, you might issue this request when a user linked from a set of search results to watch a particular video in the search result set.