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.
|
|
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.
|
|
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.
|
|
callback |
Fungsi callback.
|
|
prettyPrint |
Menampilkan respons dengan indentasi dan jeda baris.
|
|
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:
{ "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. |
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:
- Buat atau pilih project di Konsol API Google.
- Aktifkan YouTube Analytics API untuk project Anda.
- Di bagian atas halaman Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, lalu klik tombol Simpan.
- Di halaman Credentials, klik tombol Create credentials, lalu pilih Oauth client ID.
- Pilih jenis aplikasi Aplikasi web.
- Di kolom Asal JavaScript yang sah, masukkan URL tempat Anda akan menayangkan contoh kode. Misalnya, Anda dapat menggunakan sesuatu seperti
http://localhost:8000
atauhttp://yourserver.example.com
. Anda dapat mengosongkan kolom Authorized redirect URIs. - Klik tombol Buat untuk menyelesaikan pembuatan kredensial Anda.
- 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:
- Buka file lokal dari browser web, lalu buka konsol pen-debug di browser. Anda akan melihat halaman yang menampilkan dua tombol.
- 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
- 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.
- Klik tombol execute untuk memanggil API. Anda akan melihat objek
response
dicetak ke konsol di browser. Dalam objek tersebut, propertiresult
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:
- Buat atau pilih project di Konsol API Google.
- Aktifkan YouTube Analytics API untuk project Anda.
- Di bagian atas halaman Credentials, pilih tab OAuth consent screen. Pilih Alamat email, masukkan Nama produk jika belum ditetapkan, lalu klik tombol Simpan.
- Di halaman Credentials, klik tombol Create credentials, lalu pilih Oauth client ID.
- Pilih jenis aplikasi Lainnya, masukkan nama "YouTube Analytics API Quickstart", lalu klik tombol Buat.
- Klik Oke untuk menutup dialog yang muncul.
- Klik tombol (Download JSON) di sebelah kanan client ID.
- 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:
- Salin contoh kode di bawah ke direktori kerja Anda.
- Dalam contoh, perbarui nilai variabel
CLIENT_SECRETS_FILE
agar sesuai dengan lokasi file yang Anda download setelah menyiapkan kredensial otorisasi. - Jalankan kode contoh di jendela terminal:
python yt_analytics_v2.py
- 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].
- 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.