YouTube Reporting API - Get Bulk Data Reports
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
YouTube otomatis membuat serangkaian laporan pendapatan iklan yang dikelola sistem untuk pemilik konten yang memiliki akses ke laporan terkait di Creator Studio. Laporan ini dirancang untuk memberikan akses terprogram ke data yang juga tersedia dalam laporan yang dapat didownload secara manual dan dapat diakses di menu Laporan di YouTube Creator Studio.
Catatan: API memberikan akses ke serangkaian laporan yang berbeda dengan Creator Studio, meskipun laporan tersebut berisi data yang serupa. Laporan API mungkin memiliki kolom yang berbeda dan juga menggunakan nama kolom yang berbeda dengan laporan Creator Studio.
Karena YouTube otomatis membuat laporan yang dikelola sistem, proses pengambilan laporan ini berbeda dengan laporan data massal YouTube Analytics yang tersedia melalui API.
Mengambil laporan
Langkah-langkah berikut menjelaskan cara mengambil laporan yang dikelola sistem melalui API.
Langkah 1: Ambil kredensial otorisasi
Semua permintaan YouTube Reporting API harus mendapatkan otorisasi. Panduan otorisasi menjelaskan cara menggunakan protokol OAuth 2.0 untuk mengambil token otorisasi.
Permintaan YouTube Reporting 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. |
Langkah 2: Ambil ID tugas untuk laporan yang diinginkan
Panggil metode jobs.list untuk mengambil daftar tugas yang dikelola sistem. Tetapkan parameter includeSystemManaged ke true.
Properti reportTypeId di setiap resource Job yang ditampilkan mengidentifikasi jenis laporan yang dikelola sistem yang terkait dengan tugas tersebut. Aplikasi Anda memerlukan nilai properti id dari resource yang sama pada langkah berikutnya.
Dokumen Laporan mencantumkan laporan yang tersedia, ID jenis laporan, dan kolom yang ada di dalamnya. Anda juga dapat menggunakan metode reportTypes.list untuk mengambil daftar jenis laporan yang didukung.
Langkah 3: Ambil URL download laporan
Panggil metode jobs.reports.list untuk mengambil daftar laporan yang dibuat untuk tugas. Dalam permintaan, tetapkan parameter jobId ke ID tugas laporan yang ingin Anda ambil.
Anda dapat memfilter daftar laporan menggunakan satu atau semua parameter berikut:
-
Gunakan parameter createdAfter untuk menunjukkan bahwa API hanya boleh menampilkan laporan yang dibuat setelah waktu tertentu. Parameter ini dapat digunakan untuk memastikan bahwa API hanya menampilkan laporan yang belum Anda proses.
-
Gunakan parameter startTimeBefore untuk menunjukkan bahwa respons API hanya boleh berisi laporan jika data paling awal dalam laporan adalah sebelum tanggal yang ditentukan. Sementara parameter createdAfter berkaitan dengan waktu pembuatan laporan, tanggal ini berkaitan dengan data dalam laporan.
-
Gunakan parameter startTimeAtOrAfter untuk menunjukkan bahwa respons API hanya boleh berisi laporan jika data paling awal dalam laporan adalah pada atau setelah tanggal yang ditentukan. Seperti parameter startTimeBefore, nilai parameter ini sesuai dengan data dalam laporan, bukan waktu laporan dibuat.
Respons API berisi daftar resource Report untuk tugas tersebut. Setiap resource mengacu pada laporan yang berisi data untuk periode unik.
- Properti
startTime dan endTime resource mengidentifikasi jangka waktu yang dicakup oleh data laporan.
- Properti
downloadUrl resource mengidentifikasi URL tempat laporan dapat diambil.
- Properti
createTime resource menentukan tanggal dan waktu saat laporan dibuat. Aplikasi Anda harus menyimpan nilai ini dan menggunakannya untuk menentukan apakah laporan yang sebelumnya didownload telah berubah.
Langkah 4: Download laporan
Kirim permintaan HTTP GET ke downloadUrl yang diperoleh pada langkah 4 untuk mengambil laporan.
Memproses laporan
Praktik terbaik
Aplikasi yang menggunakan YouTube Reporting API harus selalu mengikuti praktik berikut:
-
Gunakan baris header laporan untuk menentukan urutan kolom laporan. Misalnya, jangan berasumsi bahwa penayangan akan menjadi metrik pertama yang ditampilkan dalam laporan hanya karena metrik tersebut adalah metrik pertama yang tercantum dalam deskripsi laporan. Sebagai gantinya, gunakan baris header laporan untuk menentukan kolom mana yang berisi data tersebut.
-
Simpan catatan laporan yang telah Anda download untuk menghindari pemrosesan laporan yang sama berulang kali. Daftar berikut menyarankan beberapa cara untuk melakukannya.
-
Saat memanggil metode reports.list, gunakan parameter createdAfter untuk hanya mengambil laporan yang dibuat setelah tanggal tertentu. (Abaikan parameter createdAfter saat pertama kali Anda mengambil laporan.)
Setiap kali Anda mengambil dan berhasil memproses laporan, simpan stempel waktu yang sesuai dengan tanggal dan waktu saat laporan terbaru tersebut dibuat. Kemudian, perbarui nilai parameter createdAfter pada setiap panggilan berikutnya ke metode reports.list untuk memastikan bahwa Anda hanya mengambil laporan baru, termasuk laporan baru dengan data yang diisi ulang, setiap kali Anda memanggil API.
Sebagai pengamanan, sebelum mengambil laporan, periksa juga untuk memastikan bahwa ID laporan belum tercantum dalam database Anda.
-
Simpan ID untuk setiap laporan yang telah Anda download dan proses. Anda juga dapat menyimpan informasi tambahan seperti tanggal dan waktu saat setiap laporan dibuat atau startTime dan endTime laporan, yang bersama-sama mengidentifikasi periode yang datanya ada dalam laporan. Untuk laporan yang mengambil data massal untuk YouTube Analytics, setiap tugas kemungkinan akan memiliki banyak laporan karena setiap laporan berisi data untuk jangka waktu 24 jam. Tugas yang dikelola sistem yang mencakup jangka waktu yang lebih lama akan memiliki lebih sedikit laporan.
Gunakan ID laporan untuk mengidentifikasi laporan yang masih perlu Anda download dan impor. Namun, jika dua laporan baru memiliki nilai properti startTime dan endTime yang sama, impor hanya laporan dengan nilai createTime yang lebih baru.
Karakteristik laporan
Laporan API adalah file .csv (nilai yang dipisahkan koma) berversi yang memiliki karakteristik berikut:
-
Setiap laporan berisi data untuk periode unik yang berlangsung dari pukul 00.00 waktu Pasifik pada tanggal mulai laporan hingga pukul 23.59 waktu Pasifik pada tanggal akhir laporan.
-
Data laporan tidak diurutkan.
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2025-08-21 UTC.
[null,null,["Terakhir diperbarui pada 2025-08-21 UTC."],[[["\u003cp\u003eYouTube's Reporting API provides access to system-managed ad revenue reports, which differ from Creator Studio reports in terms of fields and naming, yet contain similar data.\u003c/p\u003e\n"],["\u003cp\u003eRetrieving these reports involves four steps: getting authorization credentials, retrieving the job ID, getting the report's download URL, and downloading the report.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires specific authorization scopes, either \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics.readonly\u003c/code\u003e for general user activity metrics or \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics-monetary.readonly\u003c/code\u003e for monetary and ad performance metrics.\u003c/p\u003e\n"],["\u003cp\u003eBest practices for using the API include using the header row to identify column ordering and keeping a record of downloaded reports to avoid reprocessing the same data, while also checking for updated reports.\u003c/p\u003e\n"],["\u003cp\u003eEach report is a \u003ccode\u003e.csv\u003c/code\u003e file containing data for a specific period, from 12:00 a.m. to 11:59 p.m. Pacific Time, and the data within the reports is not sorted.\u003c/p\u003e\n"]]],["YouTube provides system-managed ad revenue reports accessible via the Reporting API. To retrieve these reports, first, obtain authorization credentials using OAuth 2.0. Next, retrieve the job ID for the desired report type by calling `jobs.list` with `includeSystemManaged` set to `true`. Then, call `jobs.reports.list`, providing the job ID, to get the report's download URL, which may be filtered by creation or start times. Finally, use an HTTP GET request to download the report. Remember to store downloaded report details to avoid reprocessing.\n"],null,["# YouTube Reporting API - Get Bulk Data Reports\n\nYouTube automatically generates a set of system-managed ad revenue reports for content owners that have access to the corresponding reports in [Creator Studio](http://studio.youtube.com/). These reports are designed to provide programmatic access to data that is also available in manually downloadable reports accessible in the [Reports menu](https://support.google.com/youtube/answer/7648605) of the YouTube Creator Studio.\n\n**Note:** The API provides access to a different set of reports than Creator Studio, though the reports contain similar data. API reports might have different fields and also use different field names than Creator Studio reports.\n\nSince YouTube automatically generates system-managed reports, the process for retrieving these reports is different than for the YouTube Analytics bulk data reports available via the API.\n\nRetrieving reports\n------------------\n\nThe following steps explain how to retrieve system-managed reports via the API.\n\n### Step 1: Retrieve authorization credentials\n\nAll YouTube Reporting API requests must be authorized. The [Authorization guide](/youtube/reporting/guides/authorization) explains how to use the OAuth 2.0 protocol to retrieve authorization tokens.\n\nYouTube Reporting API requests use the following authorization scopes:\n\n| Scopes ||\n|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| https://www.googleapis.com/auth/yt-analytics.readonly | View YouTube Analytics reports for your YouTube content. This scope provides access to user activity metrics, like view counts and rating counts. |\n| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics. |\n\n### Step 2: Retrieve the job ID for the desired report\n\nCall the `jobs.list` method to retrieve a list of system-managed jobs. Set the [includeSystemManaged](/youtube/reporting/v1/reference/rest/v1/jobs/list#includeSystemManaged) parameter to `true`.\n\nThe [reportTypeId](/youtube/reporting/v1/reference/rest/v1/jobs#reportTypeId) property in each returned `Job` resource identifies the type of system-managed report associated with that job. Your application needs the [id](/youtube/reporting/v1/reference/rest/v1/jobs#id) property value from the same resource in the following step.\n\nThe [Reports](/youtube/reporting/v1/reports/system_managed/reports) document lists available reports, their report type IDs, and the fields they contain. You can also use the [reportTypes.list](/youtube/reporting/v1/reference/rest/v1/reportTypes/list) method to retrieve a list of supported report types.\n\n### Step 3: Retrieve the report's download URL\n\nCall the `jobs.reports.list` method to retrieve a list of reports created for the job. In the request, set the [jobId](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#jobId) parameter to the job ID of the report that you want to retrieve.\n\nYou can filter the list of reports using any or all of the following parameters:\n\n- Use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to indicate that the API should only return reports created after a specified time. This parameter can be used to ensure that the API only returns reports that you have not already processed.\n\n- Use the [startTimeBefore](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeBefore) parameter to indicate that the API response should only contain reports if the earliest data in the report is before the specified date. Whereas the `createdAfter` parameter pertains to the time the report was created, this date pertains to the data in the report.\n\n- Use the [startTimeAtOrAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeAtOrAfter) parameter to indicate that the API response should only contain reports if the earliest data in the report is on or after the specified date. Like the `startTimeBefore` parameter, this parameter value corresponds to the data in the report and not the time the report was created.\n\nThe API response contains a list of `Report` resources for that job. Each resource refers to a report that contains data for a unique period.\n\n- The resource's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) properties identify the time period that the report's data covers.\n- The resource's [downloadUrl](/youtube/reporting/v1/reference/rest/v1/jobs.reports#downloadUrl) property identifies the URL from which the report can be fetched.\n- The resource's [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) property specifies the date and time when the report was generated. Your application should store this value and use it to determine whether previously downloaded reports have changed.\n\n### Step 4: Download the report\n\nSend an HTTP GET request to the `downloadUrl` obtained in step 4 to retrieve the report.\n\nProcessing reports\n------------------\n\n### Best practices\n\nApplications that use the YouTube Reporting API should *always* follow these practices:\n\n- Use a report's header row to determine the ordering of the report's columns. For example, do not assume that [views](/youtube/reporting/v1/reports/metrics#views) will be the first metric returned in a report just because it is the first metric listed in a report description. Instead, use the report's header row to determine which column contains that data.\n\n- Keep a record of the reports you have downloaded to avoid repeatedly processing the same report. The following list suggests a couple of ways to do that.\n\n - When calling the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method, use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to only retrieve reports created after a certain date. (Omit the `createdAfter` parameter the first time you retrieve reports.)\n\n Each time you retrieve and successfully process reports, store the timestamp corresponding to the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when the newest of those reports was created. Then, update the `createdAfter` parameter value on each successive call to the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method to ensure that you are only retrieving new reports, including new reports with backfilled data, each time you call the API.\n\n As a safeguard, before retrieving a report, also check to ensure that the report's [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) is not already listed in your database.\n - Store the [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) for each report that you have downloaded and processed. You can also store additional information like the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when each report was generated or the report's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime), which together identify the period for which the report contains data. For reports that retrieve bulk data for YouTube Analytics, each job will likely have many reports since each report contains data for a 24-hour period. System-managed jobs that cover longer time periods will have fewer reports.\n\n Use the report ID to identify reports that you still need to download and import. However, if two new reports have the same [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) property values, only import the report with the newer [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) value.\n\n### Report characteristics\n\nAPI reports are versioned `.csv` (comma-separated values) files that have the following characteristics:\n\n- Each report contains data for a unique period lasting from 12:00 a.m. Pacific time on the report's start date through 11:59 p.m. Pacific time on the report's end date.\n\n- Report data is not sorted."]]
