YouTube Analytics API - Data Model

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

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

    보고서에서 각 데이터 행에는 측정기준 값의 고유한 조합이 있습니다. 따라서 보고서에 선택한 측정기준에 따라 YouTube에서 해당 보고서의 측정항목 값을 계산하는 방식이 결정됩니다.

  • 측정항목은 사용자 활동, 광고 실적 또는 예상 수익과 관련된 개별 측정값입니다. 사용자 활동 측정항목에는 동영상 조회수, 평가 (좋아요 및 싫어요) 등이 포함됩니다.

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

보고서 매개변수 선택

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

  • 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 휴대기기에서 발생한 조회수는 몇 회인가요?)

    • 채널 소유자는 특정 국가의 값만 반환하도록 요청을 필터링할 수 있습니다. (보고 기간의 각 날짜에 캐나다에서 동영상이 조회된 횟수)

    • 채널 소유자는 특정 동영상에 대해서만 값을 반환하도록 요청을 필터링할 수 있습니다. 하지만 동영상 필터는 쉼표로 구분된 값 목록을 지원하므로 보고서에 실제로 여러 동영상의 데이터가 포함될 수 있습니다.

      또한 동영상 필터에 값이 여러 개 지정된 경우 동영상을 측정기준으로 지정할 수도 있습니다. 즉, 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 분석 API 응답에는 삭제된 항목의 측정항목 분류가 포함되지 않습니다. 예를 들어 채널 소유자가 동영상을 삭제하면 동영상별 측정항목을 반환하는 API 응답에 해당 동영상이 더 이상 표시되지 않습니다. 하지만 리소스 집합의 측정항목을 집계하는 보고서에는 삭제된 항목과 연결된 측정항목이 계속 포함됩니다.

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

이 경우 첫 번째 보고서에는 일일 집계가 포함되므로 나중에 삭제된 동영상의 조회수가 포함됩니다. 하지만 두 번째 보고서에는 삭제된 항목과 연결된 조회수가 포함되지 않습니다. 두 번째 보고서에는 동영상별 조회수가 표시되기 때문입니다. 따라서 보고서에 포함된 기간 동안 채널에서 동영상을 삭제한 경우 첫 번째 보고서에 보고된 총 일일 조회수가 두 번째 보고서의 일일 동영상별 조회수 합계보다 높을 수 있습니다.

데이터 익명 처리

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

  1. 지정된 기간 동안 동영상 또는 채널의 트래픽이 제한된 경우

    또는

  2. 값이 특정 기준점에 도달하지 않는 트래픽 소스 또는 국가와 같은 필터 또는 측정기준을 선택한 경우

데이터가 제한적인 경우 보고서의 데이터 합산 방식에 따라 보고서별로 보고된 총계가 다를 수 있습니다.

예를 들어 채널 소유자가 보고서 두 개를 가져온다고 가정해 보겠습니다. 첫 번째 보고서에는 특정 동영상의 총조회수가 표시되고 두 번째 보고서에는 해당 동영상의 총조회수가 국가별로 표시됩니다. 이때 지정된 기간 동안 동영상이 1,000회 조회되었는데 조회수의 500회는 미국에서, 498회는 캐나다에서, 2회는 프랑스에서 발생했다고 가정합니다.

이 예에서 첫 번째 보고서에는 동영상이 1, 000회 조회된 것으로 표시됩니다. 두 번째 보고서에는 동영상이 미국에서 500회, 캐나다에서 498회 조회된 것으로만 표시됩니다. 따라서 두 보고서의 총 조회수 간에 차이가 있습니다. 두 번째 보고서에는 다른 두 개의 조회가 발생했거나 프랑스에서 조회가 발생했다는 사실이 표시되지 않습니다.

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

제한된 데이터 유형

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

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

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

할당량 사용

전송하는 각 API 요청은 API 사용량 할당량의 1단위로 계산됩니다. 할당량 한도는 Google API 콘솔의 할당량 패널에 표시됩니다.