https://developers.google.com/youtube/reporting
Introduction | YouTube Analytics and Reporting APIs
This document explains similarities and differences in the ways that the YouTube Analytics API and YouTube Reporting API provide access to YouTube Analytics data. The document's purpose is to help you to choose the right API for your application. Both APIs
developers.google.com
이 문서는 Youtube Analytics API와 Youtube Reporting API가 제공하는 Youtube Analytics Data에 대한 유사성과 차이점을 설명하는 문서입니다.
이 문서의 목적은 당신의 어플리케이션에 맞는 올바른 API를 선택하게 하기 위한 것입니다.
두 APIs는 YouTube Analytics data를 가져올 수 있게 개발되어져 있습니다.
또한 두 APIs는 YouTube Cannel 소유자와 Youtube content 소유자에게 각자 특정 set의 리포트에 엑세스 할 수 있습니다.
-
Channel reports 는 특정 채널에 대한 user activity metrics 을 포함하고 있습니다.
-
Content owner reports 는 특정 Youtube Contents 소유자에게 연결된 모든 채널에 대한 집계 metrics 를 포함하고 있습니다. 예를 들어, 어떤 레코드 라벨은 이 라벨 가지고 있는 아티스트들의 모든 YouTube channels에 대한 리포트를 검색할 수 있습니다. 일부 콘텐츠 소유자 보고서에는 사용자 활동 통계가 포함되 다른 콘텐츠 소유자 보고서에는 수익 및 광고실적 관련 통계가 포함되기도 합니다.
The Reporting API는 몇몇 컨텐츠 소유자에게 system-managed ad 수익 리포트에 엑세스 할 수 있도록 허용하고 있습니다.
이 system-managed reports 데이터는 Reporting API 에서 단지 검색만 할 수 있습니다.
그리고 모든 YouTube Analytics 와 YouTube Reporting API는 channel 또는 content 소유자가 가지고 있는 데이터를 요구할때 이들의 인증이 반드시 필요합니다.
Report 내용
API가 검색하는 리포트에는 2가지 타입의 데이터를 포함하고 있습니다.
-
Dimensions 는 집계데이터에 이용하기 위한, user가 활동한 date 나 user가 위치해 있었던 국가 같은 일반기준입니다.
리포트에서, 각 data의 row 는 수치가 결합된 고유한 형태입니다. 따라서, 각 rows의 수치 값의 조합은 해당 rows에 대해 primary key 의 기능을 합니다.
-
Metrics 는 user activity 의 개별 측정값으로, 광고실적이나, 예상수입을 나타냅니다. User activity 통계에는 동영상 조회수 및 평점 (좋아요 및 싫어요)과 같은 것들이 포함되어 있습니다.
내 어플레케이션에 맞는 API 선택하기
YouTube Analytics API는 타켓된 쿼리에 의해 생성된 맞춤 YouTube Analytics 리포트를 실시간으로 제공합니다.
API는 제공 필터링과 소팅 파라미터를 제공하고 있어서, 호출하는 어플리케이션은 기본적으로 필터링이나 sorting 기능이 필요없습니다.
각 API 리턴받게될 데이터에 대해서 특정 테이터 범위를 요청합니다.
API는 또한 주별, 월별 데이터셋을 검색할 수 있도록 해줍니다.
따라서 호출하는 어플리케이션은 검색된 데이터 셋을 저장하거나 날짜 범위에 대한 통계를 집계할 필요가 없습니다.
YouTube Reporting API 는 채널 또는 콘텐츠 소유자에 대한 YouTube 분석데이터가 포함된 bulk 리포트(대량 보고서)를 검색할 수 있습니다.
이것은 중요한 대량 데이터셋을 필터링, 정렬 마이닝하는 도구를 제공하는 어플리케이션을 활용할 수 있도록 설계되어 있습니다.
각 리포트는 사전에 정의된 필드셋(fields set)을 포함하고 있습니다.
개발자는 API를 이용하여 reporting jobs을 예약할 수 있습니다.
각 작업들은 YouTube 가 생성할 수있는 리포트를 식별합니다.
그런 다음 YouTube는 비동기식으로 다운로드 할 수있는 일일 보고서를 생성합니다.
각 보고서에는 24시간 동안의 유일한 데이터를 포함하고 있습니다.
또한, YouTube 자동적으로 YouTube 제작자 스튜디오에서 리포트에 엑세스할 수 있는 시스템-관리 보고서 셋을 자동으로 생성합니다.
이 보고서는 광고 수익 데이터에 프로그래밍 방식으로 액세스 할 수 있습니다.
Supported reports
다음 표는 API를 사용하여 검색 할 수있는 다양한 유형의 보고서를 나타냅니다.
타켓팅 쿼리는 YouTube Analytics API를 통해 제공되며, 대량 보고서(Bulk report)는 YouTube Report API를 통해 제공됩니다.
한 API에서 사용 가능한 데이터는 다른 API에서 사용하기 쉽지 않습니다.
예를 들어 YouTube Analytics API를 사용하면 매주 또는 매월 사용자 활동 측정 항목을 검색 할 수 있지만 YouTube Report API에서는 해당 데이터를 직접 집계해야 합니다.
반면 YouTube Reporting API는 콘텐츠 소유자에 대한 자산 보고서(asset reports)를 지원하지만 해당 데이터는 YouTube Analytics API에서 사용할 수 없습니다.
| Video reports |
채널과 컨텐츠 소유자에게 지원합니다. 비디오 보고서는 채널 비디오 또는 콘텐츠 소유자의 비디오와 관련된 모든 사용자 활동에 대한 통계를 제공합니다. 예를 들어,이 보고서에는 동영상이 조회한 횟수가 포함되어 있습니다. YouTube Analytics API에서 일부 콘텐츠 소유자 동영상 보고서에는 예상 수익 및 광고 실적 통계도 포함됩니다.
|
| Playlist reports |
채널과 컨텐츠 소유자에게 지원합니다. |
| Ad performance reports |
컨텐츠 소유자에게 지원합니다. 광고 실적 보고서는 동영상 재생 중에 실행된 광고에 대한 노출 기반 측정 항목을 제공합니다. 이러한 측정 항목은 각 광고 노출에 대해 설명하며, 각 동영상 재생시 여러 노출이 발생할 수 있습니다. |
| Estimated revenue reports |
컨텐츠 소유자에게 지원합니다. 예상 수익 보고서는 Google에서 판매 한 광고 소스 및 비 광고 소스의 비디오에 대한 총 예상 수익을 제공합니다. 이 보고서에는 일부 광고 실적 통계도 포함되어 있습니다. 시스템 관리 보고서(system-managed reports)에는 실제 수익이 포함되어 있습니다.
|
| Asset reports |
컨텐츠 소유자에게 지원합니다. 자산 보고서는 콘텐츠 소유자의 자산에 연결된 비디오와 관련된 사용자 활동 지표를 제공합니다. 콘텐츠 소유자가 해당 동영상을 콘텐츠 소유자의 저작물 중 하나와 일치한다고 주장한 경우 콘텐츠가 보고서에 포함되어집니다. 동영상은 콘텐츠 소유자 또는 다른 YouTube 사용자가 업로드했을 수 있습니다.
|
| System-managed reports |
YouTube 제작자 스튜디오의 보고서 섹션에서 해당 보고서에 액세스 할 수 있는 콘텐츠 소유자에게 지원됩니다. 시스템 관리 보고서(System-managed reports)는 자산과 비디오로 얻은 실제 수익 데이터를 제공합니다. 추가 보고서에는 소유권을 주장한 동영상 및 해당 동영상과 일치하는 저작물의 리스트를 나타냅니다. 현재 모든 제작자 스튜디오 보고서를 API에서 사용할 수있는 것은 아닙니다.
Note: YouTube는 Creator Studio에서는 해당 보고서에 액세스 할 수 있는 콘텐츠 소유자를 위해 시스템 관리 보고서(System-managed reports)를 자동으로 생성합니다. 하지만 결과적으로 이 보고서를 검색하는 프로세스는 이 목록의 다른 유형의 보고서와 다릅니다. 자세한 내용은 시스템 관리 보고서 설명서를 참조하십시오. |
주요 차이점
다음 표는 YouTube Analytics 과 Reporting API의 중요한 차이점을 보여줍니다.
| 특징 | YouTube Analytics API | YouTube Reporting API |
| 데이터를 검색하는 프로세스 |
각 API는 특정 기준과 항목을 지정하여 요청하면 곧바로 시간 범위(time period)만큼에 대한 반환해줄 수 있는 데이터를 리턴해줍니다.
|
어플레케이션에 리포팅 job을 예약합니다. 각 job에 대해, YouTube 매일 리포트를 비동기로 다운로드 받을 수 있도록 생성합니다. |
| 날짜 범위 |
일부 API 보고서는 사용자 활동의 발생한 날자를 지정합니다. 이 몇몇 리포트들은 사용자 활동 집계를 측정하기 위해 측정 기준으로 7-day 단위 , 30-day 단위, 또는 한달 단위로 지원 합니다. |
모든 API리포트는사용자 활동이 발생하는 날짜를 지정합니다. API를 이용하는 어플리케이션은 주기적으로 데이터를 생성할 수 있는 기능을 구현할 수 있습니다. |
| 필터링 데이터 |
당신은 지정된 값을 가지고 있는 dimension을 포함하고 있는 rows 의 리포트를 필터할 수 있습니다. API는 continent a과 subContinent 같은 필터에 사용되어지는 몇몇 dimensions를 지합니다. |
이 API는 전체 데이터 set의 대량 다운로드를 지원합니다. 여기에는 필터링이나 필터 전용 dimensions에 의한 data를 리턴하지 않습니다. 클라이언트 응용 프로그램은 다운로드된 데이터를 저장하고 다운로드 된 데이터에 대해 자체적으로 필터링하는 기능을 구현해야 합니다.
|
| 정렬 |
반환되는 메트릭 값을 기준으로 보고서를 정렬 할 수 있습니다. 일부 보고서는 제한된 수의 결과만 지원합니다. 예를 들어 채널에서 가장 많이 본 동영상을 표시하는 보고서는 최대 200 rows까지 반환됩니다. |
이 API는 전체 데이터 세트의 대량 다운로드를 지원합니다. 클라이언트 응용 프로그램은 다운로드 한 데이터에 대해 자체적으로 정렬 할 수있는 기능을 구현해야 합니다. |
| 표시 |
API 보고서에는 식별할 수 있는 표시된 dimension값, 예를 들어 "ANDROID" 또는 "CHANNEL"과 같은, text 값을 포함하고 있습니다. |
API 보고서에는 텍스트 값에 매핑 할 수 있는 정수가 포함되어 있습니다. 해당 보고서의 텍스트는 정수 코드값으로 처리가 되어 있다는 뜻 |
| 쿼터 |
API 서버는 각 쿼리의 쿼터 비용을 측정하기 위해 각 쿼리를 평가합니다. 쿼터 사용량은 문서에 보다 자세히 설명하고 있습니다. |
할당량 사용량은 데이터를 한 번 검색 한 다음 응용 프로그램 내에서 필터링, 정렬 및 쿼리하기 때문에 문제가되지 않습니다. |
| 고유 리포트 |
|
|
| 고유 수치 | group (filter-only dimension) continent (filter-only dimension) subContinent (filter-only dimension) 7DayTotals 30DayTotals month isCurated==1 (filter-only dimension) viewsPerPlaylistStart averageTimeInPlaylist |
annotation_id annotation_type asset_id card_id card_type live_or_on_demand subscribed_status subtitle_language |
| 고유 측정항목 | uniques relativeRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist |
card_click_rate card_clicks card_impressions card_teaser_click_rate card_teaser_clicks card_teaser_impressions estimated_partner_adsense_revenue estimated_partner_doubleclick_revenue playlist_saves_added playlist_saves_removed |
API의 네이밍 차이점
두 API는 현재 집계와 수치를 구분하기 위해서 서로 다른 네이밍 규칙을 사용합니다.
현재 YouTube Analytics API 이름은 camelCase를 사용하지만 YouTube Reporting API 이름은 밑줄로 구분된 이름을 사용합니다.
다음 표는 두 API가 동일한 집계와 수치을 구분하는데 사용하는 다른이름으로 식별합니다.
경우에 따라 두 이름의 차이에서 camelCase에서 밑줄로 변환하여 사용하는 경우가 아닌 경우도 있습니다.
예를 들어 YouTube Analytics API의 video 이름은 YouTube Reporting API에서 video_id라는 이름으로 지정되기도 합니다.
이름 (Dimensions)
집계 (Metrics)
The following table identifies the different types of reports you can retrieve using the APIs. Targeted queries are available via the YouTube Analytics API, and bulk reports are available via the YouTube Reporting API.
Data that is available in one API might not be available in the other. For example, the YouTube Analytics API lets you retrieve user activity metrics on a weekly or monthly basis, but the YouTube Reporting API requires you to aggregate that data yourself. On the other hand, the YouTube Reporting API supports asset reports for content owners, but that data is not available from the YouTube Analytics API.
This document explains similarities and differences in the ways that the YouTube Analytics API and YouTube Reporting API provide access to YouTube Analytics data. The document's purpose is to help you to choose the right API for your application.
Both APIs enable developers to retrieve YouTube Analytics data. In addition, both APIs support YouTube channel owners and YouTube content owners, each of whom can access a specific set of reports:
-
Channel reports contain user activity metrics for a specified channel.
-
Content owner reports aggregate metrics for all of the channels linked to a specified YouTube content owner. For example, a record label could retrieve a report containing combined statistics for the YouTube channels of all of the label's artists. Some content owner reports contain user activity metrics, while others contain metrics related to revenue and ad performance.
The Reporting API also allows some content owners to access system-managed ad revenue reports. The data in the system-managed reports can only be retrieved with the Reporting API.
All YouTube Analytics and YouTube Reporting API requests must be authorized by the channel or content owner that owns the requested data.
Report contents
The reports that the APIs retrieve contain two types of data:
-
Dimensions are common criteria that are used to aggregate data, such as the date on which the user activity occurred or the country where the users were located.
In a 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.
-
Metrics are individual measurements of user activity, ad performance, or estimated revenue. User activity metrics include things like video view counts and ratings (likes and dislikes).
Choose the right API for your application
The YouTube Analytics API supports real-time targeted queries to generate custom YouTube Analytics reports. The API provides filtering and sorting parameters, so the calling application does not need to natively support these functions.
Each API request specifies the date range for which data will be returned. The API also enables you to retrieve weekly and monthly data sets. As such, the calling application does not need to store retrieved data sets or aggregate statistics across date ranges.The YouTube Reporting API retrieves bulk reports containing YouTube Analytics data for a channel or content owner. It is designed for applications that can import large data sets and that provide tools to filter, sort, and mine that data.
Each report contains a predefined set of fields. Developers use the API to schedule reporting jobs, each of which identifies a report that YouTube should generate. YouTube then generates a daily report that can be asynchronously downloaded. Each report contains data for a unique 24-hour period.
In addition, YouTube automatically generates a set of system-managed reports for content owners that have access to the corresponding reports in YouTube Creator Studio. These reports provide programmatic access to ad revenue data.
Supported reports
The following table identifies the different types of reports you can retrieve using the APIs. Targeted queries are available via the YouTube Analytics API, and bulk reports are available via the YouTube Reporting API.
Data that is available in one API might not be available in the other. For example, the YouTube Analytics API lets you retrieve user activity metrics on a weekly or monthly basis, but the YouTube Reporting API requires you to aggregate that data yourself. On the other hand, the YouTube Reporting API supports asset reports for content owners, but that data is not available from the YouTube Analytics API.
| Video reports | Supported for channels (query or bulk) and content owners (query or bulk). Video reports provide statistics for all user activity related to a channel's videos or a content owner's videos. For example, these reports contain the number of views that your videos received. In the YouTube Analytics API, some content owner video reports also include estimated revenue and ad performance metrics. |
| Playlist reports | Supported for channels (query or bulk) and content owners (query or bulk). Playlist reports provide statistics that are specifically related to video views that occur in the context of a playlist. The YouTube Reporting API supports audience retention reports for playlists, but the YouTube Analytics API does not support a similar report. |
| Ad performance reports | Supported for content owners (query or bulk). Ad performance reports provide impression-based metrics for ads that ran during video playbacks. These metrics account for each ad impression, and each video playback can yield multiple impressions. |
| Estimated revenue reports | Supported for content owners (bulk). Estimated revenue reports provide the total estimated revenue for videos from Google-sold advertising sources and from non-advertising sources. These reports also contain some ad performance metrics. Note that system-managed reports contain actual revenue. |
| Asset reports | Supported for content owners (bulk). Asset reports provide user activity metrics related to videos that are linked to a content owner's assets. A video is included in a content owner's report if the content owner has claimed that video as a match of one of the content owner's assets. The video could have been uploaded by the content owner or by another YouTube user. |
| System-managed reports | Supported for content owners who have access to the corresponding reports in the Reports section of YouTube's Creator Studio. System-managed reports provide actual revenue data earned by assets and videos. An additional report lists claimed videos and the assets those videos match. Note that not all Creator Studio reports are currently available in the API. Note: YouTube automatically generates system-managed reports for content owners that have access to the corresponding reports in Creator Studio. As a result, the process for retrieving these reports is different than for the other types of reports in this list. See the documentation for system-managed reports for more information. |
Key differences
The following table highlights important differences between the YouTube Analytics and Reporting APIs.
FeatureYouTube Analytics APIYouTube Reporting API
| Process to retrieve data | Each API request specifies dimensions and metrics to be returned as well as the time period for which data will be returned. | Applications schedule reporting jobs. For each job, YouTube generates daily reports that can be asychronously downloaded. |
| Date Ranges | Some API reports specify the date that user activity occurred. Some of those reports support dimensions to aggregate user activity metrics by 7-day periods, 30-day periods, or months. | All API reports specify the day that user activity occurred. Applications using the API can implement features to aggregate data for periodic intervals. |
| Filtering data | You can filter reports to include only rows for which a dimension has a specific value. The API also supports some dimensions, like continent and subContinent, that are used only as filters. | The API supports bulk downloads of complete data sets. It does not support filtering or return data for filter-only dimensions. The client application stores the downloaded data and implements its own features to filter the data. |
| Sorting | Reports can be sorted based on returned metric values. Some reports support only a limited number of results. For example, the report that lists a channel's most viewed videos returns a maximum of 200 rows. | This API supports bulk downloads of complete data sets. Client applications can implement their own features to sort downloaded data. |
| Enumerations | API reports contain text values, like "ANDROID" or "CHANNEL," to identify enumerated dimension values. | API reports contain integers that can be mapped to text values. |
| Quota | The API server evaluates each query to determine its quota cost. The quota usage document explains the methodology in more detail. | Quota usage is not an issue because data is retrieved once and then filtered, sorted, and queried within the application. |
| Unique reports |
|
|
| Unique dimensions | group (filter-only dimension) continent (filter-only dimension) subContinent (filter-only dimension) 7DayTotals 30DayTotals month isCurated==1 (filter-only dimension) viewsPerPlaylistStart averageTimeInPlaylist |
annotation_id annotation_type asset_id card_id card_type live_or_on_demand subscribed_status subtitle_language |
| Unique metrics | uniques relativeRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist |
card_click_rate card_clicks card_impressions card_teaser_click_rate card_teaser_clicks card_teaser_impressions estimated_partner_adsense_revenue estimated_partner_doubleclick_revenue playlist_saves_added playlist_saves_removed |
Naming differences between APIs
The two APIs currently use different naming conventions to identify dimensions and metrics. At this time, YouTube Analytics API names use camelCase, while YouTube Reporting API names use underscore-delimited names.
The following tables identify the different names that the two APIs use to identify the same metrics and dimensions. In some cases, the difference between the two names is more than what you would get after converting a name from camelCase to underscores. For example, the video dimension in the YouTube Analytics API is named video_id in the YouTube Reporting API.
Dimensions
YouTube Analytics API nameYouTube Reporting API name
Metrics
YouTube Analytics API nameYouTube Reporting API name