YouTube Reporting API - Get Bulk Data Reports
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
YouTube genera automaticamente una serie di report sulle entrate pubblicitarie gestiti dal sistema per i proprietari dei contenuti che hanno accesso ai report corrispondenti in Creator Studio. Questi report sono progettati per fornire l'accesso programmatico ai dati disponibili anche nei report scaricabili manualmente accessibili nel menu Report di YouTube Creator Studio.
Nota:l'API fornisce l'accesso a un insieme di report diverso da Creator Studio, anche se i report contengono dati simili. I report API potrebbero avere campi diversi e utilizzare anche nomi di campi diversi rispetto ai report di Creator Studio.
Poiché YouTube genera automaticamente i report gestiti dal sistema, la procedura per recuperare questi report è diversa da quella per i report sui dati collettivi di YouTube Analytics disponibili tramite l'API.
Recupero dei report
I passaggi seguenti spiegano come recuperare i report gestiti dal sistema tramite l'API.
Passaggio 1: recupera le credenziali di autorizzazione
Tutte le richieste all'API YouTube Reporting devono essere autorizzate. La guida all'autorizzazione spiega come utilizzare il protocollo OAuth 2.0 per recuperare i token di autorizzazione.
Le richieste all'API YouTube Reporting utilizzano i seguenti ambiti di autorizzazione:
| Ambiti |
| https://www.googleapis.com/auth/yt-analytics.readonly |
Visualizzare i report di YouTube Analytics per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività degli utenti, come i conteggi delle visualizzazioni e delle valutazioni. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
Visualizzare i report Analytics su YouTube relativi al valore monetario per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività utente e alle metriche stimate su entrate e rendimento degli annunci. |
Passaggio 2: recupera l'ID job per il report desiderato
Chiama il metodo jobs.list per recuperare un elenco di job gestiti dal sistema. Imposta il parametro includeSystemManaged su true.
La proprietà reportTypeId in ogni risorsa Job restituita identifica il tipo di report gestito dal sistema associato a quel job. Nel passaggio successivo, l'applicazione ha bisogno del valore della proprietà id della stessa risorsa.
Il documento Report elenca i report disponibili, i relativi ID tipo di report e i campi che contengono. Puoi anche utilizzare il metodo reportTypes.list per recuperare un elenco dei tipi di report supportati.
Passaggio 3: recupera l'URL di download del report
Chiama il metodo jobs.reports.list per recuperare un elenco di report creati per il job. Nella richiesta, imposta il parametro jobId sull'ID job del report che vuoi recuperare.
Puoi filtrare l'elenco dei report utilizzando uno o tutti i seguenti parametri:
-
Utilizza il parametro createdAfter per indicare che l'API deve restituire solo i report creati dopo un determinato orario. Questo parametro può essere utilizzato per garantire che l'API restituisca solo i report che non hai ancora elaborato.
-
Utilizza il parametro startTimeBefore per indicare che la risposta dell'API deve contenere report solo se i dati meno recenti del report sono precedenti alla data specificata. Mentre il parametro createdAfter si riferisce al momento della creazione del report, questa data si riferisce ai dati nel report.
-
Utilizza il parametro startTimeAtOrAfter per indicare che la risposta dell'API deve contenere report solo se i dati meno recenti del report sono stati registrati a partire dalla data specificata. Come il parametro startTimeBefore, questo valore del parametro corrisponde ai dati nel report e non all'ora in cui è stato creato.
La risposta dell'API contiene un elenco di risorse Report per il job. Ogni risorsa si riferisce a un report che contiene dati per un periodo univoco.
- Le proprietà
startTime e endTime della risorsa identificano il periodo di tempo coperto dai dati del report.
- La proprietà
downloadUrl della risorsa identifica l'URL da cui è possibile recuperare il report.
- La proprietà
createTime della risorsa specifica la data e l'ora in cui è stato generato il report. La tua applicazione deve memorizzare questo valore e utilizzarlo per determinare se i report scaricati in precedenza sono stati modificati.
Passaggio 4: scarica il report
Invia una richiesta HTTP GET all'downloadUrl ottenuto nel passaggio 4 per recuperare il report.
Elaborazione dei report
Best practice
Le applicazioni che utilizzano l'API YouTube Reporting devono sempre seguire queste pratiche:
-
Utilizza la riga di intestazione di un report per determinare l'ordine delle colonne del report. Ad esempio, non dare per scontato che le visualizzazioni saranno la prima metrica restituita in un report solo perché è la prima metrica elencata nella descrizione di un report. Utilizza invece la riga di intestazione del report per determinare la colonna contenente i dati.
-
Tieni un registro dei report che hai scaricato per evitare di elaborare ripetutamente lo stesso report. Il seguente elenco suggerisce un paio di modi per farlo.
-
Quando chiami il metodo reports.list, utilizza il parametro createdAfter per recuperare solo i report creati dopo una determinata data. (Ometti il parametro createdAfter la prima volta che recuperi i report.)
Ogni volta che recuperi ed elabori correttamente i report, memorizza il timestamp corrispondente alla data e all'ora in cui è stato creato il più recente. Poi, aggiorna il valore del parametro createdAfter a ogni chiamata successiva al metodo reports.list per assicurarti di recuperare solo i nuovi report, inclusi quelli con dati di riempimento, ogni volta che chiami l'API.
Come misura di sicurezza, prima di recuperare un report, verifica anche che il relativo ID non sia già presente nel tuo database.
-
Memorizza l'ID di ogni report che hai scaricato ed elaborato. Puoi anche memorizzare informazioni aggiuntive come la data e l'ora in cui è stato generato ogni report o il startTime e il endTime del report, che insieme identificano il periodo per il quale il report contiene dati. Per i report che recuperano dati collettivi per YouTube Analytics, ogni job avrà probabilmente molti report, poiché ogni report contiene dati per un periodo di 24 ore. I job gestiti dal sistema che coprono periodi di tempo più lunghi avranno meno report.
Utilizza l'ID report per identificare i report che devi ancora scaricare e importare. Tuttavia, se due nuovi report hanno gli stessi valori delle proprietà startTime e endTime, importa solo il report con il valore createTime più recente.
Caratteristiche del report
I report API sono file .csv (valori separati da virgola) con controllo delle versioni e con le seguenti caratteristiche:
-
Ogni report contiene dati per un periodo univoco che va dalle ore 00:00 del fuso orario del Pacifico del giorno di inizio del report alle ore 23:59 del fuso orario del Pacifico del giorno di fine del report.
-
I dati del report non sono ordinati.
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-08-21 UTC.
[null,null,["Ultimo aggiornamento 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."]]
