YouTube Reporting API - Get Bulk Data Reports
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
YouTube generiert automatisch eine Reihe von systemverwalteten Berichten zu Werbeeinnahmen für Rechteinhaber, die in YouTube Studio Zugriff auf die entsprechenden Berichte haben. Diese Berichte bieten programmatischen Zugriff auf Daten, die auch in manuell herunterladbaren Berichten im Menü „Berichte“ von YouTube Studio verfügbar sind.
Hinweis:Die API bietet Zugriff auf andere Berichte als Creator Studio. Die Berichte enthalten jedoch ähnliche Daten. API-Berichte können andere Felder und Feldnamen als Creator Studio-Berichte enthalten.
Da YouTube automatisch von Systemen verwaltete Berichte generiert, unterscheidet sich das Verfahren zum Abrufen dieser Berichte von dem für die YouTube Analytics-Bulk-Datenberichte, die über die API verfügbar sind.
Berichte abrufen
In den folgenden Schritten wird beschrieben, wie Sie systemverwaltete Berichte über die API abrufen.
Schritt 1: Autorisierungsanmeldedaten abrufen
Alle YouTube Reporting API-Anfragen müssen autorisiert sein. Im Autorisierungsleitfaden wird beschrieben, wie Sie mit dem OAuth 2.0-Protokoll Autorisierungstokens abrufen.
Für YouTube Reporting API-Anfragen werden die folgenden Autorisierungsbereiche verwendet:
| Ebenen |
| https://www.googleapis.com/auth/yt-analytics.readonly |
YouTube Analytics-Berichte für deine YouTube-Inhalte ansehen Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität wie Aufruf- und Bewertungszahlen. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
YouTube Analytics-Finanzberichte für deine YouTube-Inhalte abrufen Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität sowie auf geschätzte Umsatz- und Anzeigenleistungsmesswerte. |
Schritt 2: Job-ID für den gewünschten Bericht abrufen
Rufen Sie die Methode jobs.list auf, um eine Liste der vom System verwalteten Jobs abzurufen. Setzen Sie den Parameter includeSystemManaged auf true.
Die reportTypeId-Property in jeder zurückgegebenen Job-Ressource gibt den Typ des vom System verwalteten Berichts an, der mit diesem Job verknüpft ist. Ihre Anwendung benötigt den Wert des Attributs id aus derselben Ressource im nächsten Schritt.
Im Dokument Berichte sind die verfügbaren Berichte, ihre Berichtstyp-IDs und die Felder aufgeführt, die sie enthalten. Sie können auch mit der Methode reportTypes.list eine Liste der unterstützten Berichtstypen abrufen.
Schritt 3: Download-URL des Berichts abrufen
Rufen Sie die Methode jobs.reports.list auf, um eine Liste der für den Job erstellten Berichte abzurufen. Legen Sie in der Anfrage den Parameter jobId auf die Job-ID des Berichts fest, den Sie abrufen möchten.
Sie können die Liste der Berichte mit einem oder mehreren der folgenden Parameter filtern:
-
Mit dem Parameter createdAfter können Sie angeben, dass die API nur Berichte zurückgeben soll, die nach einem bestimmten Zeitpunkt erstellt wurden. Mit diesem Parameter können Sie dafür sorgen, dass die API nur Berichte zurückgibt, die Sie noch nicht verarbeitet haben.
-
Mit dem Parameter startTimeBefore können Sie angeben, dass die API-Antwort nur Berichte enthalten soll, wenn die frühesten Daten im Bericht vor dem angegebenen Datum liegen. Der Parameter createdAfter bezieht sich auf den Zeitpunkt, zu dem der Bericht erstellt wurde. Dieses Datum bezieht sich auf die Daten im Bericht.
-
Mit dem Parameter startTimeAtOrAfter geben Sie an, dass die API-Antwort nur Berichte enthalten soll, wenn die frühesten Daten im Bericht am oder nach dem angegebenen Datum liegen. Wie beim Parameter startTimeBefore entspricht dieser Parameterwert den Daten im Bericht und nicht dem Zeitpunkt, zu dem der Bericht erstellt wurde.
Die API-Antwort enthält eine Liste der Report-Ressourcen für diesen Job. Jede Ressource verweist auf einen Bericht, der Daten für einen bestimmten Zeitraum enthält.
- Die Eigenschaften
startTime und endTime der Ressource geben den Zeitraum an, für den die Daten des Berichts gelten.
- Die
downloadUrl-Property der Ressource gibt die URL an, über die der Bericht abgerufen werden kann.
- In der
createTime-Eigenschaft der Ressource wird das Datum und die Uhrzeit angegeben, zu der der Bericht generiert wurde. Ihre Anwendung sollte diesen Wert speichern und damit feststellen, ob sich zuvor heruntergeladene Berichte geändert haben.
Schritt 4: Bericht herunterladen
Senden Sie eine HTTP/GET-Anfrage an die in Schritt 4 abgerufene downloadUrl, um den Bericht abzurufen.
Berichte verarbeiten
Best Practices
Anwendungen, die die YouTube Reporting API verwenden, sollten immer die folgenden Best Practices einhalten:
-
Anhand der Kopfzeile eines Berichts können Sie die Reihenfolge der Spalten des Berichts bestimmen. Gehen Sie beispielsweise nicht davon aus, dass Aufrufe der erste Messwert ist, der in einem Bericht zurückgegeben wird, nur weil er der erste Messwert ist, der in einer Berichtsbeschreibung aufgeführt wird. Verwenden Sie stattdessen die Kopfzeile des Berichts, um zu ermitteln, in welcher Spalte diese Daten enthalten sind.
-
Führen Sie eine Liste der heruntergeladenen Berichte, um zu vermeiden, dass Sie denselben Bericht wiederholt verarbeiten. In der folgenden Liste finden Sie einige Vorschläge.
-
Verwenden Sie beim Aufrufen der Methode reports.list den Parameter createdAfter, um nur Berichte abzurufen, die nach einem bestimmten Datum erstellt wurden. Lassen Sie den Parameter createdAfter beim ersten Abrufen von Berichten weg.
Speichern Sie jedes Mal, wenn Sie Berichte abrufen und erfolgreich verarbeiten, den Zeitstempel, der dem Datum und der Uhrzeit entspricht, als der neueste dieser Berichte erstellt wurde. Aktualisieren Sie dann den Parameterwert createdAfter bei jedem nachfolgenden Aufruf der Methode reports.list, damit Sie bei jedem API-Aufruf nur neue Berichte abrufen, einschließlich neuer Berichte mit nachgetragenen Daten.
Prüfen Sie zur Sicherheit vor dem Abrufen eines Berichts, ob die ID des Berichts bereits in Ihrer Datenbank aufgeführt ist.
-
Speichern Sie die ID für jeden Bericht, den Sie heruntergeladen und verarbeitet haben. Sie können auch zusätzliche Informationen wie Datum und Uhrzeit speichern, zu denen die einzelnen Berichte generiert wurden, oder die startTime und endTime des Berichts, die zusammen den Zeitraum angeben, für den der Bericht Daten enthält. Bei Berichten, in denen Massendaten für YouTube Analytics abgerufen werden, enthält jeder Job wahrscheinlich viele Berichte, da jeder Bericht Daten für einen Zeitraum von 24 Stunden enthält. Bei systemverwalteten Jobs, die längere Zeiträume abdecken, sind weniger Berichte verfügbar.
Anhand der Berichts-ID können Sie Berichte identifizieren, die Sie noch herunterladen und importieren müssen. Wenn zwei neue Berichte jedoch dieselben startTime- und endTime-Eigenschaftswerte haben, importieren Sie nur den Bericht mit dem neueren createTime-Wert.
Berichtseigenschaften
API-Berichte sind versionierte .csv-Dateien (kommagetrennte Werte) mit den folgenden Merkmalen:
-
Jeder Bericht enthält Daten für einen eindeutigen Zeitraum, der am Startdatum des Berichts um 00:00 Uhr (Pacific Time) beginnt und am Enddatum des Berichts um 23:59 Uhr (Pacific Time) endet.
-
Die Berichtsdaten sind nicht sortiert.
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-21 (UTC).
[null,null,["Zuletzt aktualisiert: 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."]]
