보고서 요청
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이제 새 Search Ads 360 Reporting API를 사용할 수 있습니다. 새로운 API를 사용하면 더욱 유연하게 맞춤 보고서를 작성하고, 데이터를 보고 애플리케이션 및 프로세스에 통합할 수 있습니다.
새 Search Ads 360 Reporting API로 이전하고 이를 사용하는 방법에 대해 자세히 알아보세요.
내 첫 번째 앱에 설명된 대로 클라이언트 앱을 설정한 후에는 Search Ads 360 API를 사용하여 보고서를 요청하고 다운로드할 수 있습니다. 다음 유형의 요청 중 하나를 실행할 수 있습니다.
- 동기
단일 요청만 필요하며 JSON 형식의 응답으로 보고서를 반환합니다. 동기식 요청:
- 광고주 및 엔진 계정 보고서만 반환할 수 있습니다.
- Search Ads 360에서 보고서를 생성할 때까지 클라이언트를 차단합니다.
대규모 광고주 또는 엔진 계정 보고서를 요청하는 경우 비동기식 방식을 사용하는 것이 좋습니다.
- 비동기
보고서에 포함하려는 데이터를 지정하는 초기 요청을 전송해야 합니다. 그런 다음 Search Ads 360 폴링을 위한 추가 요청을 보냅니다. Search Ads 360에서 보고서 생성이 완료되면 보고서를 하나 이상의 파일로 다운로드하라는 요청을 보냅니다. 비동기식 요청:
- 모든 보고서 유형을 반환할 수 있습니다.
- 매우 큰 보고서를 여러 파일로 샤딩합니다.
- CSV 또는 TSV로 보고서 형식 지정
데이터 모델: 행과 열
Search Ads 360은 보고서의 데이터를 행과 열로 구성합니다.
요청하는 보고서의 유형에 따라 반환되는 행이 결정됩니다.
예를 들어 키워드 보고서를 요청하는 경우 각 행에는 단일 키워드에 대한 데이터가 포함됩니다. 모든 보고서 유형의 목록은 보고서 유형 참조를 참고하세요.
보고서 요청에서 각 열의 이름을 지정하여 보고서에 포함할 열을 지정합니다. 각 보고서 유형에서 반환할 수 있는 열의 목록은 보고서 유형 참조를 참고하세요.
열 동작
열의 동작은 열에 포함된 데이터 유형에 따라 다릅니다 (보고서 유형 참조에 각 열의 동작이 표시됩니다).
속성 열. 속성 열에는 캠페인 이름 또는 키워드 입찰가와 같이 캠페인의 항목을 구성하거나 식별하는 데이터가 포함됩니다. Search Ads 360 API는 요청에 지정된 날짜 또는 기간에 관계없이 항상 속성 열의 현재 값을 반환합니다. 예를 들어 어제 키워드 입찰가를 2.00에서 1.50으로
변경한 후 지난 달의 데이터에 대한 보고서를 요청하면 보고서에서
키워드 입찰가에 1.50 값을 반환합니다.
측정항목 열. 측정항목 열에는 광고 클릭수, 플러드라이트 태그에 기록된 방문수, 수익과 같은
캠페인 실적 데이터가 포함됩니다. 하루 기간을 지정하지 않는 한 API는 측정항목 열의 집계 값을 반환합니다. 예를 들어 지난달 데이터에 대한 보고서를 요청하면 API에서 지난달의 총 클릭수를 반환합니다.
분류 기준 열. 분류 기준 열은 데이터를 별도의 행으로 분할합니다.
예를 들어 date는 여러 유형의 보고서에 지정할 수 있는 분류 기준 열입니다. 기간이 2013-01-01에서 2013-01-07인 키워드 보고서에서 date 열을 지정하면 API는 각 키워드에 대해 각각 하루에 해당하는 7개의 행을 반환하고 해당 날짜의 측정항목을 표시합니다. 분류된 보고서를 참조하세요.
시간대
Search Ads 360 측정항목은 시간대가 없는 날짜에 저장됩니다. 이 날짜는 엔진 측정항목 (예: 클릭수, 노출수, 방문수)의
엔진 계정 시간대 및 전환 측정항목 (예: 액션,
거래, 수익)의 Campaign Manager 네트워크 시간대와
일치합니다. 보고서의 모든 측정항목이 동일한 시간대에서 비롯되는 경우 요청에 해당 시간대가 반환됩니다. 그렇지 않으면 시간대가 반환되지 않습니다.
요청은 두 개 이상의 시간대에서 측정항목을 표시하는 보고서를 실패하도록 Reports.request.verifySingleTimeZone: true를 설정할 수 있습니다.
보고서에 있는 모든 측정항목이 한 시간대에서 비롯된 경우 해당 시간대는 Reports.statisticsTimeZoneReports로 반환됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eThe new Search Ads 360 Reporting API offers enhanced flexibility for building custom reports and integrating data into your workflows.\u003c/p\u003e\n"],["\u003cp\u003eYou can make synchronous requests for quick advertiser and engine account reports, or asynchronous requests for larger reports and various report types.\u003c/p\u003e\n"],["\u003cp\u003eReports are organized into rows based on the report type and columns that you specify in your request, with attribute, metric, and segment columns behaving differently.\u003c/p\u003e\n"],["\u003cp\u003eWhen requesting reports, you need to specify the currency for monetary data, and Search Ads 360 handles time zones based on engine and conversion metric sources.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API allows custom report building and data integration. Reports can be requested synchronously (limited to advertiser/engine account reports, JSON format, blocking) or asynchronously (all report types, CSV/TSV format, multiple files). Data is organized in rows and columns; column behavior varies by type (attribute, metric, segment). Currency for monetary data must be specified and can be the agency's, advertiser's, or engine account's or USD. Time zones are relevant to metric dates.\n"],null,["# Request Reports\n\nThe new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the [new Search Ads 360 Reporting\nAPI](https://developers.google.com/search-ads/reporting/overview).\n\n\nAfter you've set up your client app as described in [My First App](/search-ads/v2/first-app), you can use the Search Ads 360 API\nto request and download reports. You can make either of the following types of\nrequests:\n\n**[Synchronous](/search-ads/v2/how-tos/reporting/synchronous-requests)**\n\n: Requires just a single request and returns the report in a JSON-formatted response. Synchronous requests:\n\n - Can return only [advertiser](/search-ads/v2/report-types/advertiser) and [engine account](/search-ads/v2/report-types/account) reports\n - Block your client until Search Ads 360 generates the report\n\n\n If you're requesting large advertiser or engine-account reports, we recommend the\n asynchronous approach.\n\n**[Asynchronous](/search-ads/v2/how-tos/reporting/asynchronous-requests)**\n\n: Requires you to send an initial request that specifies the data you want in the\n report. Then you send additional requests to poll Search Ads 360. When Search Ads 360 finishes generating the report,\n you send requests to download the report as one or more files. Asynchronous requests:\n\n - Can return any [report type](/search-ads/v2/report-types)\n - Shards very large reports into multiple files\n - Formats reports as CSV or TSV\n\n### Data model: rows and columns\n\nSearch Ads 360 organizes data in a report into rows and columns.\nThe type of report you request determines the **rows** that are returned.\nFor example, if your request a keyword report, each row will contain data about a single\nkeyword. See the [Report Types](/search-ads/v2/report-types)\nreference for a list of all report types.\nYou specify which **columns** you want in the report by naming each column\nin your report request. See the [Report\nTypes](/search-ads/v2/report-types) reference for the list of columns that can be returned for each report type.\n\n### Column behaviors\n\n\nThe behavior of a column depends on the type of data that the column\ncontains (the [Report Types](/search-ads/v2/report-types) reference\ndisplays each column's behavior):\n\n-\n **Attribute columns**. An attribute column contains data that configures\n or identifies an entity in a campaign, such as the campaign name or a keyword bid. The Search Ads 360 API\n always returns the current value for an attribute column, regardless of any date or\n date range specified in a request. For example, if you changed a keyword's bid from\n 2.00 to 1.50 yesterday and then request a report for last month's data, the report\n will return a value of 1.50 for the keyword bid.\n\n-\n **Metric columns** . A metric column contains data about your campaign's\n performance, such as the number of clicks on an ad, the number of visits as recorded\n by a Floodlight tag, or revenue. Unless you [specify a\n time range](/search-ads/v2/reference/reports#request.timeRange) of a single day, the API returns an aggregate value for metric columns. For\n example, if you request a report for last month's data, the API will return the total\n number of clicks for last month.\n\n-\n **Segment columns** . A segment column splits data into separate rows.\n For example, `date` is a segment column that you can specify for many\n types of reports. If you specify the `date` column in a keyword report\n with a date range 2013-01-01 to 2013-01-07, the API would return seven rows for each\n keyword, each corresponding to one day and displaying metrics for that day. See [Segmented\n Reports](/search-ads/v2/how-tos/reporting/segmented-reports).\n\n### Currencies\n\n\nYour report request is required to specify the currency of monetary data (both attributes like `dailyBudget` and metrics like\n`cost`). You can specify one of the following:\n\n- The agency's currency, if the report is [scoped](/search-ads/v2/reference/reports#request.reportScope) to an agency, advertiser, or engine account.\n- The advertiser's currency, if the report is scoped to an advertiser or engine account.\n- The engine account's currency, if the report is scoped to an engine account.\n- USD\n\n\nUse the [Reports.request.statisticsCurrency](/search-ads/v2/reference/reports#request.statisticsCurrency)\nrequest property to specify a currency.\n\n\nThe report itself will indicate the currency in the ` `[Reports.statisticsCurrencyCode](/search-ads/v2/reference/reports#statisticsCurrencyCode) property.\n\n### Time zone\n\n\nSearch Ads 360 metrics are stored in dates without time zones. These dates correspond to the engine\naccount time zone for engine metrics (such as clicks, impressions, and visits), and\nCampaign Manager network time zone for conversion metrics (such as actions,\ntransactions and revenue). When every metric in a report comes from the same time zone,\nthat time zone will be returned in the request. Otherwise, no time zone will be returned.\nYour requests can set [Reports.request.verifySingleTimeZone](/search-ads/v2/reference/reports#request.verifySingleTimeZone)`: true`\nto fail reports that present metric from more than one time zone.\n\n\nIf all metrics present in a report are from one time zone, that time zone is\nreturned in [Reports.statisticsTimeZoneReports](/search-ads/v2/reference/reports#statisticsTimeZone)."]]
