Reports: Query

Penting: Permintaan API untuk metode ini sekarang 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 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 pengukuran individu aktivitas pengguna, seperti jumlah tontonan 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 diberi 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 Analytics YouTube untuk konten YouTube Anda. Cakupan ini memberikan akses ke metrik aktivitas pengguna serta estimasi pendapatan dan metrik performa iklan.
https://www.googleapis.com/auth/youtube Kelola 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 serta 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 yang Diperlukan
endDate string
Tanggal akhir pengambilan 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 mencantumkan tanggal akhir 5 Juli 2017, dan nilai untuk semua metrik yang diminta hanya tersedia hingga 3 Juli 2017, tanggal tersebut akan menjadi tanggal terakhir data disertakan dalam respons. (Hal ini benar meskipun data untuk beberapa metrik yang diminta tersedia untuk 4 Juli 2017.)
Catatan: Di versi 1 API, parameter ini diberi nama end-date.
ids string
Mengidentifikasi channel YouTube atau pemilik konten yang data YouTube Analytics-nya Anda ambil.

  • Untuk meminta data untuk channel YouTube, setel parameter value ids ke channel==MINE atau channel==CHANNEL_ID, dengan CHANNEL_ID mengidentifikasi channel YouTube pengguna yang saat ini diautentikasi.
  • Untuk meminta data bagi pemilik konten YouTube, tetapkan nilai parameter ids ke contentOwner==OWNER_NAME, dengan OWNER_NAME sebagai 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 Metrik berisi definisi untuk semua metrik.)
startDate string
Tanggal mulai pengambilan data YouTube Analytics. Nilai harus dalam format YYYY-MM-DD.
Catatan: Di versi 1 API, 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 merupakan perkiraan yang dihitung menggunakan nilai tukar yang berubah setiap hari. Jika tidak ada satu pun dari metrik tersebut yang diminta, parameter akan diabaikan.

Nilai parameternya 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. Baca dokumentasi 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 saluran dan laporan pemilik konten mengidentifikasi dimensi yang dapat digunakan untuk memfilter setiap laporan, dan dokumen Dimensi akan 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 dari video==dMH0bHeiRNg;country==IT membatasi kumpulan 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 terpisah berisi ID video, playlist, atau channel yang respons API-nya harus difilter. Misalnya, nilai parameter filters dari video==pd1FJh59zxQ,Zhawgd0REhA;country==IT membatasi kumpulan 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 menjangkau konten video di channel tersebut. Selain itu, anggaplah permintaan parameter filters dari permintaan 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 ke-10 video tersebut.
  • 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 data penayangan dari jangka waktu sebelum channel ditautkan ke pemilik konten. Parameter value defaultnya adalah false yang berarti respons API hanya menyertakan waktu tonton dan data 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-beda. Jika permintaan API mengambil data untuk beberapa saluran dan nilai parameternya adalah false, respons API akan berisi data berdasarkan tanggal penautan untuk setiap saluran masing-masing. Jika nilai parameter adalah true, respons API akan berisi data yang cocok dengan tanggal yang ditentukan dalam permintaan API.
Catatan: Di versi 1 API, parameter ini diberi nama include-historical-channel-data.
maxResults integer
Jumlah baris maksimum yang akan disertakan dalam respons.
Catatan: Di versi 1 API, parameter ini diberi nama max-results.
sort string
Daftar dimensi atau metrik yang dipisahkan koma yang menentukan tata urutan untuk data YouTube Analytics. Secara {i>default<i}, tata urutannya adalah 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: Di versi 1 API, 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 nilainya false, ukuran payload respons dapat mengurangi ukuran payload respons, yang dapat menghasilkan performa yang lebih baik di beberapa lingkungan.
quotaUser Parameter ini didukung dalam API versi 1, yang kini sudah tidak digunakan lagi. Parameter ini tidak didukung dalam API versi 2.
userIp Parameter ini didukung dalam API versi 1, yang kini sudah tidak digunakan lagi. Parameter ini tidak didukung dalam API versi 2.

Isi permintaan

Jangan kirim isi permintaan saat memanggil metode ini.

Respons

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

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 lain.
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, diikuti dengan metrik yang ditentukan dalam permintaan API. Urutan dimensi dan metrik sesuai 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 sesuai dengan urutan kolom yang tercantum dalam kolom columnHeaders.

Jika tidak ada data yang tersedia untuk kueri tertentu, elemen rows akan dihapus 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. Baca dokumentasi library klien untuk mengetahui daftar bahasa yang didukung.

JavaScript

Contoh ini memanggil YouTube Analytics API untuk mengambil jumlah penayangan harian dan metrik lainnya untuk channel pengguna yang memberi otorisasi 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 Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, dan klik tombol Simpan.
  4. Di halaman Credentials, klik tombol Create credentials dan pilih Oauth client ID.
  5. Pilih jenis aplikasi Aplikasi web.
  6. Di kolom Asal JavaScript yang Diotorisasi, masukkan URL tempat Anda akan menyajikan contoh kode. Misalnya, Anda dapat menggunakan sesuatu seperti http://localhost:8000 atau http://yourserver.example.com. Anda dapat mengosongkan kolom URI Pengalihan yang sah.
  7. Klik tombol Create untuk menyelesaikan pembuatan kredensial Anda.
  8. Sebelum menutup kotak dialog, salin client ID yang harus Anda masukkan ke contoh kode.

Kemudian, simpan sampel ke file lokal. Pada contoh, cari baris berikut dan ganti YOUR_CLIENT_ID dengan client ID yang Anda dapatkan 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, dan 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 dan bukan baris di atas, pastikan bahwa Anda memuat skrip dari URI pengalihan yang diotorisasi yang Anda siapkan untuk project Anda dan bahwa Anda memasukkan client ID ke dalam kode seperti yang dijelaskan di atas.
  4. Klik tombol execute 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>

yt_analytics_v2.html

Python

Contoh ini memanggil YouTube Analytics API untuk mengambil jumlah penayangan harian dan metrik lainnya untuk channel pengguna yang memberi otorisasi 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 Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, dan klik tombol Simpan.
  4. Di halaman Credentials, klik tombol Create credentials dan 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 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 mungkin dimuat secara otomatis di browser, 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 dan klik [return].
  5. Kueri API dijalankan dan respons JSON dihasilkan 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'
  )

yt_analytics_v2.py

Cobalah!

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