YouTube Reporting API - Get Bulk Data Reports
Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
YouTube, İçerik Stüdyosu'nda ilgili raporlara erişimi olan içerik sahipleri için otomatik olarak bir dizi sistem tarafından yönetilen reklam geliri raporu oluşturur. Bu raporlar, YouTube İçerik Stüdyosu'nun Raporlar menüsünde bulunan ve manuel olarak indirilebilen raporlarda da yer alan verilere programatik erişim sağlamak için tasarlanmıştır.
Not: API, raporlar benzer veriler içerse de İçerik Stüdyosu'ndan farklı bir rapor grubuna erişim sağlar. API raporları farklı alanlara sahip olabilir ve Creator Studio raporlarından farklı alan adları kullanabilir.
YouTube, sistem tarafından yönetilen raporları otomatik olarak oluşturduğundan bu raporları alma süreci, API üzerinden kullanılabilen YouTube Analytics toplu veri raporlarını alma sürecinden farklıdır.
Raporları alma
Aşağıdaki adımlarda, sistem tarafından yönetilen raporların API aracılığıyla nasıl alınacağı açıklanmaktadır.
1. adım: Yetkilendirme kimlik bilgilerini alın
Tüm YouTube Reporting API istekleri yetkilendirilmelidir. Yetkilendirme kılavuzunda, yetkilendirme jetonlarını almak için OAuth 2.0 protokolünün nasıl kullanılacağı açıklanmaktadır.
YouTube Reporting API istekleri aşağıdaki yetkilendirme kapsamlarını kullanır:
| Kapsamlar |
| https://www.googleapis.com/auth/yt-analytics.readonly |
YouTube içeriğiniz için YouTube Analytics raporlarını görüntüleyin. Bu kapsam, görüntüleme sayısı ve derecelendirme sayısı gibi kullanıcı etkinliği metriklerine erişim sağlar. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
YouTube içeriğiniz için YouTube Analytics finansal raporlarını görüntüleyin. Bu kapsam, kullanıcı etkinliği metriklerine, tahmini gelire ve reklam performansı metriklerine erişim sağlar. |
2. adım: İstenen raporun iş kimliğini alın
Sistem tarafından yönetilen işlerin listesini almak için jobs.list yöntemini çağırın. includeSystemManaged parametresini true olarak ayarlayın.
Döndürülen her Job kaynağındaki reportTypeId özelliği, söz konusu işle ilişkilendirilmiş sistem tarafından yönetilen raporun türünü tanımlar. Uygulamanızın, bir sonraki adımda aynı kaynaktaki id özellik değerine ihtiyacı vardır.
Raporlar dokümanında, kullanılabilir raporlar, rapor türü kimlikleri ve içerdiği alanlar listelenir. Desteklenen rapor türlerinin listesini almak için reportTypes.list yöntemini de kullanabilirsiniz.
3. adım: Raporun indirme URL'sini alın
İş için oluşturulan raporların listesini almak üzere jobs.reports.list yöntemini çağırın. İstek içinde jobId parametresini, almak istediğiniz raporun iş kimliğine ayarlayın.
Aşağıdaki parametrelerden herhangi birini veya tümünü kullanarak rapor listesini filtreleyebilirsiniz:
-
API'nin yalnızca belirtilen bir zamandan sonra oluşturulan raporları döndürmesi gerektiğini belirtmek için createdAfter parametresini kullanın. Bu parametre, API'nin yalnızca henüz işlemediğiniz raporları döndürmesini sağlamak için kullanılabilir.
-
API yanıtının yalnızca rapordaki en eski veriler belirtilen tarihten önceyse raporları içermesi gerektiğini belirtmek için startTimeBefore parametresini kullanın. createdAfter parametresi raporun oluşturulduğu zamanla ilgiliyken bu tarih, rapordaki verilerle ilgilidir.
-
API yanıtının yalnızca rapordaki en eski veriler belirtilen tarihte veya sonrasında ise raporları içermesi gerektiğini belirtmek için startTimeAtOrAfter parametresini kullanın. startTimeBefore parametresinde olduğu gibi, bu parametre değeri de raporun oluşturulma zamanına değil, rapordaki verilere karşılık gelir.
API yanıtı, söz konusu iş için Report kaynaklarının listesini içerir. Her kaynak, benzersiz bir döneme ait verileri içeren bir raporu ifade eder.
- Kaynağın
startTime ve endTime özellikleri, raporun verilerinin kapsadığı zaman aralığını tanımlar.
- Kaynağın
downloadUrl özelliği, raporun alınabileceği URL'yi tanımlar.
- Kaynağın
createTime özelliği, raporun oluşturulduğu tarih ve saati belirtir. Uygulamanız bu değeri saklamalı ve daha önce indirilen raporların değişip değişmediğini belirlemek için kullanmalıdır.
4. adım: Raporu indirin
Raporu almak için 4. adımda elde edilen downloadUrl değerine bir HTTP GET isteği gönderin.
İşleme raporları
En iyi uygulamalar
YouTube Reporting API'yi kullanan uygulamalar her zaman şu uygulamaları takip etmelidir:
-
Raporun sütunlarının sıralamasını belirlemek için raporun başlık satırını kullanın. Örneğin, görüntülemeler, rapor açıklamasında listelenen ilk metrik olduğu için raporda döndürülen ilk metrik olacağını varsaymayın. Bunun yerine, hangi sütunda bu verilerin bulunduğunu belirlemek için raporun başlık satırını kullanın.
-
Aynı raporun tekrar tekrar işlenmesini önlemek için indirdiğiniz raporların kaydını tutun. Aşağıdaki listede bunu yapmanın birkaç yolu önerilmektedir.
-
reports.list yöntemini çağırırken yalnızca belirli bir tarihten sonra oluşturulan raporları almak için createdAfter parametresini kullanın. (Raporları ilk kez aldığınızda createdAfter parametresini atlayın.)
Raporları her aldığınızda ve başarılı bir şekilde işlediğinizde, bu raporların en yenisinin oluşturulduğu tarih ve saate karşılık gelen zaman damgasını saklayın. Ardından, API'yi her çağırdığınızda yalnızca yeni raporları (geri doldurulmuş veriler içeren yeni raporlar dahil) aldığınızdan emin olmak için reports.list yöntemine yapılan her ardışık çağrıda createdAfter parametre değerini güncelleyin.
Güvenlik önlemi olarak, raporu almadan önce raporun kimliğinin veritabanınızda listelenmediğinden de emin olun.
-
İndirip işlediğiniz her raporun kimliğini saklayın. Ayrıca, her raporun oluşturulduğu tarih ve saat veya raporun startTime ve endTime gibi ek bilgileri de saklayabilirsiniz. Bu bilgiler, raporun veri içerdiği dönemi birlikte tanımlar. YouTube Analytics için toplu verileri alan raporlarda, her rapor 24 saatlik bir döneme ait veriler içerdiğinden her işte muhtemelen birçok rapor bulunur. Daha uzun zaman aralıklarını kapsayan sistem tarafından yönetilen işlerde daha az rapor bulunur.
Hâlâ indirmeniz ve içe aktarmanız gereken raporları belirlemek için rapor kimliğini kullanın. Ancak iki yeni rapor aynı startTime ve endTime özellik değerlerine sahipse yalnızca daha yeni createTime değerine sahip raporu içe aktarın.
Rapor özellikleri
API raporları, aşağıdaki özelliklere sahip .csv (virgülle ayrılmış değerler) dosyalarıdır:
-
Her rapor, raporun başlangıç tarihinde Pasifik saatiyle 00:00'dan raporun bitiş tarihinde Pasifik saatiyle 23:59'a kadar süren benzersiz bir döneme ait verileri içerir.
-
Rapor verileri sıralanmamış.
Aksi belirtilmediği sürece bu sayfanın içeriği Creative Commons Atıf 4.0 Lisansı altında ve kod örnekleri Apache 2.0 Lisansı altında lisanslanmıştır. Ayrıntılı bilgi için Google Developers Site Politikaları'na göz atın. Java, Oracle ve/veya satış ortaklarının tescilli ticari markasıdır.
Son güncelleme tarihi: 2025-08-21 UTC.
[null,null,["Son güncelleme tarihi: 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."]]
