YouTube Reporting API - Get Bulk Data Reports
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
YouTube automatycznie generuje zestaw raportów o przychodach z reklam zarządzanych przez system dla właścicieli treści, którzy mają dostęp do odpowiednich raportów w Studio twórców. Raporty te zapewniają programowy dostęp do danych, które są też dostępne w raportach do pobrania ręcznie w menu Raporty w Studiu twórców YouTube.
Uwaga: interfejs API zapewnia dostęp do innego zestawu raportów niż Studio twórców, chociaż raporty zawierają podobne dane. Raporty interfejsu API mogą zawierać inne pola i używać innych nazw pól niż raporty w YouTube Studio.
YouTube automatycznie generuje raporty zarządzane przez system, dlatego proces pobierania tych raportów różni się od procesu pobierania raportów z dużą ilością danych Statystyk YouTube dostępnych za pomocą interfejsu API.
Pobieranie raportów
Poniżej znajdziesz instrukcje pobierania raportów zarządzanych przez system za pomocą interfejsu API.
Krok 1. Pobierz dane logowania autoryzacji
Wszystkie żądania do interfejsu YouTube Reporting API muszą być autoryzowane. W przewodniku po autoryzacji znajdziesz informacje o tym, jak używać protokołu OAuth 2.0 do pobierania tokenów autoryzacji.
Żądania do interfejsu YouTube Reporting API używają tych zakresów autoryzacji:
| Zakresy |
| https://www.googleapis.com/auth/yt-analytics.readonly |
Wyświetlanie raportów Statystyk YouTube dotyczących treści w YouTube. Ten zakres zapewnia dostęp do danych o aktywności użytkowników, takich jak liczba wyświetleń i ocen. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
Wyświetlanie raportów finansowych Statystyk YouTube dotyczących treści w YouTube. Ten zakres zapewnia dostęp do danych o aktywności użytkowników oraz do szacunkowych danych o przychodach i skuteczności reklam. |
Krok 2. Pobierz identyfikator zadania dla wybranego raportu
Aby pobrać listę zadań zarządzanych przez system, wywołaj metodę jobs.list. Ustaw parametr includeSystemManaged na true.
Właściwość reportTypeId w każdym zwróconym zasobie Job identyfikuje typ raportu zarządzanego przez system, który jest powiązany z tym zadaniem. W następnym kroku aplikacja będzie potrzebować wartości właściwości id z tego samego zasobu.
Dokument Raporty zawiera listę dostępnych raportów, ich identyfikatory typu raportu i pola, które zawierają. Możesz też użyć metody reportTypes.list, aby pobrać listę obsługiwanych typów raportów.
Krok 3. Pobierz adres URL pobierania raportu
Wywołaj metodę jobs.reports.list, aby pobrać listę raportów utworzonych dla zadania. W żądaniu ustaw parametr jobId na identyfikator zadania raportu, który chcesz pobrać.
Listę raportów możesz filtrować za pomocą dowolnych lub wszystkich z tych parametrów:
-
Użyj parametru createdAfter, aby wskazać, że interfejs API ma zwracać tylko raporty utworzone po określonym czasie. Ten parametr może służyć do zapewnienia, że interfejs API zwraca tylko raporty, które nie zostały jeszcze przez Ciebie przetworzone.
-
Użyj parametru startTimeBefore, aby wskazać, że odpowiedź interfejsu API powinna zawierać tylko raporty, w których najwcześniejsze dane pochodzą sprzed określonej daty. Parametr createdAfter odnosi się do czasu utworzenia raportu, a ta data dotyczy danych w raporcie.
-
Użyj parametru startTimeAtOrAfter, aby wskazać, że odpowiedź interfejsu API powinna zawierać tylko raporty, w których najwcześniejsze dane pochodzą z określonej daty lub są późniejsze. Podobnie jak parametr startTimeBefore, wartość tego parametru odpowiada danym w raporcie, a nie czasowi jego utworzenia.
Odpowiedź interfejsu API zawiera listę zasobów Report dla tego zadania. Każdy zasób odnosi się do raportu, który zawiera dane z unikalnego okresu.
- Właściwości
startTime i endTime zasobu określają okres, którego dotyczą dane w raporcie.
- Właściwość
downloadUrl zasobu określa adres URL, z którego można pobrać raport.
- Właściwość
createTime zasobu określa datę i godzinę wygenerowania raportu. Aplikacja powinna przechowywać tę wartość i używać jej do określania, czy wcześniej pobrane raporty uległy zmianie.
Krok 4. Pobierz raport
Aby pobrać raport, wyślij żądanie HTTP GET do adresu URL downloadUrl uzyskanego w kroku 4.
Raporty przetwarzania
Sprawdzone metody
Aplikacje korzystające z interfejsu YouTube Reporting API powinny zawsze postępować zgodnie z tymi zasadami:
-
Aby określić kolejność kolumn w raporcie, użyj wiersza nagłówka raportu. Nie zakładaj na przykład, że wyświetlenia będą pierwszymi danymi zwróconymi w raporcie tylko dlatego, że są pierwszymi danymi wymienionymi w jego opisie. Zamiast tego użyj wiersza nagłówka raportu, aby określić, która kolumna zawiera te dane.
-
Zapisuj informacje o pobranych raportach, aby uniknąć wielokrotnego przetwarzania tego samego raportu. Poniżej znajdziesz kilka sposobów, jak to zrobić.
-
Podczas wywoływania metody reports.list użyj parametru createdAfter, aby pobierać tylko raporty utworzone po określonej dacie. (Przy pierwszym pobieraniu raportów pomiń parametr createdAfter).
Za każdym razem, gdy pobierzesz i przetworzysz raporty, zapisz sygnaturę czasową odpowiadającą dacie i godzinie utworzenia najnowszego z nich. Następnie aktualizuj wartość parametru createdAfter w każdym kolejnym wywołaniu metody reports.list, aby za każdym razem, gdy wywołujesz interfejs API, pobierać tylko nowe raporty, w tym nowe raporty z danymi uzupełnionymi wstecznie.
Aby się zabezpieczyć, przed pobraniem raportu sprawdź, czy jego identyfikator nie jest już wymieniony w Twojej bazie danych.
-
Zapisz identyfikator każdego pobranego i przetworzonego raportu. Możesz też przechowywać dodatkowe informacje, takie jak data i godzina wygenerowania każdego raportu lub jego startTime i endTime, które razem określają okres, za który raport zawiera dane. W przypadku raportów, które pobierają dane zbiorcze ze Statystyk YouTube, każde zadanie będzie prawdopodobnie zawierać wiele raportów, ponieważ każdy z nich zawiera dane z 24-godzinnego okresu. W przypadku zadań zarządzanych przez system, które obejmują dłuższe okresy, będzie dostępnych mniej raportów.
Użyj identyfikatora raportu, aby zidentyfikować raporty, które musisz jeszcze pobrać i zaimportować. Jeśli jednak 2 nowe raporty mają te same wartości właściwości startTime i endTime, zaimportuj tylko raport z nowszą wartością createTime.
Charakterystyka raportu
Raporty interfejsu API to pliki .csv (z wartościami rozdzielonymi przecinkami) z wersjami, które mają te cechy:
-
Każdy raport zawiera dane z unikalnego okresu, który trwa od godziny 00:00 czasu pacyficznego w dniu rozpoczęcia raportu do godziny 23:59 czasu pacyficznego w dniu zakończenia raportu.
-
Dane w raporcie nie są posortowane.
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-08-21 UTC.
[null,null,["Ostatnia aktualizacja: 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."]]
