YouTube Reporting API - Get Bulk Data Reports
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
YouTube는 크리에이터 스튜디오에서 해당 보고서에 액세스할 수 있는 콘텐츠 소유자를 위해 시스템에서 관리하는 광고 수익 보고서를 자동으로 생성합니다. 이 보고서는 YouTube 크리에이터 스튜디오의 보고서 메뉴에서 액세스할 수 있는 수동 다운로드 가능 보고서에서도 제공되는 데이터에 프로그래매틱 방식으로 액세스할 수 있도록 설계되었습니다.
참고: API는 크리에이터 스튜디오와 다른 보고서 세트에 대한 액세스를 제공하지만 보고서에는 유사한 데이터가 포함됩니다. 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를 사용하는 애플리케이션은 항상 다음 관행을 따라야 합니다.
-
보고서의 헤더 행을 사용하여 보고서 열의 순서를 확인합니다. 예를 들어 조회수가 보고서 설명에 나열된 첫 번째 측정항목이라는 이유만으로 보고서에서 반환되는 첫 번째 측정항목이라고 가정하지 마세요. 대신 보고서의 헤더 행을 사용하여 해당 데이터가 포함된 열을 확인하세요.
-
동일한 보고서를 반복적으로 처리하지 않도록 다운로드한 보고서를 기록해 두세요. 다음 목록에서는 이를 수행하는 몇 가지 방법을 제안합니다.
-
reports.list 메서드를 호출할 때 createdAfter 매개변수를 사용하여 특정 날짜 이후에 생성된 보고서만 가져옵니다. (보고서를 처음 가져올 때는 createdAfter 매개변수를 생략합니다.)
보고서를 가져와서 성공적으로 처리할 때마다 이러한 보고서 중 가장 최신 보고서가 생성된 날짜 및 시간에 해당하는 타임스탬프를 저장합니다. 그런 다음 reports.list 메서드를 연속으로 호출할 때마다 createdAfter 매개변수 값을 업데이트하여 API를 호출할 때마다 데이터가 채워진 새 보고서를 포함한 새 보고서만 가져오도록 합니다.
안전 장치로 보고서를 가져오기 전에 보고서의 ID가 데이터베이스에 아직 나열되어 있지 않은지 확인하세요.
-
다운로드하고 처리한 각 보고서의 ID를 저장합니다. 각 보고서가 생성된 날짜 및 시간 또는 보고서에 데이터가 포함된 기간을 함께 식별하는 보고서의 startTime 및 endTime와 같은 추가 정보를 저장할 수도 있습니다. YouTube 분석의 대량 데이터를 가져오는 보고서의 경우 각 보고서에 24시간 동안의 데이터가 포함되어 있으므로 각 작업에 많은 보고서가 있을 수 있습니다. 더 긴 기간을 포함하는 시스템 관리 작업에는 보고서가 더 적게 표시됩니다.
보고서 ID를 사용하여 아직 다운로드하고 가져와야 하는 보고서를 식별합니다. 하지만 두 개의 새 보고서의 startTime 및 endTime 속성 값이 동일한 경우 createTime 값이 더 최신인 보고서만 가져옵니다.
보고서 특성
API 보고서는 다음과 같은 특징이 있는 버전이 지정된 .csv (쉼표로 구분된 값) 파일입니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 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."]]
