Reports: Query

중요: 이제 이 메서드에 대한 API 요청 시 https://www.googleapis.com/auth/youtube.readonly 범위에 액세스해야 합니다.

이 방법을 사용하면 다양한 애널리틱스 보고서를 검색할 수 있습니다. 각 요청은 쿼리 매개변수를 사용하여 채널 ID 또는 콘텐츠 소유자, 시작일, 종료일, 하나 이상의 측정항목을 지정합니다. 측정기준, 필터, 정렬 지침과 같은 추가 쿼리 매개변수를 제공할 수도 있습니다.

  • 측정항목은 동영상 조회수 또는 평점 (좋아요 및 싫어요) 등 사용자 활동의 개별 측정값입니다.
  • 측정기준은 사용자 활동이 발생한 날짜 또는 사용자 거주 국가와 같은 데이터를 집계하는 데 사용되는 일반적인 기준입니다. 보고서의 각 데이터 행에는 측정기준 값의 고유한 조합이 있습니다.
  • 필터는 검색할 데이터를 지정하는 측정기준 값입니다. 예를 들어 특정 국가, 특정 동영상, 동영상 그룹에 대한 데이터를 검색할 수 있습니다.

참고: YouTube 파트너 프로그램에 참여하는 YouTube 콘텐츠 파트너만 콘텐츠 소유자 보고서를 이용할 수 있습니다.

일반적인 사용 사례

요청

HTTP 요청

GET https://youtubeanalytics.googleapis.com/v2/reports

모든 YouTube Analytics API 요청은 승인된 상태여야 합니다. 승인 가이드에서는 OAuth 2.0 프로토콜을 사용하여 승인 토큰을 검색하는 방법을 설명합니다.

YouTube Analytics API 요청은 다음 승인 범위를 사용합니다.

범위
https://www.googleapis.com/auth/yt-analytics.readonly YouTube 콘텐츠에 관한 YouTube 분석 보고서를 봅니다. 이 범위를 사용하여 사용자 활동 측정항목(예: 조회수, 평가 횟수)을 조회할 수 있습니다.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube 콘텐츠에 대한 YouTube 분석 수익 보고서를 봅니다. 이 범위를 통해 사용자 활동 측정항목, 예상 수익, 광고 실적 측정항목에 액세스할 수 있습니다.
https://www.googleapis.com/auth/youtube YouTube 계정을 관리합니다. YouTube Analytics API에서 채널 소유자는 이 범위를 사용하여 YouTube 분석 그룹과 그룹 항목을 관리합니다.
https://www.googleapis.com/auth/youtubepartner YouTube에서 YouTube 저작물 및 관련 콘텐츠를 보고 관리합니다. YouTube Analytics API에서 콘텐츠 소유자는 이 범위를 사용하여 YouTube 분석 그룹과 그룹 항목을 관리합니다.

매개변수

다음 표에는 쿼리 보고서를 검색하기 위한 API 요청에 대한 필수 및 선택적 쿼리 매개변수가 나와 있습니다. 표에 나열된 표준 쿼리 매개변수도 선택사항이며 여러 Google API에서 지원됩니다.

매개변수
필수 매개변수
endDate string
YouTube Analytics 데이터를 가져오는 종료일입니다. 값은 YYYY-MM-DD 형식이어야 합니다.

API 응답에는 쿼리 시점에 쿼리의 모든 측정항목을 사용할 수 있는 마지막 날까지의 데이터가 포함됩니다. 예를 들어 요청에서 종료일을 2017년 7월 5일로 지정하고 요청된 모든 측정항목의 값을 2017년 7월 3일까지만 사용할 수 있는 경우, 이 날짜가 2017년 7월 3일까지만 응답에 데이터가 포함됩니다. 요청된 측정항목 중 일부의 데이터가 2017년 7월 4일에 대한 데이터인 경우에도 마찬가지입니다.
참고: API 버전 1에서는 이 매개변수의 이름이 end-date였습니다.
ids string
YouTube Analytics 데이터를 검색 중인 YouTube 채널 또는 콘텐츠 소유자를 확인합니다.

  • YouTube 채널 데이터를 요청하려면 ids 매개변수 값을 channel==MINE 또는 channel==CHANNEL_ID로 설정하세요. 여기서 CHANNEL_ID는 현재 인증된 사용자의 YouTube 채널을 식별합니다.
  • YouTube 콘텐츠 소유자 데이터를 요청하려면 ids 매개변수 값을 contentOwner==OWNER_NAME로 설정합니다. 여기서 OWNER_NAME는 사용자의 content owner ID입니다.

metrics string
YouTube Analytics 측정항목을 쉼표로 구분한 목록입니다(예: views 또는 likes,dislikes). 검색할 수 있는 보고서 목록과 각 보고서에서 사용할 수 있는 측정항목은 채널 보고서 또는 콘텐츠 소유자 보고서에 대한 문서를 참조하세요. 측정항목 문서에는 모든 측정항목에 대한 정의가 포함되어 있습니다.
startDate string
YouTube Analytics 데이터를 가져오는 시작일입니다. 값은 YYYY-MM-DD 형식이어야 합니다.
참고: API 버전 1에서는 이 매개변수의 이름이 start-date였습니다.
선택적 매개변수
currency string
API에서 다음과 같은 예상 수익 측정항목을 지정하는 데 사용할 통화로, estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm입니다. 이러한 측정항목에 대해 API가 반환하는 값은 매일 변하는 환율을 사용하여 계산된 추정치입니다. 이러한 측정항목이 요청되지 않으면 매개변수가 무시됩니다.

매개변수 값은 아래 통화 목록에 있는 3자리 ISO 4217 통화 코드입니다. 지원되지 않는 통화가 지정된 경우 API에서 오류를 반환합니다. 기본값은 USD입니다.
dimensions string
쉼표로 구분된 YouTube 분석 측정기준 목록(예: video 또는 ageGroup,gender) 검색할 수 있는 보고서 목록과 이러한 보고서에 사용되는 측정기준은 채널 보고서 또는 콘텐츠 소유자 보고서에 대한 문서를 참조하세요. (측정기준 문서에는 모든 측정기준에 대한 정의가 포함되어 있습니다.)
filters string
YouTube Analytics 데이터를 가져올 때 적용해야 하는 필터 목록입니다. 채널 보고서 및 콘텐츠 소유자 보고서 문서에는 각 보고서를 필터링하는 데 사용할 수 있는 측정기준이 설명되어 있으며 측정기준 문서는 이러한 측정기준을 정의합니다.

요청에서 여러 필터를 사용하는 경우 세미콜론 (;)으로 필터를 결합하면 반환된 결과 표가 두 필터를 모두 충족합니다. 예를 들어 filters 매개변수 값 video==dMH0bHeiRNg;country==IT는 이탈리아에서 지정된 동영상의 데이터를 포함하도록 결과 집합을 제한합니다.

필터에 여러 값 지정

API는 video, playlist, channel 필터에 여러 값을 지정할 수 있는 기능을 지원합니다. 이렇게 하려면 API 응답을 필터링해야 하는 동영상, 재생목록 또는 채널 ID로 구분된 목록을 지정합니다. 예를 들어 filters 매개변수 값 video==pd1FJh59zxQ,Zhawgd0REhA;country==IT는 이탈리아에서 지정된 동영상의 데이터를 포함하도록 결과 집합을 제한합니다. 매개변수 값은 최대 500개의 ID를 지정할 수 있습니다.

동일한 필터에 여러 값을 지정하는 경우 요청에 지정하는 측정기준 목록에 해당 필터를 추가할 수도 있습니다. 이는 필터가 특정 보고서에서 지원되는 측정기준으로 등록되지 않은 경우에도 마찬가지입니다. 측정기준 목록에 필터를 추가하면 API에서도 필터 값을 사용하여 결과를 그룹화합니다.

예를 들어 시청자가 채널의 동영상 콘텐츠에 도달한 방식에 따라 시청 통계를 집계하는 채널의 트래픽 소스 보고서를 검색한다고 가정해 보겠습니다. 또한 요청의 filters 매개변수 요청이 데이터를 반환해야 하는 동영상 10개의 목록을 식별한다고 가정해 보겠습니다.
  • dimensions 매개변수의 값에 video를 추가하면 API 응답은 동영상 10개 각각에 대해 별도의 트래픽 소스 통계를 제공합니다.
  • video를 dimensions 매개변수 값에 추가하지 않으면 API 응답은 동영상 10개 모두에 대한 트래픽 소스 통계를 집계합니다.
includeHistoricalChannelData boolean
참고: 이 매개변수는 콘텐츠 소유자 보고서에만 적용됩니다.

채널이 콘텐츠 소유자와 연결되기 이전 기간의 채널 시청 시간 및 조회 데이터를 API 응답에 포함해야 하는지를 나타냅니다. 기본 매개변수 값은 false이며, 이 경우 API 응답에 채널이 콘텐츠 소유자와 연결된 날짜의 시청 시간 및 조회수 데이터만 포함됩니다.

서로 다른 날짜에 콘텐츠 소유자와 연결된 채널이 다를 수 있다는 점에 유의해야 합니다. API 요청이 여러 채널의 데이터를 가져오고 매개변수 값이 false인 경우 API 응답에는 각 채널의 연결 날짜를 기준으로 하는 데이터가 포함됩니다. 매개변수 값이 true이면 API 응답에 API 요청에 지정된 날짜와 일치하는 데이터가 포함됩니다.
참고: API 버전 1에서는 이 매개변수의 이름이 include-historical-channel-data였습니다.
maxResults integer
응답에 포함할 최대 행 수입니다.
참고: API 버전 1에서는 이 매개변수의 이름이 max-results였습니다.
sort string
YouTube 분석 데이터의 정렬 순서를 결정하는 측정기준 또는 측정항목을 쉼표로 구분한 목록입니다. 기본 정렬 순서는 오름차순입니다. - 접두사를 사용하면 내림차순이 됩니다.
startIndex integer
검색할 첫 번째 항목의 1부터 시작하는 색인입니다. (기본값은 1입니다.) 이 매개변수를 max-results 매개변수와 함께 페이지로 나누기 메커니즘으로 사용합니다.
참고: API 버전 1에서는 이 매개변수의 이름이 start-index였습니다.
표준 매개변수
access_token 현재 사용자의 OAuth 2.0 토큰입니다.
alt 이 매개변수는 JSON 응답만 지원하는 API 버전 2에서는 지원되지 않습니다.API 응답의 데이터 형식입니다.
  • 유효한 값: json, csv
  • 기본값은 json입니다.
callback 콜백 함수입니다.
  • 응답을 처리하는 자바스크립트 콜백 함수의 이름입니다.
  • JavaScript JSON-P 요청에서 사용됩니다.
prettyPrint

들여쓰기와 줄바꿈이 적용된 응답을 반환합니다.

  • true인 경우 사람이 읽을 수 있는 형식으로 응답을 반환합니다.
  • 기본값은 true입니다.
  • false로 설정하면 응답 페이로드 크기가 줄어들어 일부 환경에서 성능이 개선될 수 있습니다.
quotaUser 이 매개변수는 현재 지원이 중단된 API 버전 1에서 지원되었습니다. 이 매개변수는 API 버전 2에서 지원되지 않습니다.
userIp 이 매개변수는 현재 지원이 중단된 API 버전 1에서 지원되었습니다. 이 매개변수는 API 버전 2에서 지원되지 않습니다.

요청 본문

이 메서드를 호출할 때 요청 본문을 전송하지 않습니다.

응답

alt 매개변수 정의에 설명된 대로 API는 JSON 또는 CSV 형식으로 응답을 반환할 수 있습니다. 각 유형의 응답 본문에 대한 정보는 아래와 같습니다.

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
속성
kind string
이 값은 API 응답에 포함되는 데이터 유형을 지정합니다. query 메서드의 경우 kind 속성 값은 youtubeAnalytics#resultTable입니다. 그러나 API가 다른 메서드에 대한 지원을 추가하면 이러한 메서드에 대한 API 응답에서 다른 kind 속성 값을 도입할 수 있습니다.
columnHeaders[] list
이 값은 rows 필드에서 반환된 데이터에 대한 정보를 지정합니다. columnHeaders 목록의 각 항목은 rows 값에 반환된 필드를 식별하며, 여기에는 쉼표로 구분된 데이터 목록이 포함됩니다.

columnHeaders 목록은 API 요청에 지정된 측정기준으로 시작되며, 그 뒤에 API 요청에 지정된 측정항목이 나옵니다. 측정기준과 측정항목의 순서는 API 요청의 순서와 일치합니다.

예를 들어 API 요청에 dimensions=ageGroup,gender&metrics=viewerPercentage 매개변수가 포함된 경우 API 응답은 ageGroup,gender,viewerPercentage 순서로 열을 반환합니다.
columnHeaders[].name string
측정기준 또는 측정항목의 이름입니다.
columnHeaders[].columnType string
열의 유형입니다 (DIMENSION 또는 METRIC).
columnHeaders[].dataType string
열의 데이터 유형입니다 (STRING, INTEGER, FLOAT 등).
rows[] list
목록에 결과 테이블의 모든 행이 포함됩니다. 목록의 각 항목은 데이터의 단일 행에 해당하는 쉼표로 구분된 데이터가 포함된 배열입니다. 쉼표로 구분된 데이터 필드의 순서는 columnHeaders 필드에 나열된 열 순서와 일치합니다.

지정된 쿼리에 사용할 수 있는 데이터가 없으면 응답에서 rows 요소가 생략됩니다.

day 측정기준을 사용한 쿼리에 대한 응답에는 최근 며칠 동안의 행이 포함되지 않습니다.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

예

참고: 다음 코드 샘플은 지원되는 일부 프로그래밍 언어를 나타냅니다. 지원되는 언어 목록을 보려면 클라이언트 라이브러리 문서를 참조하세요.

JavaScript

이 예에서는 YouTube Analytics API를 호출하여 2017년 한 해 동안 승인된 사용자 채널의 일일 조회수 및 기타 측정항목을 검색합니다. 이 샘플은 Google API JavaScript 클라이언트 라이브러리를 사용합니다.

이 샘플을 로컬에서 처음 실행하기 전에 프로젝트에 승인 사용자 인증 정보를 설정해야 합니다.
  1. Google API 콘솔에서 프로젝트를 만들거나 선택합니다.
  2. 프로젝트에 YouTube Analytics API를 사용 설정합니다.
  3. 사용자 인증 정보 페이지 상단에서 OAuth 동의 화면 탭을 선택합니다. 이메일 주소를 선택하고 아직 설정되지 않은 경우 제품 이름을 입력한 다음 저장 버튼을 클릭합니다.
  4. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 버튼을 클릭하고 OAuth 클라이언트 ID를 선택합니다.
  5. 애플리케이션 유형을 '웹 애플리케이션'으로 선택합니다.
  6. 승인된 자바스크립트 출처 입력란에 코드 샘플을 제공할 URL을 입력합니다. 예를 들어 http://localhost:8000 또는 http://yourserver.example.com 등을 사용할 수 있습니다. 승인된 리디렉션 URI 입력란은 비워 둘 수 있습니다.
  7. 만들기 버튼을 클릭하여 사용자 인증 정보 만들기를 마칩니다.
  8. 대화상자를 닫기 전에 클라이언트 ID를 복사합니다. 이 ID를 코드 샘플에 입력해야 합니다.

그런 다음 샘플을 로컬 파일에 저장합니다. 샘플에서 다음 줄을 찾아 YOUR_CLIENT_ID를 승인 사용자 인증 정보를 설정할 때 가져온 클라이언트 ID로 바꿉니다.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

이제 실제로 샘플을 테스트할 준비가 되었습니다.

  1. 웹브라우저에서 로컬 파일을 열고 브라우저에서 디버깅 콘솔을 엽니다. 두 개의 버튼을 표시하는 페이지가 표시됩니다.
  2. 승인 및 로드 버튼을 클릭하여 사용자 승인 과정을 시작합니다. 앱이 채널 데이터를 검색하도록 승인하면 브라우저의 콘솔에 다음 줄이 출력되어야 합니다. 
    Sign-in successful
GAPI client loaded for API
  3. 위의 행 대신 오류 메시지가 표시되면 프로젝트에 설정한 승인된 리디렉션 URI에서 스크립트를 로드하고 위에 설명된 대로 클라이언트 ID를 코드에 입력했는지 확인합니다.
  4. execute 버튼을 클릭하여 API를 호출합니다. 브라우저에서 콘솔에 출력된 response 객체를 확인할 수 있습니다. 이 객체에서 result 속성은 API 데이터가 포함된 객체에 매핑됩니다.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

이 예에서는 YouTube Analytics API를 호출하여 2017년 한 해 동안 승인된 사용자 채널의 일일 조회수 및 기타 측정항목을 검색합니다. 이 샘플은 Google API Python 클라이언트 라이브러리를 사용합니다.

이 샘플을 로컬에서 처음 실행하기 전에 프로젝트에 승인 사용자 인증 정보를 설정해야 합니다.
  1. Google API 콘솔에서 프로젝트를 만들거나 선택합니다.
  2. 프로젝트에 YouTube Analytics API를 사용 설정합니다.
  3. 사용자 인증 정보 페이지 상단에서 OAuth 동의 화면 탭을 선택합니다. 이메일 주소를 선택하고 아직 설정되지 않은 경우 제품 이름을 입력한 다음 저장 버튼을 클릭합니다.
  4. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 버튼을 클릭하고 OAuth 클라이언트 ID를 선택합니다.
  5. 애플리케이션 유형으로 Other를 선택하고 이름을 'YouTube Analytics API Quickstart'로 입력한 후 만들기 버튼을 클릭합니다.
  6. OK(확인)를 클릭하여 결과 대화상자를 닫습니다.
  7. 클라이언트 ID 오른쪽에 있는 (JSON 다운로드) 버튼을 클릭합니다.
  8. 다운로드한 파일을 작업 디렉터리로 이동합니다.

또한 Python용 Google API 클라이언트 라이브러리와 몇 가지 추가 라이브러리를 설치해야 합니다.

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

이제 실제로 샘플을 테스트할 준비가 되었습니다.

  1. 아래의 코드 샘플을 작업 디렉터리에 복사합니다.
  2. 이 샘플에서는 승인 사용자 인증 정보를 설정한 후 다운로드한 파일의 위치와 일치하도록 CLIENT_SECRETS_FILE 변수의 값을 업데이트합니다.
  3. 터미널 창에서 샘플 코드를 실행합니다. 
    python yt_analytics_v2.py
  4. 승인 흐름을 진행합니다. 인증 흐름이 브라우저에 자동으로 로드되거나 브라우저 창에 인증 URL을 복사해야 할 수 있습니다. 필요한 경우 인증 흐름이 끝날 때 브라우저에 표시된 인증 코드를 터미널 창에 붙여넣고 [return]을 클릭합니다.
  5. API 쿼리가 실행되고 JSON 응답이 터미널 창에 출력됩니다.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

사용해 보기

APIs Explorer를 사용하여 이 API를 호출하고 API 요청 및 응답을 확인하세요.