Reports: Query

Penting: Permintaan API ke metode ini kini memerlukan akses ke cakupan https://www.googleapis.com/auth/youtube.readonly.

Metode ini memungkinkan Anda mengambil berbagai laporan Analytics. Setiap permintaan menggunakan parameter kueri untuk menentukan ID saluran atau pemilik konten, tanggal mulai, tanggal akhir, dan setidaknya satu metrik. Anda juga dapat memberikan parameter kueri tambahan, seperti dimensi, filter, dan petunjuk pengurutan.

  • Metrik adalah pengukuran individual aktivitas pengguna, seperti penayangan video atau rating (suka dan tidak suka).
  • Dimensi adalah kriteria umum yang digunakan untuk menggabungkan data, seperti tanggal terjadinya aktivitas pengguna atau negara tempat pengguna berada. Dalam laporan, setiap baris data memiliki kombinasi nilai dimensi yang unik.
  • Filter adalah nilai dimensi yang menentukan data yang akan diambil. Misalnya, Anda dapat mengambil data untuk negara tertentu, video tertentu, atau sekelompok video.

Catatan: Laporan pemilik konten hanya dapat diakses oleh partner konten YouTube yang berpartisipasi dalam Program Partner YouTube.

Kasus penggunaan umum

Permintaan

Permintaan HTTP

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

Semua permintaan YouTube Analytics API harus mendapatkan otorisasi. Panduan otorisasi menjelaskan cara menggunakan protokol OAuth 2.0 untuk mengambil token otorisasi.

Permintaan YouTube Analytics API menggunakan cakupan otorisasi berikut:

Cakupan
https://www.googleapis.com/auth/yt-analytics.readonly Melihat laporan YouTube Analytics untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna, seperti jumlah penayangan dan jumlah rating.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Melihat laporan moneter YouTube Analytics untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna serta metrik perkiraan pendapatan dan performa iklan.
https://www.googleapis.com/auth/youtube Mengelola akun YouTube Anda. Di YouTube Analytics API, pemilik channel menggunakan cakupan ini untuk mengelola grup YouTube Analytics dan item grup.
https://www.googleapis.com/auth/youtubepartner Melihat dan mengelola aset YouTube dan konten terkait di YouTube. Di YouTube Analytics API, pemilik konten menggunakan cakupan ini untuk mengelola grup YouTube Analytics dan item grup.

Parameter

Tabel berikut mencantumkan parameter kueri wajib dan opsional untuk permintaan API guna mengambil laporan kueri. Parameter kueri standar yang tercantum dalam tabel juga bersifat opsional dan didukung oleh banyak Google API.

Parameter
Parameter Wajib
endDate string
Tanggal akhir untuk mengambil data YouTube Analytics. Nilai harus dalam format YYYY-MM-DD.

Respons API berisi data hingga hari terakhir saat semua metrik dalam kueri tersedia pada saat kueri. Jadi, misalnya, jika permintaan menentukan tanggal akhir 5 Juli 2017, dan nilai untuk semua metrik yang diminta hanya tersedia hingga 3 Juli 2017, maka tanggal tersebut akan menjadi tanggal terakhir yang datanya disertakan dalam respons. (Hal ini benar meskipun data untuk beberapa metrik yang diminta tersedia untuk 4 Juli 2017.)
Catatan: Pada API versi 1, parameter ini diberi nama end-date.
ids string
Mengidentifikasi channel YouTube atau pemilik konten yang datanya Anda ambil YouTube Analytics.

  • Untuk meminta data channel YouTube, tetapkan nilai parameter ids ke channel==MINE atau channel==CHANNEL_ID, dengan CHANNEL_ID mengidentifikasi channel YouTube pengguna yang saat ini diautentikasi.
  • Untuk meminta data pemilik konten YouTube, tetapkan nilai parameter ids ke contentOwner==OWNER_NAME, dengan OWNER_NAME adalah content owner ID untuk pengguna.

metrics string
Daftar metrik YouTube Analytics yang dipisahkan koma, seperti views atau likes,dislikes. Lihat dokumentasi untuk laporan channel atau laporan pemilik konten untuk mengetahui daftar laporan yang dapat Anda ambil dan metrik yang tersedia di setiap laporan. (Dokumen Metrics berisi definisi untuk semua metrik.)
startDate string
Tanggal mulai untuk mengambil data YouTube Analytics. Nilai harus dalam format YYYY-MM-DD.
Catatan: Pada API versi 1, parameter ini diberi nama start-date.
Parameter Opsional
currency string
Mata uang yang akan digunakan API untuk menentukan perkiraan metrik pendapatan berikut: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Nilai yang ditampilkan API untuk metrik tersebut adalah estimasi yang dihitung menggunakan nilai tukar yang berubah setiap hari. Jika tidak ada metrik tersebut yang diminta, parameter akan diabaikan.

Nilai parameter adalah kode mata uang ISO 4217 tiga huruf dari daftar mata uang di bawah. API akan menampilkan error jika mata uang yang tidak didukung ditentukan. Nilai defaultnya adalah USD.

dimensions string
Daftar dimensi YouTube Analytics yang dipisahkan koma, seperti video atau ageGroup,gender. Lihat dokumentasi untuk laporan channel atau laporan pemilik konten untuk mengetahui daftar laporan yang dapat Anda ambil dan dimensi yang digunakan untuk laporan tersebut. (Dokumen Dimensi berisi definisi untuk semua dimensi.)
filters string
Daftar filter yang harus diterapkan saat mengambil data YouTube Analytics. Dokumentasi untuk laporan channel dan laporan pemilik konten mengidentifikasi dimensi yang dapat digunakan untuk memfilter setiap laporan, dan dokumen Dimensi menentukan dimensi tersebut.

Jika permintaan menggunakan beberapa filter, gabungkan filter tersebut dengan titik koma (;), dan tabel hasil yang ditampilkan akan memenuhi kedua filter. Misalnya, nilai parameter filters video==dMH0bHeiRNg;country==IT membatasi set hasil untuk menyertakan data untuk video tertentu di Italia.

Menentukan beberapa nilai untuk filter

API mendukung kemampuan untuk menentukan beberapa nilai untuk filter video, playlist, dan channel. Untuk melakukannya, tentukan daftar ID video, playlist, atau channel yang dipisahkan untuk respons API yang harus difilter. Misalnya, nilai parameter filters video==pd1FJh59zxQ,Zhawgd0REhA;country==IT membatasi set hasil untuk menyertakan data untuk video tertentu di Italia. Nilai parameter dapat menentukan hingga 500 ID.

Saat menentukan beberapa nilai untuk filter yang sama, Anda juga dapat menambahkan filter tersebut ke daftar dimensi yang Anda tentukan untuk permintaan. Hal ini berlaku meskipun filter tidak tercantum sebagai dimensi yang didukung untuk laporan tertentu. Jika Anda menambahkan filter ke daftar dimensi, API juga akan menggunakan nilai filter untuk mengelompokkan hasil.

Misalnya, Anda mengambil laporan sumber traffic channel, yang menggabungkan statistik penayangan berdasarkan cara penonton mengakses konten video channel. Misalkan juga bahwa permintaan parameter filters Anda mengidentifikasi daftar 10 video yang datanya harus ditampilkan.
  • Jika Anda menambahkan video ke nilai parameter dimensions, respons API akan memberikan statistik sumber traffic terpisah untuk masing-masing dari 10 video.
  • Jika Anda tidak menambahkan video ke nilai parameter dimensions, respons API akan menggabungkan statistik sumber traffic untuk semua 10 video.
includeHistoricalChannelData boolean
Catatan: Parameter ini hanya berlaku untuk laporan pemilik konten.

Menunjukkan apakah respons API harus menyertakan data waktu tonton dan penayangan channel dari jangka waktu sebelum channel ditautkan ke pemilik konten. Nilai parameter default adalah false yang berarti bahwa respons API hanya menyertakan data waktu tonton dan penayangan dari tanggal saat channel ditautkan ke pemilik konten.

Penting untuk diingat bahwa channel yang berbeda mungkin telah ditautkan ke pemilik konten pada tanggal yang berbeda. Jika permintaan API mengambil data untuk beberapa saluran dan nilai parameter adalah false, respons API akan berisi data berdasarkan tanggal penautan untuk setiap saluran terkait. Jika nilai parameter adalah true, respons API berisi data yang cocok dengan tanggal yang ditentukan dalam permintaan API.
Catatan: Pada API versi 1, parameter ini diberi nama include-historical-channel-data.
maxResults integer
Jumlah maksimum baris yang akan disertakan dalam respons.
Catatan: Pada API versi 1, parameter ini diberi nama max-results.
sort string
Daftar dimensi atau metrik yang dipisahkan koma yang menentukan urutan pengurutan untuk data YouTube Analytics. Secara default, urutan pengurutan adalah menaik. Awalan - menyebabkan urutan pengurutan menurun.
startIndex integer
Indeks berbasis 1 dari entitas pertama yang akan diambil. (Nilai defaultnya adalah 1.) Gunakan parameter ini sebagai mekanisme penomoran halaman bersama dengan parameter max-results.
Catatan: Pada API versi 1, parameter ini diberi nama start-index.
Parameter Standar
access_token Token OAuth 2.0 untuk pengguna saat ini.
alt Parameter ini tidak didukung di API versi 2, yang hanya mendukung respons JSON.Format data untuk respons API.
  • Nilai yang valid: json, csv
  • Nilai default: json
callback Fungsi callback.
  • Nama fungsi callback JavaScript yang menangani respons.
  • Digunakan dalam permintaan JSON-P JavaScript.
prettyPrint

Menampilkan respons dengan indentasi dan jeda baris.

  • Menampilkan respons dalam format yang dapat dibaca manusia jika true.
  • Nilai default: true.
  • Jika disetel ke false, ukuran payload respons dapat dikurangi, sehingga dapat meningkatkan performa di beberapa lingkungan.
quotaUser Parameter ini didukung di API versi 1, yang kini tidak digunakan lagi. Parameter ini tidak didukung di API versi 2.
userIp Parameter ini didukung di API versi 1, yang kini tidak digunakan lagi. Parameter ini tidak didukung di API versi 2.

Isi permintaan

Jangan mengirim isi permintaan saat memanggil metode ini.

Respons

Seperti yang tercantum dalam definisi parameter alt, API dapat menampilkan respons dalam format JSON atau CSV. Informasi tentang isi respons untuk setiap jenis ditampilkan di bawah:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Properti
kind string
Nilai ini menentukan jenis data yang disertakan dalam respons API. Untuk metode query, nilai properti kind adalah youtubeAnalytics#resultTable. Namun, jika API menambahkan dukungan untuk metode lain, respons API untuk metode tersebut dapat memperkenalkan nilai properti kind lainnya.
columnHeaders[] list
Nilai ini menentukan informasi tentang data yang ditampilkan di kolom rows. Setiap item dalam daftar columnHeaders mengidentifikasi kolom yang ditampilkan dalam nilai rows, yang berisi daftar data yang dibatasi koma.

Daftar columnHeaders dimulai dengan dimensi yang ditentukan dalam permintaan API, yang diikuti dengan metrik yang ditentukan dalam permintaan API. Urutan dimensi dan metrik cocok dengan urutan dalam permintaan API.

Misalnya, jika permintaan API berisi parameter dimensions=ageGroup,gender&metrics=viewerPercentage, respons API akan menampilkan kolom dalam urutan ini: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Nama dimensi atau metrik.
columnHeaders[].columnType string
Jenis kolom (DIMENSION atau METRIC).
columnHeaders[].dataType string
Jenis data dalam kolom (STRING, INTEGER, FLOAT, dll.).
rows[] list
Daftar ini berisi semua baris tabel hasil. Setiap item dalam daftar adalah array yang berisi data yang dibatasi koma yang sesuai dengan satu baris data. Urutan kolom data yang dibatasi koma akan cocok dengan urutan kolom yang tercantum di kolom columnHeaders.

Jika tidak ada data yang tersedia untuk kueri tertentu, elemen rows akan dihilangkan dari respons.

Respons untuk kueri dengan dimensi day tidak akan berisi baris untuk hari-hari terbaru.

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

Contoh

Catatan: Contoh kode berikut mungkin tidak merepresentasikan semua bahasa pemrograman yang didukung. Lihat dokumentasi library klien untuk mengetahui daftar bahasa yang didukung.

JavaScript

Contoh ini memanggil YouTube Analytics API untuk mengambil penayangan harian dan metrik lainnya untuk channel pengguna yang memberikan otorisasi selama tahun kalender 2017. Contoh ini menggunakan Library klien JavaScript Google API.

Sebelum menjalankan contoh ini secara lokal untuk pertama kalinya, Anda perlu menyiapkan kredensial otorisasi untuk project Anda:
  1. Buat atau pilih project di Konsol API Google.
  2. Aktifkan YouTube Analytics API untuk project Anda.
  3. Di bagian atas halaman Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, lalu klik tombol Simpan.
  4. Di halaman Credentials, klik tombol Create credentials, lalu pilih Oauth client ID.
  5. Pilih jenis aplikasi Aplikasi web.
  6. Di kolom Asal JavaScript yang sah, masukkan URL tempat Anda akan menayangkan contoh kode. Misalnya, Anda dapat menggunakan sesuatu seperti http://localhost:8000 atau http://yourserver.example.com. Anda dapat mengosongkan kolom Authorized redirect URIs.
  7. Klik tombol Buat untuk menyelesaikan pembuatan kredensial Anda.
  8. Sebelum menutup kotak dialog, salin ID klien, yang akan Anda perlukan untuk dimasukkan ke dalam contoh kode.

Kemudian, simpan sampel ke file lokal. Dalam contoh, temukan baris berikut dan ganti YOUR_CLIENT_ID dengan client ID yang Anda peroleh saat menyiapkan kredensial otorisasi.

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

Sekarang, Anda siap untuk benar-benar menguji sampel:

  1. Buka file lokal dari browser web, lalu buka konsol pen-debug di browser. Anda akan melihat halaman yang menampilkan dua tombol.
  2. Klik tombol authorize and load untuk meluncurkan alur otorisasi pengguna. Jika Anda mengizinkan aplikasi untuk mengambil data channel Anda, Anda akan melihat baris berikut dicetak ke konsol di browser:
    Sign-in successful
    GAPI client loaded for API
  3. Jika Anda melihat pesan error, bukan baris di atas, pastikan Anda memuat skrip dari URI pengalihan resmi yang Anda siapkan untuk project dan Anda memasukkan ID klien ke dalam kode seperti yang dijelaskan di atas.
  4. Klik tombol execute untuk memanggil API. Anda akan melihat objek response dicetak ke konsol di browser. Dalam objek tersebut, properti result dipetakan ke objek yang berisi data 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

Contoh ini memanggil YouTube Analytics API untuk mengambil penayangan harian dan metrik lainnya untuk channel pengguna yang memberikan otorisasi selama tahun kalender 2017. Contoh ini menggunakan library klien Python Google API.

Sebelum menjalankan contoh ini secara lokal untuk pertama kalinya, Anda perlu menyiapkan kredensial otorisasi untuk project Anda:
  1. Buat atau pilih project di Konsol API Google.
  2. Aktifkan YouTube Analytics API untuk project Anda.
  3. Di bagian atas halaman Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, lalu klik tombol Simpan.
  4. Di halaman Credentials, klik tombol Create credentials, lalu pilih Oauth client ID.
  5. Pilih jenis aplikasi Lainnya, masukkan nama "YouTube Analytics API Quickstart", lalu klik tombol Buat.
  6. Klik Oke untuk menutup dialog yang muncul.
  7. Klik tombol (Download JSON) di sebelah kanan client ID.
  8. Pindahkan file yang didownload ke direktori kerja Anda.

Anda juga perlu menginstal Library Klien Google API untuk Python dan beberapa library tambahan:

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

Sekarang, Anda siap untuk benar-benar menguji sampel:

  1. Salin contoh kode di bawah ke direktori kerja Anda.
  2. Dalam contoh, perbarui nilai variabel CLIENT_SECRETS_FILE agar sesuai dengan lokasi file yang Anda download setelah menyiapkan kredensial otorisasi.
  3. Jalankan kode contoh di jendela terminal:
    python yt_analytics_v2.py
  4. Ikuti alur otorisasi. Alur autentikasi dapat dimuat secara otomatis di browser Anda, atau Anda mungkin perlu menyalin URL autentikasi ke jendela browser. Di akhir alur otorisasi, jika perlu, tempelkan kode otorisasi yang ditampilkan di browser ke jendela terminal Anda, lalu klik [return].
  5. Kueri API dijalankan dan respons JSON ditampilkan ke jendela terminal.
# -*- 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'
  )

Cobalah!

Gunakan APIs Explorer untuk memanggil API ini dan melihat permintaan serta respons API.