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 분석 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
views 또는 likes,dislikes과 같은 YouTube Analytics 측정항목의 쉼표로 구분된 목록입니다. 검색할 수 있는 보고서와 각 보고서에서 사용할 수 있는 측정항목 목록은 채널 보고서 또는 콘텐츠 소유자 보고서 문서를 참고하세요. 측정항목 문서에는 모든 측정항목의 정의가 포함되어 있습니다.
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
video, ageGroup,gender과 같은 YouTube 분석 측정기준의 쉼표로 구분된 목록입니다. 가져올 수 있는 보고서와 해당 보고서에 사용되는 측정기준 목록은 채널 보고서 또는 콘텐츠 소유자 보고서 문서를 참고하세요. (측정기준 문서에는 모든 측정기준의 정의가 포함되어 있습니다.)
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개 동영상 각각에 대한 별도의 트래픽 소스 통계를 제공합니다.
  • dimensions 매개변수의 값에 video을 추가하지 않으면 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 콜백 함수의 이름입니다.
  • 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 값에 반환되는 필드를 식별합니다. 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, ...
...

참고: 다음 코드 샘플은 지원되는 모든 프로그래밍 언어를 나타내지 않을 수 있습니다. 지원되는 언어 목록은 클라이언트 라이브러리 문서를 참고하세요.

자바스크립트

이 예시에서는 YouTube 분석 API를 호출하여 2017년의 승인된 사용자의 채널에 대한 일일 조회수와 기타 측정항목을 가져옵니다. 이 샘플에서는 Google API JavaScript 클라이언트 라이브러리를 사용합니다.

이 샘플을 처음으로 로컬에서 실행하기 전에 프로젝트의 승인 사용자 인증 정보를 설정해야 합니다.
  1. Google API 콘솔에서 프로젝트를 만들거나 선택합니다.
  2. 프로젝트에서 YouTube 분석 API를 사용 설정합니다.
  3. 사용자 인증 정보 페이지 상단에서 OAuth 동의 화면 탭을 선택합니다. 이메일 주소를 선택하고, 아직 설정되지 않은 경우 제품 이름을 입력한 다음 저장 버튼을 클릭합니다.
  4. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 버튼을 클릭하고 OAuth 클라이언트 ID를 선택합니다.
  5. 애플리케이션 유형으로 웹 애플리케이션을 선택합니다.
  6. '승인된 JavaScript 원본' 필드에 코드 샘플을 제공할 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. 실행 버튼을 클릭하여 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>

Python

이 예시에서는 YouTube 분석 API를 호출하여 2017년의 승인된 사용자의 채널에 대한 일일 조회수와 기타 측정항목을 가져옵니다. 이 샘플에서는 Google API Python 클라이언트 라이브러리를 사용합니다.

이 샘플을 처음으로 로컬에서 실행하기 전에 프로젝트의 승인 사용자 인증 정보를 설정해야 합니다.
  1. Google API 콘솔에서 프로젝트를 만들거나 선택합니다.
  2. 프로젝트에서 YouTube 분석 API를 사용 설정합니다.
  3. 사용자 인증 정보 페이지 상단에서 OAuth 동의 화면 탭을 선택합니다. 이메일 주소를 선택하고, 아직 설정되지 않은 경우 제품 이름을 입력한 다음 저장 버튼을 클릭합니다.
  4. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 버튼을 클릭하고 OAuth 클라이언트 ID를 선택합니다.
  5. 애플리케이션 유형 기타를 선택하고 이름 'YouTube 분석 API 빠른 시작'을 입력한 후 만들기 버튼을 클릭합니다.
  6. 확인을 클릭하여 결과 대화상자를 닫습니다.
  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'
  )

기능을 사용해 보세요.

APIs Explorer를 사용하여 이 API를 호출하고 API 요청과 응답을 확인합니다.