YouTube API v2.0 – Retrieving Insight Data

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

Important: The API's support for YouTube Insight data has been officially deprecated as of September 30, 2013. This functionality will continue to work as per our deprecation policy, but we encourage you to migrate to the new YouTube Analytics API as soon as possible. If you are building a new application, use the YouTube Analytics API to get the most comprehensive set of API features related to the YouTube Analytics data.

YouTube Insight, an analytics and reporting engine, provides viewing statistics, popularity metrics and demographic information for videos and channels.

  • A video entry contains a link to Insight data if the authenticated user retrieving the entry owns the video.

  • A profile entry contains a link to Insight data for the channel if the authenticated user is retrieving his or her own profile.

Both links appear 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-partner/gwt/csv-zip?token=lGYReallyLongString==...'/>

The URL in the <link> tag points to a zip file that contains 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".)

You can adjust the date range for which a report contains data to a period of up to 31 days beginning no earlier than March 1, 2009. To do so, update the values of the user_starttime and user_endtime parameters in the zip file URL. Each parameter specifies a timestamp in milliseconds, and the parameter values are floored to midnight UTC. As such, the first day for which the report will include data will be the day on which the user_starttime timestamp occurs. The last day for which the report will include data will be the day before the day on which the user_endtime timestamp occurs.

For example, the following URL's user_starttime and user_endtime parameters specify timestamps on the dates February 17, 2011, and February 24, 2011, respectively. Thus, the report would contain data for the period between February 17, 2011, and February 23, 2011.

http://insight.youtube.com/video-analytics-partner/gwt/csv-zip?token=lGYlGYReallyLongString==
    &sig=MCwReallyLongString
    &user_starttime=1297900800000
    &user_endtime=1298505600000

To update the parameter values, you need to parse the URL and modify the default parameter values before retrieving the zip file. For example, if you wanted to instead retrieve a report containing data for the period between February 10, 2011, and February 17, 2011, you would need to update both parameter values:

  • You would need to replace the user_starttime parameter value shown above with any value between (and including) 1297296000000 and 1297382399999 to retrieve data beginning on February 10, 2011. Any timestamp in that range occurs on February 10, 2011, and, therefore, the Insight report would contain data as of that date.

  • You would need to replace the user_endtime parameter value shown above with any value between (and including) 1297987200000 and 1298073599999 to retrieve data beginning on February 10, 2011. Any timestamp in that range occurs on February 18, 2011, and, therefore, the Insight report would contain data as of the previous day.

Note: All Insight report data is for days in Pacific time.

Insight reports and their contents

The following list identifies the reports that are included in the zip file and defines the fields in each report.

  • Video reports

    • Demographics (filename: VIDEOID_demographics_1.csv) – This report provides a demographic breakdown of the viewers who have watched a video. The report contains the following fields:

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

      • Title – The title of the video.

      • Gender – The gender of the demographic group.

      • Age group – The age group of the demographic group. Reported age groups are 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, and 65-.

      • Percentage – The percentage of the video's viewers who are in the specified gender and age group.

    • Locations (filename: VIDEOID_DATERANGE_REGION_locations_1.csv) – This report indicates where users watched a video. Each row in the report specifies the number of times that a particular video was viewed on a specific date in a specific region on either a YouTube channel page, a YouTube video watch page, another website, or a mobile device. 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 views occurred. The date is in YYYY-MM-DD format.

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

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

      • Title – The title of the video that was viewed.

      • Player location – The type of page or application where the video that was viewed. This field will contain one of the following values:

        • CHANNEL – The row describes views that occurred on a channel page.
        • WATCH – The row describes views that occurred on the video's YouTube watch page.
        • EMBEDDED – The row describes views occurred on another website or application where the video was embedded.
        • MOBILE – The row describes views that occurred on YouTube's mobile website or on approved YouTube API clients, including mobile devices.

      • Detail – This field is not used in this report.

      • Views – The number of views that occurred in the location on the specified day in the specified region.

    • 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 for a specific video 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. The date is in YYYY-MM-DD format.

      • 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 that was viewed.

      • Title – The title of the video that was viewed.

      • 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.
        • ANNOTATION – Viewers reached the video by clicking on an annotation in another video.
        • 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.
        • NO_LINK_EMBEDDED – The video was embedded on another website when it was viewed. The Detail field in the row will identify the web page where the video was embedded.
        • NO_LINK_MOBILE – The video views occurred on a mobile device, but YouTube did not identify a referrer for the views.
        • NO_LINK_VIRAL – 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.
        • PROMOTED – The video views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
        • RELATED_VIDEO – The video views were referred from a related video listing on another video watch page. The Detail field in the row will specify the video ID for that video.
        • YT_CHANNEL – The video views occurred on a channel page.
        • 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_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:

        • If the source type is a search results page (YT_SEARCH, GOOGLE_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, NO_LINK_EMBEDDED), then the Detail field contains the URL of that page. If the source type is YT_OTHER_PAGE, then the Detail field actually contains a relative URL on YouTube's website.
        • If the source type is a promotion (PROMOTED), then the Detail field specifies the type of promotion associated with the views.

        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. The date is in YYYY-MM-DD format.

      • 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 or a "dislike" rating.

      • 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 or a "like" rating.

  • Channel reports

    • Demographics (filename: CHANNEL_demographics_1.csv) – This report provides a demographic breakdown of the viewers who have watched visited your channel page or watched your channel's videos. The report contains the following fields:

      • Channel – The name of the YouTube channel for which the row contains data. (This value will be the same in every row.)

      • Gender – The gender of the demographic group.

      • Age group – The age group of the demographic group. Reported age groups are 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, and 65-.

      • Percentage – The percentage of visitors to your channel page who are in the specified gender and age group.

    • Locations (filename: CHANNEL_DATERANGE_REGION_locations_1.csv) – This report indicates where users watched a channel's videos. Each row in the report specifies the number of times that a channel's videos were viewed on a specific date in a specific region on either a YouTube channel page, a YouTube video watch page, another website, or a mobile device. This report will be omitted if the channel's videos were not viewed at least once during the reporting period. The report contains the following fields:

      • Date – The day that the views occurred. The date is in YYYY-MM-DD format.

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

      • Channel – The name of the YouTube channel for which the row contains data. (This value will be the same in every row.)

      • Player location – The type of page or application where the video that was viewed. This field will contain one of the following values:

        • CHANNEL – The row describes views that occurred on a channel page.
        • WATCH – The row describes views that occurred on YouTube video watch pages.
        • EMBEDDED – The row describes views occurred on another website or application where the channel's videos were embedded.
        • MOBILE – The row describes views that occurred on YouTube's mobile website or on approved YouTube API clients, including mobile devices.

      • Views – The number of views that occurred in the location on the specified day in the specified region.

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

      • Date – The day that the referred video views occurred. The date is in YYYY-MM-DD format.

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

      • Channel – The name of the YouTube channel for which the row contains data. (This value will be the same in every row.)

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

        • ADVERTISING – The views were referred to the channel's videos by an advertisement.
        • ANNOTATION
        • EXT_URL – The views were referred from a link on a web page. The Detail field in the row will identify the web page.
        • GOOGLE_SEARCH – The views were referred from Google search results.
        • NO_LINK_EMBEDDED – The channel's videos were embedded on another website when they were viewed. The Detail field in the row will identify the web page where the videos was embedded.
        • NO_LINK_MOBILE – The views occurred on a mobile device, but YouTube did not identify a referrer for the views.
        • NO_LINK_VIRAL – YouTube did not identify a referrer for the views, indicating that the user navigated directly to the channel's videos, perhaps by copying and pasting the URLs from another location.
        • PROMOTED – The views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
        • RELATED_VIDEO – The views were referred from related video listings on other video watch pages. The Detail field in the row will specify the video ID for that video.
        • YT_CHANNEL – The views occurred on a channel page.
        • YT_OTHER_PAGE – The views were referred from a link other than a search result or related video link that appeared on a YouTube page.
        • YT_SEARCH – The 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:

        • If the source type is a search results page (YT_SEARCH, GOOGLE_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, NO_LINK_EMBEDDED), then the Detail field contains the URL of that page. If the source type is YT_OTHER_PAGE, then the Detail field actually contains a relative URL on YouTube's website.
        • If the source type is a promotion (PROMOTED), then the Detail field specifies the type of promotion associated with the views.

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

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

    • Views (filename: CHANNEL_DATERANGE_REGION_views_1.csv) – This report provides information about the visitors to your channel and their activity on your channel page. Each row in the report contains data for a specific date in a specific region. The report contains the following fields:

      • Date – The day for which the channel information is relevant. The date is in YYYY-MM-DD format.

      • Region – The country associated with the channel information. The value will be an ISO 3166 two-letter country code.

      • Channel – The name of the YouTube channel for which the row contains data. (This value will be the same in every row.)

      • Views – The number of times that your channel page was visited.

      • Unique users – The number of unique users who visited your channel page on the specified day.

      • Unique users (7 days) – The number of unique users who have visited your channel page in the past seven days (from the date specified in the Date column.

      • Unique users (30 days) – The number of unique users who have visited your channel page in the past 30 days (from the date specified in the Date column.

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

      • Comments – The number of comments that viewers left on the channel page or on any videos in the channel.

      • Favorites – The number of times that any videos in the channel were marked as a favorite video.

      • Rating 1 – The number of times that a video in the channel received a rating of 1 or a "dislike" rating.

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

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

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

      • Rating 5 – The number of times that a video in the channel received a rating of 5 or a "like" rating.

      • Subscriptions – The number of YouTube users who subscribed to the channel on the specified date.

      • Unsubscriptions – The number of YouTube users who unsubscribed from the channel on the specified date.

pagination links

« Previous
Managing Live Events

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.