이 페이지는 Cloud Translation API를 통해 번역되었습니다.

YouTube Analytics API - Data Model

YouTube Analytics API를 사용하면 YouTube 분석 데이터가 포함된 맞춤 보고서를 생성할 수 있습니다. API는 채널 및 콘텐츠 소유자에 대한 보고서를 지원합니다. 보고서 필드는 측정기준 또는 측정항목 중 하나로 분류됩니다.

측정기준은 액션 발생일 또는 사용자 거주 국가와 같이 데이터를 집계하는 데 사용되는 공통 기준입니다.

보고서에서는 데이터의 각 행에 측정기준 값의 고유한 조합이 있습니다. 따라서 보고서에 대해 선택한 측정기준에 따라 YouTube가 보고서의 측정항목 값을 계산하는 방식이 달라집니다.
측정항목은 사용자 활동, 광고 실적 또는 예상 수익과 관련된 개별 측정값입니다. 사용자 활동 측정항목에는 동영상 조회수 및 평점 (좋아요 및 싫어요) 등이 포함됩니다.

Analytics API는 필터링 및 정렬 매개변수를 제공하므로 호출 애플리케이션에서 기본적으로 이러한 함수를 지원할 필요가 없습니다. API를 사용하면 최대 500개의 동영상, 재생목록, 채널 또는 저작물로 구성된 맞춤 컬렉션인 YouTube 분석 그룹의 데이터를 검색할 수도 있습니다.

보고서 매개변수 선택

보고서를 요청할 때 API의 reports.query 메서드를 사용하여 API 요청에 보고서 값을 계산하는 방식을 결정하는 5가지 매개변수가 포함됩니다.

startDate 및 endDate 매개변수는 보고서에 데이터가 포함될 기간을 지정합니다. API 응답에는 쿼리에서 모든 측정항목을 사용할 수 있도록 지정된 마지막 날까지의 데이터가 실제로 포함되어 있습니다.
metrics 매개변수는 보고서에 포함될 측정값을 지정합니다. 채널 보고서에서 측정항목은 사용자 활동을 측정하고 조회수, 좋아요 등의 값을 포함합니다. 일부 측정항목은 광고 실적이나 예상 수익도 측정합니다.
dimensions 매개변수는 측정항목이 그룹화되는 방식을 설명합니다.
filters 매개변수는 보고서 데이터가 필터링되는 방식을 설명합니다. 예를 들어 채널의 모든 데이터를 반환하는 대신 특정 국가, 동영상 또는 동영상 그룹의 측정항목만 포함하도록 보고서를 필터링할 수 있습니다.

참고: API를 사용하면 동영상, 재생목록, 채널 필터에 대해 여러 값을 지정할 수 있습니다. 이 경우 측정기준에 해당 필터를 포함하여 반환된 측정항목도 동영상, 재생목록 또는 채널별로 그룹화될 수 있습니다.

샘플 보고 옵션

예를 들어 채널 소유자가 동영상 기기 유형 보고서를 검색하여 휴대기기, 게임 콘솔, TV 등에서 발생한 채널 동영상의 조회수를 확인하려고 합니다.

채널 소유자가 startDate 매개변수를 2015-06-01로, endDate 매개변수를 2015-07-31로 설정합니다. 이러한 값에 따라 보고서에는 2개월 동안의 데이터가 포함됩니다.
기기 유형 보고서에서는 조회수 및 estimatedMinutesWatched 측정항목을 지원하므로 채널 소유자가 metrics 매개변수를 views,estimatedMinutesWatched로 설정합니다.
dimensions 매개변수의 경우 채널 소유자에게 여러 옵션이 있습니다. 이 중 두 개는 다음 목록에 나와 있으며, 세 번째는 이 섹션의 뒷부분에 나오는 filters 매개변수 값에 관한 설명에 설명되어 있습니다.
- 매개변수 값을 deviceType로 설정하면 조회수 및 시청 시간이 보고서에서 다루는 전체 기간 동안 기기 유형별로 그룹화됩니다. 따라서 이 값을 사용하면 다음과 같은 질문에 대한 답을 얻을 수 있습니다.
  - 2015년 6월 1일부터 2015년 7월 31일까지 휴대기기에서 이 채널의 동영상을 몇 회 시청했나요?
  - 2015년 6월 1일부터 2015년 7월 31일까지 게임 콘솔에서 채널의 동영상 조회수가 몇 회였나요?
  이 보고서에는 각 기기 유형의 총 조회수와 시청 시간이 포함됩니다.
- 매개변수 값을 day,deviceType로 설정하면 보고 기간 동안 조회수와 시청 시간이 기기 유형별로 계산됩니다. 따라서 이 값을 사용하면 다음과 같은 질문에 대한 답을 얻을 수 있습니다.
  - 2015년 6월 1일 휴대기기에서 채널의 동영상이 몇 회나 조회되었나요?
  - 2015년 7월 14일의 텔레비전에서 채널의 동영상을 몇 번 봤나요?
마지막으로 filters 매개변수를 사용하면 채널 소유자가 보고서에 특정 필터 값과 일치하는 데이터만 포함하도록 제한할 수 있습니다. 이 보고서는 너무 많은 필터링 옵션을 지원하여 모든 항목을 설명할 수 있으므로 이 예는 생성할 수 있는 보고서의 일부만 표시합니다.
- 채널 소유자는 Android 운영체제의 값만 반환하도록 요청을 필터링할 수 있습니다. 보고서 기간 동안 Android 휴대기기에서 발생한 조회수는 얼마나 되나요?
- 채널 소유자는 특정 국가의 값만 반환하도록 요청을 필터링할 수 있습니다. (보고 기간 동안 캐나다에서 동영상을 시청한 횟수)
- 채널 소유자는 특정 동영상의 값만 반환하도록 요청을 필터링할 수 있습니다. 하지만 video 필터가 쉼표로 구분된 값 목록을 지원하므로 보고서에 실제로 많은 동영상의 데이터가 포함될 수 있습니다.
  
  또한 동영상 필터가 여러 값을 지정하는 경우 동영상을 측정기준으로 지정할 수도 있습니다. 즉, dimensions 매개변수는 deviceType,video 및 day,deviceType,video 값도 지원합니다.
  - 채널 소유자가 측정기준 목록에 동영상을 포함하면 측정항목에서 각 동영상에 대한 개별 값을 지정합니다. 2015년 6월 1일에 게임 콘솔에서 동영상 XYZ를 몇 번 봤나요?
  - 채널 소유자가 측정기준 목록에 동영상을 포함하지 않으면 측정항목은 지정된 모든 동영상을 포괄하는 총 값을 지정합니다. 2015년 6월 1일 게임 콘솔에서 ABC, DEF, XYZ를 시청한 횟수는 얼마나 되나요?

보고서 검색

보고서를 검색하려면 API의 reports.query 메서드에 승인된 GET 요청을 보내 검색하려는 보고서를 정의하는 매개변수를 지정합니다.

API가 지원하는 보고서 목록은 채널 보고서 및 콘텐츠 소유자 보고서 문서를 참고하세요. 각 보고서 정의는 보고서에서 metrics, dimensions, filters 매개변수에 허용하는 값을 식별합니다.

권장사항

YouTube Analytics API를 사용하는 애플리케이션은 항상 다음 권장사항을 따라야 합니다.

응답의 헤더 행을 사용하여 보고서 열의 순서를 결정합니다. 예를 들어 조회수가 보고서 설명에 나열된 첫 번째 측정항목이라고 해서 응답으로 반환되는 첫 번째 측정항목이라고 가정하지 마세요. 대신 응답의 헤더 행을 사용하여 해당 데이터를 포함하는 열을 결정합니다.
YouTube Data API를 사용하여 YouTube Analytics API 응답에서 식별된 리소스의 추가 메타데이터를 검색할 수 있습니다. YouTube API 서비스 개발자 정책 (III.E.4.b~III.E.4.d 섹션)에 명시된 대로 API 클라이언트는 30일 후 API에서 저장된 리소스 메타데이터를 삭제하거나 새로고침해야 합니다.

측정항목 및 삭제된 항목 집계

YouTube Analytics API 응답에는 삭제된 항목에 대한 측정항목 분석이 포함되지 않습니다. 예를 들어 채널 소유자가 동영상을 삭제하면 동영상별로 측정항목을 반환하는 API 응답에 해당 동영상이 더 이상 표시되지 않습니다. 하지만 리소스 집합의 측정항목을 집계하는 보고서에는 삭제된 항목과 연결된 측정항목이 계속 포함됩니다.

예를 들어 채널 소유자가 두 개의 보고서를 검색한다고 가정해 보겠습니다. 첫 번째 보고서에는 특정 기간 동안 채널의 모든 동영상에 대한 총 일일 조회수가 나열됩니다. 두 번째 보고서에는 같은 기간의 총 동영상 조회수가 동영상별로 표시됩니다.

이 경우 첫 번째 보고서의 수치에는 일일 집계가 포함되어 있으므로 나중에 삭제된 동영상의 조회수가 포함됩니다. 하지만 두 번째 보고서에는 동영상별 조회수가 표시되므로 두 번째 보고서에는 삭제된 항목과 관련된 조회수가 포함되지 않습니다. 따라서 보고서에서 다루는 기간에 동영상이 삭제된 경우 첫 번째 보고서에 보고된 총 일일 조회수가 두 번째 보고서의 일일 동영상별 조회수의 총계보다 많을 수 있습니다.

데이터 익명처리

측정항목이 특정 기준을 충족하지 않을 경우 일부 YouTube 분석 데이터는 제한됩니다. 이러한 현상은 다양한 보고서에서 발생할 수 있습니다. 실제로 다음과 같은 경우 보고서에 데이터 전체 또는 일부가 포함되지 않을 수 있습니다.

지정된 기간 동안 동영상 또는 채널의 트래픽이 제한적임

또는
트래픽 소스 또는 국가 등의 값이 특정 기준점을 충족하지 않는 필터 또는 측정기준을 선택했습니다.

데이터가 제한적인 경우 보고서의 데이터 집계 방식에 따라 보고되는 총계가 다를 수 있습니다.

예를 들어 채널 소유자가 두 개의 보고서를 검색한다고 가정해 보겠습니다. 첫 번째 보고서에는 특정 동영상의 총 조회수가 나열되고 두 번째 보고서에는 해당 동영상의 총 조회수가 국가별로 나열됩니다. 특정 기간 동안 동영상의 조회수가 1, 000회라고 가정하고, 미국에서는 500회, 캐나다에서는 498회, 프랑스에서는 2회가 발생했습니다.

이 예에서 첫 번째 보고서는 동영상 조회수가 1, 000회임을 나타냅니다. 두 번째 보고서는 미국에서는 500회, 캐나다에서는 498회만 조회되었음을 나타냅니다. 따라서 두 보고서의 총 조회수에는 차이가 있을 수 있습니다. 두 번째 보고서에는 다른 두 개의 조회수도 발생했음을 나타내거나 프랑스에서 발생한 조회수가 포함되지 않습니다.

데이터가 제한되는 실제 기준은 게시되지 않으며 YouTube의 재량에 따라 변경될 수 있습니다.

제한적인 데이터 유형

YouTube 분석 보고서에서는 다음과 같은 데이터가 제한될 수 있습니다.

인구통계 데이터(예: 연령, 성별)
국가 또는 지역 등 시청자가 위치한 국가 또는 지역과 관련된 측정항목 또는 측정기준을 포함한 지역 데이터입니다. 하지만 보고서는 지역 기준점을 수익 측정항목에 적용하지 않습니다.
동영상 조회수로 이어진 외부 트래픽이나 검색어 등 특정 트래픽 소스와 관련된 측정항목입니다. 예를 들어 매우 적은 수의 조회수를 발생시키는 검색어 및 URL은 보고서에 표시되지 않습니다. 하지만 콘텐츠로 많은 시청자를 유도하는 검색어 및 URL이 계속 표시됩니다.

YouTube 분석 보고서의 제한된 데이터에 대한 자세한 내용은 YouTube 고객센터를 참고하세요.

할당량 사용

API 요청마다 API 요청 1개의 단위로 계산됩니다. 할당량 한도는 Google API 콘솔의 할당량 패널에 표시됩니다.