Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

YouTube Analytics API - Data Model

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

측정기준 은 작업이 발생한 날짜 또는 사용자가 위치한 국가와 같이 데이터를 집계하는 데 사용되는 일반적인 기준입니다.

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

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

보고서 매개변수 선택

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일에 TV에서 채널 동영상이 조회된 횟수는 얼마인가요?
마지막으로 filters 매개변수를 사용하면 채널 소유자가 특정 필터 값과 일치하는 데이터만 포함하도록 보고서를 제한할 수 있습니다. 보고서에서 지원하는 필터링 옵션이 너무 많아 모두 설명할 수는 없으므로 이러한 예는 생성할 수 있는 보고서의 일부만 나타냅니다.
- 채널 소유자는 Android 운영체제의 값만 반환하도록 요청을 필터링할 수 있습니다. (보고 기간 동안 Android 휴대기기에서 조회수가 얼마나 발생했나요?)
- 채널 소유자는 특정 국가의 값만 반환하도록 요청을 필터링할 수 있습니다. (보고 기간의 각 날짜에 캐나다에서 동영상이 조회된 횟수는 얼마인가요?)
- 채널 소유자는 특정 동영상의 값만 반환하도록 요청을 필터링할 수 있습니다. 그러나 동영상 필터는 쉼표로 구분된 값 목록을 지원하므로 보고서에는 실제로 여러 동영상의 데이터가 포함될 수 있습니다.
  
  또한 동영상 필터에서 여러 값을 지정하는 경우 동영상을 측정기준으로 지정할 수도 있습니다. 즉, dimensions 매개변수는 deviceType,video 및 day,deviceType,video 값도 지원합니다.
  - 채널 소유자가 측정기준 목록에 동영상을 포함하면 측정항목은 각 동영상의 개별 값을 지정합니다. (2015년 6월 1일에 게임 콘솔에서 동영상 XYZ가 조회된 횟수는 얼마인가요?)
  - 채널 소유자가 측정기준 목록에 동영상을 포함하지 않으면 측정항목은 지정된 모든 동영상을 포함하는 총 값을 지정합니다. (2015년 6월 1일에 게임 콘솔에서 동영상 ABC, DEF, XYZ가 조회된 횟수는 얼마인가요?)

데이터 업데이트 및 지연 시간

YouTube Analytics API는 타겟팅된 쿼리를 지원하지만 기본 분석 데이터는 실시간이 아닙니다. 데이터 처리에는 일반적으로 48~72시간의 지연 시간이 발생합니다. 따라서 API 응답에는 가장 최근 날짜의 데이터가 포함되지 않으며 보고서의 endDate에는 요청된 모든 측정항목이 완전히 처리된 마지막 날짜까지의 데이터만 포함됩니다.

데이터 지연 시간을 고려할 때 API에서 반환된 데이터와 YouTube 스튜디오에 표시되는 실시간 측정항목 간에 불일치가 발생할 수 있습니다. 애플리케이션에 현재 조회수, 좋아요 또는 댓글 수와 같은 개별 동영상의 실시간 통계가 필요한 경우 YouTube Analytics API 대신 YouTube Data API's videos.list 메서드를 사용하세요.

보고서 검색

보고서를 검색하려면 검색할 보고서를 정의하는 매개변수를 지정하여 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은 보고서에 표시되지 않지만 콘텐츠로 많은 시청자를 유도하는 검색어와 URL은 계속 표시됩니다.

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

할당량 사용량

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