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개월 동안의 데이터가 포함됩니다.기기 유형 보고서는 views 및 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값도 지원합니다.
데이터 업데이트 빈도 및 지연 시간
YouTube Analytics API는 타겟팅된 쿼리를 지원하지만 기본 분석 데이터는 실시간이 아닙니다. 데이터 처리에는 일반적으로 48~72시간의 지연 시간이 발생합니다. 따라서 API 응답에는 최근 며칠간의 데이터가 포함되지 않으며, 보고서의 endDate에는 요청된 모든 측정항목이 완전히 처리된 마지막 날까지의 데이터만 포함됩니다.
데이터 지연 시간으로 인해 API에서 반환된 데이터와 YouTube 스튜디오에 표시되는 실시간 측정항목 간에 불일치가 발생할 수 있습니다. 애플리케이션에서 현재 조회수, 좋아요 수, 댓글 수와 같은 개별 동영상의 실시간 통계가 필요한 경우 YouTube Analytics API 대신 YouTube Data API의 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 분석 데이터가 제한됩니다. 이 문제는 다양한 보고서에서 발생할 수 있습니다. 실제로 다음과 같은 경우 보고서에 데이터가 일부 또는 전부 포함되지 않을 수 있습니다.
지정된 기간 동안 동영상 또는 채널의 트래픽이 제한된 경우
또는
값이 특정 기준점에 도달하지 않는 트래픽 소스 또는 국가와 같은 필터 또는 측정기준을 선택한 경우
데이터가 제한적인 경우 보고서의 데이터 합산 방식에 따라 보고서별로 보고된 총계가 다를 수 있습니다.
예를 들어 채널 소유자가 보고서 2개를 가져온다고 가정해 보겠습니다. 첫 번째 보고서에는 특정 동영상의 총조회수가 나열되고 두 번째 보고서에는 해당 동영상의 총조회수가 국가별로 나열됩니다. 이때 지정된 기간 동안 동영상이 1,000회 조회되었는데 조회수의 500회는 미국에서, 498회는 캐나다에서, 2회는 프랑스에서 발생했다고 가정합니다.
이 예에서 첫 번째 보고서에는 동영상이 1, 000회 조회된 것으로 표시됩니다. 두 번째 보고서에는 동영상이 미국에서 500회, 캐나다에서 498회 조회된 것으로만 표시됩니다. 따라서 두 보고서의 총 조회수 간에 차이가 있습니다. 두 번째 보고서에는 다른 두 개의 조회도 발생했다는 사실(또는 프랑스에서 조회가 발생했다는 사실)이 표시되지 않습니다.
데이터 유형 제한
YouTube 분석 보고서에서 다음 데이터가 제한될 수 있습니다.
- 연령, 성별 등의 인구통계 데이터
- 시청자가 위치한 국가 또는 지역과 관련된 측정항목 또는 측정기준을 포함한 지리적 데이터(예: 국가 또는 지역) 하지만 보고서에서는 수익 측정항목에 지역 기준을 적용하지 않습니다.
- 동영상 조회로 이어진 검색어나 외부 URL과 같은 특정 트래픽 소스와 관련된 측정항목 예를 들어 조회수가 매우 적은 검색어와 URL은 보고서에 표시되지 않지만, 콘텐츠로 많은 시청자를 유도하는 검색어와 URL은 계속 표시됩니다.
YouTube 분석 보고서의 제한된 데이터에 대한 자세한 내용은 YouTube 고객센터를 참조하세요.
할당량 사용량
각 API 요청은 API 사용량 할당량의 1단위로 계산됩니다. 할당량 한도는 Google Cloud 콘솔의 할당량 패널에 표시됩니다.