Developer's Guide: Data API Protocol – Retrieving Insight Data for a Video

YouTube Insight, an analytics and reporting engine, provides viewing statistics, popularity metrics and demographic information for videos. A video entry contains a link to an Insight data feed if the authenticated user retrieving the entry owns the video. The link appears in a <link> tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#insight.views.

<link rel='http://gdata.youtube.com/schemas/2007#insight.views'
  type='text/html'
  href='http://insight.youtube.com/video-analytics/csvreports?query=PlVJ88-zqkI&type=...'/>

The URL in the <link> tag points to a zip file that contains two Insight reports in CSV (comma-separated values) format. Each report contains worldwide data for the previous seven-day period. (As such, the REGION in each filename listed below will be "world".) This list identifies the reports that are included in the zip file and defines the fields in each report:

• Referrers (filename: VIDEOID_DATERANGE_REGION_referrers_1.csv) – This report explains how users reached the video. Each row in the report identifies the number of referred views from a particular referrer on a specific date in a specific region. Note that this report will be omitted if the video was not viewed at least once during the reporting period. The report contains the following fields:

  • Date – The day that the referred video views occurred.

  • Region – The country where the referred video views occurred. The value will be a ISO 3166 two-letter country code.

  • VideoID – The YouTube video ID that uniquely identifies the video.

  • Title – The title of the video.

  • Source type – The referrer for the video views. This field will contain one of the following values:

    • ADVERTISING – The viewer was referred to the video by an advertisement.
    • EMBEDDED – The video was embedded in a web page when it wsa viewed. The "Detail" field in the row will identify the web page where the video was embedded.
    • EXT_URL – The video views were referred from a link on a web page. The "Detail" field in the row will identify the web page.
    • GOOGLE_SEARCH – The video views were referred from Google search results.
    • GVIDEO_SEARCH – The video views were referred from Google Video search results.
    • PROMOTED – The video views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
    • VIRAL_OTHER – YouTube did not identify a referrer for the views, indicating that the user navigated directly to the video, perhaps by copying and pasting the URL from another location.
    • YT_OTHER_PAGE – The video views were referred from a link other than a search result or related video link that appeared on a YouTube page.
    • YT_RELATED – The video views were referred from a related video on YouTube.
    • YT_SEARCH – The video views were referred from YouTube search results.

  • Detail – Additional information about the traffic referral source. This type of information that the field provides depends on the value of the "Source Type" field:

    • If the source type is a search results page (YT_SEARCH, GOOGLE_SEARCH, GVIDEO_SEARCH), then the "Detail" field contains the search term(s) for that page.
    • If the source type is another video (YT_RELATED), then the "Detail" field contains the YouTube video ID for that video.
    • If the source type is another web page (EXT_URL, YT_OTHER_PAGE, EMBEDDED), then the "Detail" field contains the URL of that page.

    For all other source types, the "Detail" field will be empty or will contain the word "Other".

  • Referred views – The number of video views that originated from the data source on the specified day in the specified region.

• Views (filename: VIDEOID_DATERANGE_REGION_views_1.csv) – This report provides insight into the way that viewers interacted with the video. Each row in the report identifies the number of views that occurred on a specific date in a specific region. The report contains the following fields:

  • Date – The day that the video views occurred.

  • Region – The country where the video views occurred. The value will be a ISO 3166 two-letter country code.

  • VideoID – The YouTube video ID that uniquely identifies the video.

  • Title – The title of the video.

  • Views – The number of times that the video was watched.

  • Unique users – The number of unique users who watched the video.

  • Popularity – A metric that measures the popularity of a video, as measured by views, relative to other videos in a region. For example, a popularity score of 0.75 indicates that a video has been viewed more frequently than 75 percent of all other videos available in the region.

  • Comments – The number of comments that viewers left on the video.

  • Favorites – The number of times that the video was marked as a favorite video.

  • Rating 1 – The number of times that the video received a rating of 1.

  • Rating 2 – The number of times that the video received a rating of 2.

  • Rating 3 – The number of times that the video received a rating of 3.

  • Rating 4 – The number of times that the video received a rating of 4.

  • Rating 5 – The number of times that the video received a rating of 5.