Show
This document defines the dimensions that the YouTube Reporting API supports. This API retrieves bulk reports that contain YouTube Analytics data for a channel or content owner. Dimensions are common criteria that are used to aggregate data, such as the date on which user activity occurred or the country where users were located. Each bulk report supports a predefined list of dimensions, and, in any report, each row of data has a unique combination of dimension values. As such, each row's combination of dimension values functions as the primary key for that row. You neither need to specify nor have the option of specifying which dimensions are included in the report. Core dimensionsWhile the YouTube Reporting API is subject to the Deprecation Policy defined in the Terms of Service, non-core dimensions (and non-core metrics) are not subject to the policy. In the definitions on this page, any dimension that is a core dimension is explicitly identified as such. The following list identifies the API's core dimensions. All of them are also core dimensions in the YouTube Analytics API.
See the list of YouTube APIs subject to the Deprecation Policy for more information. DimensionsThe following sections define the dimensions that are used in the YouTube Reporting API's bulk reports. Unless otherwise noted, these dimensions are used in both channel and content owner reports. ResourcesThese dimensions correspond to resources that channels and content owners manage on YouTube:
video resource's id property. This is a core dimension and is subject to the Deprecation Policy.playlist_idThe ID of a YouTube playlist. In the YouTube Data API, this is the value of a playlist resource's id property.channel_id (core dimension)The ID for a YouTube channel. In the YouTube Data API, this is the value of a channel resource's id property. This is a core dimension and is subject to the Deprecation Policy.asset_id (only used in content owner reports)The ID of an asset
managed in YouTube's Content ID system. An asset is the representation of your intellectual property in that system. On the YouTube website, you can locate asset IDs in YouTube Content Manager. You can also retrieve them using the YouTube Content ID API.Geographic areasThese dimensions identify a geographic region associated with user activity, ad performance, or estimated revenue metrics. US , CN (China), or FR (France). The country code ZZ is used to report metrics for which YouTube could not identify the associated country. This is a core dimension and is subject to the
Deprecation Policy.province_codeThe U.S. state or territory associated with the metrics in the report row. The dimension value is an ISO 3166-2 code that identifies a U.S. state or the District of Columbia, such as US-MI (Michigan) or US-TX (Texas). The
province code US-ZZ is used to report metrics for which YouTube could not identify the associated U.S. state. Note: This dimension does not support ISO 3166-2 values that identify U.S. outlying areas since those territories also have their own ISO 3166-1 country codes. It also does not support subdivisions of countries other than the United States. Time periodsdate (core dimension)This dimension identifies the date associated with the metrics in each report row. In bulk reports, the date refers to the period beginning at 12:00 a.m. Pacific time and ending at 11:59 p.m. Pacific time on the specified day, month, and year. Depending on the time of year, Pacific time is either UTC-7 or UTC-8.Note that while dates typically represent a 24-hour period, dates when clocks are adjusted forward for Daylight Savings Time represent a 23-hour period, and dates when clocks are adjusted backward represent a 25-hour period. This is a core dimension and is subject to the Deprecation Policy.Playback locationsThese dimensions provide insight about the page or application where user activity occurred. playback_location_type This dimension identifies the type of page or application where user activity occurred. The following table lists dimension values:
1 . In other rows, this dimension's value is empty.Playback detailslive_or_on_demandThis dimension indicates whether the user activity metrics in the data row are associated with views of a live broadcast. Data for this dimension is available for dates beginning April 1, 2014.The following table lists dimension values:
subscribed and unsubscribed . Note that the dimension value is accurate as of the time that the user activity occurs. For example, suppose a user has not subscribed to a channel and watches one of that channel's
videos, then subscribes to the channel and watches another video, all on the same day. The channel's report indicates that one view has a Traffic sourcestraffic_source_typeThis dimension identifies the referrer type associated with the user activity metrics. The referrer type describes the manner in which users reached the video or channel associated with the row of data in the report. The following table lists dimension values:
Devicesdevice_typeThis dimension identifies the physical form factor of the device on which the view occurred. The following table lists valid dimension values:
DemographicsDemographic dimensions help you to understand the age range and gender distribution of your audience. The YouTube Help Center contains additional information about demographic data in YouTube Analytics reports. age_group (core dimension)This dimension identifies the age group of the logged-in users associated with the report data. The API uses the following age groups:
FEMALE , MALE and GENDER_OTHER . This is a core dimension and is subject to the Deprecation Policy.sharing_service (core dimension)
This dimension identifies the service that was used to share videos. Videos can be shared on YouTube (or via the YouTube player) using the "Share" button. This is a core dimension and is subject to the Deprecation Policy.The following table lists valid dimension values:
See the help docs for more information. Annotationsannotation_typeThis dimension identifies the manner in which the annotation displays during the video. The following table lists possible dimension values:
Cardscard_typeThis dimension identifies the type of card that was displayed to the user. The following table lists possible dimension values:
End screensend_screen_element_typeThis dimension identifies the type of end screen element that was displayed to the user. The following table lists the end screen element types and their values:
Subtitlessubtitle_languageThis dimension identifies the closed caption language used for the longest time during the view. Views for which closed captions were mostly turned off are not counted. See the documentation for channel reports or content owner reports for more information about reports that contain this dimension.subtitle_language_autotranslatedThis dimension identifies the auto-translated closed caption language used for the longest time during the view. Views for which closed captions were mostly turned off are not counted. See the documentation for channel reports or content owner reports for more information about reports that contain this dimension.Ad performancead_typeThead_type dimension is used in ad performance reports and aggregates the requested metrics based on the types of ads that ran during video
playbacks. The following table lists possible dimension values. See the YouTube Help Center for more information about YouTube advertising formats.
Note: Query reports might return for some additional ad types that were previously used on YouTube. Content owner dimensionsThe following dimensions are only used in content owner reports. claimed_status (only used in content owner reports)This dimension indicate that a row of data only contains metrics for claimed content. The only valid value for this dimension isclaimed . The table in the definition of the uploader_type dimension provides more detail about how to use this dimension.uploader_type (core dimension) (only used in content owner reports)This dimension indicates whether a row of data contains metrics for content uploaded by the specified content owner and/or content uploaded by third parties,
such as user-uploaded videos. Valid values are self and thirdParty . This is a core dimension and is subject to the Deprecation Policy.The table below shows the supported combinations for the
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates. Last updated 2022-12-15 UTC. [{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Missing the information I need" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Too complicated / too many steps" },{ "type": "thumb-down", "id": "outOfDate", "label":"Out of date" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Samples / code issue" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }] |