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.
|
|
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.
|
|
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.
|
|
callback |
Fungsi callback.
|
|
prettyPrint |
Menampilkan respons dengan indentasi dan baris baru.
|
|
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:
{ "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. |
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:
- Buat atau pilih project di Konsol API Google.
- Aktifkan YouTube Analytics API untuk project Anda.
- Di bagian atas halaman Kredensial, pilih tab Layar persetujuan OAuth. Pilih alamat Email, masukkan nama Produk jika belum ditetapkan, lalu klik tombol Simpan.
- Di halaman Kredensial, klik tombol Create credentials, lalu pilih Oauth client ID.
- Pilih jenis aplikasi Web.
- Di kolom asal JavaScript yang Diizinkan, 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 URI Pengalihan yang Diotorisasi. - Klik tombol Buat untuk menyelesaikan pembuatan kredensial.
- 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:
- Buka file lokal dari browser web, lalu buka konsol debug di browser. Anda akan melihat halaman yang menampilkan dua tombol.
- 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
- 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.
- Klik tombol eksekusi untuk memanggil API. Anda akan melihat objek
response
yang dicetak ke konsol di browser. Di 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 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:
- Buat atau pilih project di Konsol API Google.
- Aktifkan YouTube Analytics API untuk project Anda.
- Di bagian atas halaman Kredensial, pilih tab Layar persetujuan OAuth. Pilih alamat Email, masukkan nama Produk jika belum ditetapkan, lalu klik tombol Simpan.
- Di halaman Kredensial, klik tombol Create credentials, lalu pilih Oauth client ID.
- Pilih jenis aplikasi Lainnya, masukkan nama "Panduan Memulai YouTube Analytics API", lalu klik tombol Buat.
- Klik OK untuk menutup dialog yang dihasilkan.
- Klik tombol (Download JSON) di sebelah kanan client ID.
- 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:
- Salin contoh kode di bawah ini ke direktori kerja.
- Di contoh, perbarui nilai variabel
CLIENT_SECRETS_FILE
agar cocok 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 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].
- 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.