YouTube Reporting API - Get Bulk Data Reports
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
YouTube では、クリエイター ツールで対応するレポートにアクセスできるコンテンツ所有者向けに、システム管理の広告収益レポートが自動的に生成されます。これらのレポートは、YouTube クリエイター ツールの [レポート メニュー] で手動でダウンロードできるレポートでも確認できるデータに、プログラムでアクセスできるように設計されています。
注: API でアクセスできるレポートは、YouTube Studio のレポートとは異なりますが、レポートに含まれるデータは類似しています。API レポートには、クリエイター ツールのレポートとは異なるフィールドが含まれ、異なるフィールド名が使用されている場合があります。
YouTube ではシステム管理レポートが自動的に生成されるため、これらのレポートを取得するプロセスは、API で利用できる YouTube アナリティクスのバルクデータ レポートとは異なります。
レポートの取得
次の手順では、API を介してシステム管理レポートを取得する方法について説明します。
ステップ 1: 認証情報を取得する
YouTube Reporting API へのすべてのリクエストは承認を受ける必要があります。認可ガイドでは、OAuth 2.0 プロトコルを使用して認可トークンを取得する方法について説明しています。
YouTube Reporting API リクエストでは、次の認証スコープが使用されます。
| スコープ |
| https://www.googleapis.com/auth/yt-analytics.readonly |
YouTube コンテンツの YouTube アナリティクス レポートを表示します。このスコープは再生回数や評価数など、ユーザー アクティビティの指標へのアクセスを提供します。 |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
YouTube コンテンツに関する YouTube アナリティクス収益レポートを表示します。このスコープは、ユーザー アクティビティの指標と、推定収益と広告パフォーマンスの指標へのアクセスを提供します。 |
ステップ 2: 目的のレポートのジョブ ID を取得する
jobs.list メソッドを呼び出して、システム管理ジョブのリストを取得します。includeSystemManaged パラメータを true に設定します。
返された各 Job リソースの reportTypeId プロパティは、そのジョブに関連付けられているシステム管理レポートのタイプを識別します。次のステップでは、同じリソースの id プロパティ値が必要です。
レポート ドキュメントには、利用可能なレポート、レポートタイプの ID、レポートに含まれるフィールドが記載されています。reportTypes.list メソッドを使用して、サポートされているレポートタイプの一覧を取得することもできます。
ステップ 3: レポートのダウンロード URL を取得する
jobs.reports.list メソッドを呼び出して、ジョブ用に作成されたレポートの一覧を取得します。リクエストで、jobId パラメータを取得するレポートのジョブ ID に設定します。
次のパラメータのいずれかまたはすべてを使用して、レポートのリストをフィルタできます。
-
createdAfter パラメータを使用して、指定した日時以降に作成されたレポートのみを API が返すように指定します。このパラメータを使用すると、API がまだ処理していないレポートのみを返すようにできます。
-
startTimeBefore パラメータを使用して、レポート内の最も古いデータが指定した日付より前の場合にのみ、API レスポンスにレポートを含めるように指定します。createdAfter パラメータはレポートが作成された時刻に関連しますが、この日付はレポート内のデータに関連します。
-
startTimeAtOrAfter パラメータを使用して、レポートの最も古いデータが指定した日付以降の場合にのみ、API レスポンスにレポートを含めるように指定します。startTimeBefore パラメータと同様に、このパラメータ値はレポートのデータに対応しており、レポートの作成時間には対応していません。
API レスポンスには、そのジョブの Report リソースのリストが含まれます。各リソースは、一意の期間のデータを含むレポートを参照します。
- リソースの
startTime プロパティと endTime プロパティは、レポートのデータが対象とする期間を示します。
- リソースの
downloadUrl プロパティは、レポートを取得できる URL を識別します。
- リソースの
createTime プロパティは、レポートが生成された日時を指定します。アプリケーションはこの値を保存し、以前にダウンロードしたレポートが変更されたかどうかを判断するために使用する必要があります。
ステップ 4: レポートをダウンロードする
ステップ 4 で取得した downloadUrl に HTTP GET リクエストを送信して、レポートを取得します。
レポートの処理
ベスト プラクティス
YouTube Reporting API を使用するアプリは、常に次のプラクティスに従う必要があります。
-
レポートのヘッダー行を使用して、レポートの列の順序を決定します。たとえば、レポートの説明に最初に記載されている指標が「ビュー」であるからといって、レポートで最初に返される指標が「ビュー」であるとは限りません。代わりに、レポートのヘッダー行を使用して、そのデータを含む列を特定します。
-
同じレポートを繰り返し処理しないように、ダウンロードしたレポートの記録を保持します。以下に、そのための 2 つの方法を示します。
-
reports.list メソッドを呼び出す際は、createdAfter パラメータを使用して、特定の日付以降に作成されたレポートのみを取得します。（レポートを初めて取得するときは、createdAfter パラメータを省略します）。
レポートを取得して正常に処理するたびに、それらのレポートの最新のものが作成された日時に対応するタイムスタンプを保存します。次に、reports.list メソッドの呼び出しごとに createdAfter パラメータの値を更新して、API を呼び出すたびに、バックフィルされたデータを含む新しいレポートのみを取得するようにします。
安全対策として、レポートを取得する前に、レポートの ID がデータベースにまだ登録されていないことを確認してください。
-
ダウンロードして処理した各レポートの ID を保存します。各レポートが生成された日時や、レポートにデータが含まれる期間を特定するレポートの startTime と endTime などの追加情報を保存することもできます。YouTube アナリティクスのデータを一括で取得するレポートの場合、各レポートには 24 時間分のデータが含まれているため、各ジョブには多くのレポートが含まれる可能性があります。より長い期間を対象とするシステム管理ジョブでは、レポートの数が少なくなります。
レポート ID を使用して、ダウンロードとインポートが必要なレポートを特定します。ただし、2 つの新しいレポートの startTime プロパティと endTime プロパティの値が同じ場合は、createTime 値が新しいレポートのみをインポートします。
レポートの特性
API レポートは、次の特性を持つバージョン管理された .csv（カンマ区切り値）ファイルです。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-21 UTC。
[null,null,["最終更新日 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."]]
