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 yang berbeda. Setiap permintaan menggunakan parameter kueri untuk menentukan ID channel 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 ukuran individu dari aktivitas pengguna, seperti jumlah tontonan video atau rating (suka dan tidak suka).
  • Dimensi adalah kriteria umum yang digunakan untuk menggabungkan data, seperti tanggal aktivitas pengguna terjadi 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 grup 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 diizinkan. 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 Lihat 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 Lihat laporan moneter YouTube Analytics untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna dan estimasi pendapatan serta metrik performa iklan.
https://www.googleapis.com/auth/youtube Mengelola akun YouTube Anda. Di YouTube Analytics API, pemilik channel menggunakan cakupan ini untuk mengelola grup dan item grup YouTube Analytics.
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 dan item grup YouTube Analytics.

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 yang semua metriknya 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, tanggal tersebut akan menjadi tanggal terakhir saat data disertakan dalam respons. (Ini berlaku 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 data YouTube Analytics-nya Anda ambil.

  • Untuk meminta data saluran YouTube, setel nilai parameter ids ke channel==MINE atau channel==CHANNEL_ID, dengan CHANNEL_ID mengidentifikasi saluran YouTube pengguna yang saat ini diautentikasi.
  • Untuk meminta data bagi pemilik konten YouTube, setel 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 laporan channel atau laporan pemilik konten untuk melihat 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 metrik estimasi 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 yang diminta, parameter akan diabaikan.

Nilai parameternya adalah kode mata uang tiga huruf ISO 4217 dari daftar mata uang di bawah ini. 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 laporan channel atau laporan pemilik konten untuk melihat 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 keduanya dengan titik koma (;), dan tabel hasil yang ditampilkan akan memenuhi kedua filter tersebut. Misalnya, nilai parameter filters dari video==dMH0bHeiRNg;country==IT membatasi kumpulan hasil agar 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 terpisah dari video, playlist, atau ID channel yang respons API-nya harus difilter. Misalnya, nilai parameter filters dari video==pd1FJh59zxQ,Zhawgd0REhA;country==IT membatasi kumpulan hasil agar 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 ditentukan 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 menjangkau konten video channel. Selain itu, anggaplah permintaan parameter filters permintaan Anda mengidentifikasi daftar 10 video yang harus ditampilkan datanya.
  • Jika Anda menambahkan video ke nilai parameter dimensions, respons API akan memberikan statistik sumber traffic yang terpisah untuk masing-masing dari 10 video.
  • Jika Anda tidak menambahkan video ke nilai parameter dimensions, respons API akan menggabungkan statistik sumber traffic untuk ke-10 video tersebut.
includeHistoricalChannelData boolean
Catatan: Parameter ini hanya berlaku untuk laporan pemilik konten.

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

Perlu 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 parameternya adalah false, respons API akan berisi data berdasarkan tanggal penautan untuk setiap saluran. 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 tata urutan untuk data YouTube Analytics. Secara default, tata urutan menaik. Awalan - menyebabkan tata urutan menurun.
startIndex integer
Indeks berbasis 1 dari entity 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 dalam API versi 2 yang hanya mendukung respons JSON.Format data untuk respons API.
  • Nilai 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 baris baru.

  • Menampilkan respons dalam format yang dapat dibaca manusia jika true.
  • Nilai default: true.
  • Jika ini adalah false, ini dapat mengurangi ukuran payload respons, yang dapat menyebabkan peningkatan performa di beberapa lingkungan.
quotaUser Parameter ini didukung dalam versi 1 API, yang sekarang tidak digunakan lagi. Parameter ini tidak didukung dalam versi 2 API.
userIp Parameter ini didukung dalam versi 1 API, yang sekarang tidak digunakan lagi. Parameter ini tidak didukung dalam versi 2 API.

Isi permintaan

Jangan mengirim isi permintaan saat memanggil metode ini.

Tanggapan

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 akan menjadi 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 dipisahkan 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 di kolom (STRING, INTEGER, FLOAT, dll.).
rows[] list
Daftar berisi semua baris tabel hasil. Setiap item dalam daftar adalah array yang berisi data yang dipisahkan koma yang sesuai dengan satu baris data. Urutan kolom data yang dipisahkan 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 beberapa hari terakhir.

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 mewakili semua bahasa pemrograman yang didukung. Lihat dokumentasi library klien untuk mengetahui daftar bahasa yang didukung.

JavaScript

Contoh ini memanggil YouTube Analytics API untuk mengambil jumlah tontonan harian dan metrik lainnya bagi channel yang memberi otorisasi kepada pengguna untuk 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 Kredensial, pilih tab Layar persetujuan OAuth. Pilih alamat Email, masukkan nama Produk jika belum ditetapkan, lalu klik tombol Simpan.
  4. Di halaman Kredensial, klik tombol Create credentials, lalu pilih Oauth client ID.
  5. Pilih jenis aplikasi Web.
  6. Di kolom asal JavaScript yang Diizinkan, 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 URI Pengalihan yang Diotorisasi.
  7. Klik tombol Buat untuk menyelesaikan pembuatan kredensial.
  8. Sebelum menutup kotak dialog, salin client ID yang harus dimasukkan ke dalam contoh kode.

Kemudian, simpan contoh ke file lokal. Di 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 debug di browser. Anda akan melihat halaman yang menampilkan dua tombol.
  2. Klik tombol otorisasi dan muat untuk meluncurkan alur otorisasi pengguna. Jika Anda mengizinkan aplikasi untuk mengambil data saluran, 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 yang diotorisasi yang Anda siapkan untuk project dan memasukkan client ID ke dalam kode seperti yang dijelaskan di atas.
  4. Klik tombol eksekusi untuk memanggil API. Anda akan melihat objek response yang dicetak ke konsol di browser. Di 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 jumlah tontonan harian dan metrik lainnya bagi channel yang memberi otorisasi kepada pengguna untuk 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 Kredensial, pilih tab Layar persetujuan OAuth. Pilih alamat Email, masukkan nama Produk jika belum ditetapkan, lalu klik tombol Simpan.
  4. Di halaman Kredensial, klik tombol Create credentials, lalu pilih Oauth client ID.
  5. Pilih jenis aplikasi Lainnya, masukkan nama "Panduan Memulai YouTube Analytics API", lalu klik tombol Buat.
  6. Klik OK untuk menutup dialog yang dihasilkan.
  7. Klik tombol (Download JSON) di sebelah kanan client ID.
  8. Pindahkan file yang didownload ke direktori kerja.

Anda juga harus 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 ini ke direktori kerja.
  2. Di contoh, perbarui nilai variabel CLIENT_SECRETS_FILE agar cocok 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 mungkin dimuat secara otomatis di browser Anda, atau Anda mungkin perlu menyalin URL autentikasi ke jendela browser. Di akhir alur otorisasi, jika perlu, tempel kode otorisasi yang ditampilkan di browser ke jendela terminal Anda, lalu klik [return].
  5. Kueri API dijalankan dan respons JSON merupakan output 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 dan respons API.