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 분석 API에서 채널 소유자는 이 범위를 사용하여 YouTube 분석 그룹 및 그룹 항목을 관리합니다.
https://www.googleapis.com/auth/youtubepartner YouTube에서 YouTube 저작물과 관련 콘텐츠를 보고 관리합니다. YouTube 분석 API에서 콘텐츠 소유자는 이 범위를 사용하여 YouTube 분석 그룹 및 그룹 항목을 관리합니다.

매개변수

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

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

API 응답에는 쿼리 시 쿼리의 모든 측정항목을 사용할 수 있는 마지막 날까지의 데이터가 포함됩니다. 예를 들어 요청에서 2017년 7월 5일을 지정하고 요청된 모든 측정항목의 값이 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, totalRevenue, cpm, playbackBasedCpm을 지정하는 데 사용하는 통화입니다. API가 이러한 측정항목에 대해 반환하는 값은 매일 변경되는 환율을 사용하여 계산한 추정치입니다. 요청된 측정항목이 없으면 매개변수가 무시됩니다.

매개변수 값은 아래 통화 목록의 세 자리 ISO 4217 통화 코드입니다. 지원되지 않는 통화가 지정된 경우 API에서 오류를 반환합니다. 기본값은 USD입니다.

dimensions string
YouTube 분석 측정기준의 쉼표로 구분된 목록입니다(예: video 또는 ageGroup,gender). 검색할 수 있는 보고서의 목록과 이러한 보고서에 사용된 측정기준은 채널 보고서 또는 콘텐츠 소유자 보고서 문서를 참고하세요. 측정기준 문서에는 모든 측정기준의 정의가 포함되어 있습니다.
filters string
YouTube Analytics 데이터를 검색할 때 적용해야 하는 필터 목록입니다. 채널 보고서콘텐츠 소유자 보고서에 대한 문서에서는 각 보고서를 필터링하는 데 사용할 수 있는 측정기준을 확인하고 측정기준 문서는 이러한 측정기준을 정의합니다.

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

필터에 여러 값 지정

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

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

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

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

여러 채널이 각기 다른 날짜에 콘텐츠 소유자와 연결되었을 수 있다는 점에 유의해야 합니다. API 요청이 여러 채널의 데이터를 검색하고 매개변수 값이 false인 경우 API 응답에 각 채널의 연결 날짜를 기준으로 한 데이터가 포함됩니다. 매개변수 값이 true이면 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 콜백 함수입니다.
  • 응답을 처리하는 자바스크립트 콜백 함수의 이름입니다.
  • 자바스크립트 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, ...
...

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

자바스크립트

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

이 샘플을 처음으로 로컬에서 실행하기 전에 프로젝트에 대한 승인 사용자 인증 정보를 설정해야 합니다.
  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를 복사합니다.

그런 다음 샘플을 로컬 파일에 저장합니다. 샘플에서 다음 줄을 찾아 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 Analytics API를 호출하여 2017년을 승인하는 사용자 채널의 일일 조회수 및 기타 측정항목을 검색합니다. 이 샘플은 Google API Python 클라이언트 라이브러리를 사용합니다.

이 샘플을 처음으로 로컬에서 실행하기 전에 프로젝트에 대한 승인 사용자 인증 정보를 설정해야 합니다.
  1. Google API 콘솔에서 프로젝트를 만들거나 선택합니다.
  2. 프로젝트에 YouTube Analytics API를 사용 설정합니다.
  3. 사용자 인증 정보 페이지 상단에서 OAuth 동의 화면 탭을 선택합니다. 이메일 주소를 선택하고 아직 설정하지 않은 경우 제품 이름을 입력한 다음 저장 버튼을 클릭합니다.
  4. 사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 버튼을 클릭하고 Oauth 클라이언트 ID를 선택합니다.
  5. 애플리케이션 유형을 기타로 선택하고 'YouTube Analytics 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을 브라우저 창에 복사해야 할 수 있습니다. 승인 흐름이 끝나면 필요한 경우 브라우저에 표시된 승인 코드를 터미널 창에 붙여넣고 [반환]을 클릭합니다.
  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 요청 및 응답을 확인하세요.