Solicitar relatórios
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
A nova API Search Ads 360 Reporting já está disponível. Ela oferece mais flexibilidade para criar relatórios personalizados e integrar os dados aos seus aplicativos e processos relacionados à geração de relatórios. Saiba mais sobre como migrar e usar a
nova API Search Ads 360 Reporting.
Depois de configurar o app cliente conforme descrito em Meu primeiro app, use a API Search Ads 360 para solicitar e fazer o download de relatórios. É possível fazer um dos seguintes tipos de solicitação:
- Síncrono
Requer apenas uma solicitação e retorna o relatório em uma resposta formatada em JSON. Solicitações síncronas:
Se você solicitar grandes relatórios de contas de mecanismo ou anunciantes, recomendamos a abordagem assíncrona.
- Assíncrono
Exige que você envie uma solicitação inicial que especifique os dados desejados no
relatório. Depois, você envia outras solicitações para pesquisar no Search Ads 360. Quando o Search Ads 360 terminar de gerar o relatório, você enviará solicitações para fazer o download dele como um ou mais arquivos. Solicitações assíncronas:
- Pode retornar qualquer tipo de relatório.
- Fragmenta relatórios muito grandes em vários arquivos
- Formata relatórios como CSV ou TSV
Modelo de dados: linhas e colunas
O Search Ads 360 organiza os dados de um relatório em linhas e colunas.
O tipo de relatório solicitado determina as linhas retornadas.
Por exemplo, se você solicitar um relatório de palavras-chave, cada linha conterá dados sobre uma única palavra-chave. Consulte a referência Tipos de relatório para ver uma lista com todos os tipos de relatório.
Para especificar quais colunas quer incluir no relatório, nomeie cada uma
na solicitação. Consulte a referência Tipos de relatório para ver a lista de colunas que podem ser retornadas em cada tipo de relatório.
Comportamentos das colunas
O comportamento de uma coluna depende do tipo de dados que ela contém (a referência Tipos de relatório exibe o comportamento de cada coluna):
Colunas de atributos. Uma coluna de atributos contém dados que configuram ou identificam uma entidade em uma campanha, como o nome da campanha ou um lance de palavra-chave. A API Search Ads 360 sempre retorna o valor atual de uma coluna de atributo, independentemente da data ou do período especificado em uma solicitação. Por exemplo, se você alterou o lance de uma palavra-chave de 2,00 para 1,50 ontem e, em seguida, solicitou um relatório com os dados do mês passado, o relatório retornará um valor de 1,50.
Colunas de métricas. Uma coluna de métrica contém dados sobre o desempenho da sua campanha, como o número de cliques em um anúncio, o número de visitas conforme registrado por uma tag do Floodlight ou a receita. A menos que você especifique um período de um único dia, a API retornará um valor agregado para as colunas de métricas. Por exemplo, se você solicitar um relatório com os dados do mês passado, a API retornará o número total de cliques do mês passado.
Segmentar colunas Uma coluna de segmento divide os dados em linhas separadas.
Por exemplo, date é uma coluna de segmento que pode ser especificada para diversos tipos de relatórios. Se você especificar a coluna date em um relatório de palavra-chave com o período de 01/01/2013 a 07/01/2013, a API retornará sete linhas para cada palavra-chave, cada uma correspondente a um dia e exibindo as métricas desse dia. Consulte Relatórios segmentados.
Moedas
Sua solicitação de relatório é obrigatória para especificar a moeda dos dados monetários (tanto atributos como dailyBudget quanto métricas como cost). É possível especificar uma das seguintes opções:
- A moeda da agência, se o escopo do relatório for
de uma agência, um anunciante ou uma conta de mecanismo.
- A moeda do anunciante, se o escopo do relatório for um anunciante ou uma conta de mecanismo.
- A moeda da conta de mecanismo, se o escopo do relatório for uma conta de mecanismo.
- USD
Use a propriedade de solicitação Reports.request.statisticsCurrency para especificar uma moeda.
O relatório vai indicar a moeda na propriedade Reports.statisticsCurrencyCode.
Fuso horário
As métricas do Search Ads 360 são armazenadas em datas sem fusos horários. Essas datas correspondem ao fuso horário da conta de mecanismo para as métricas de mecanismo (como cliques, impressões e visitas) e ao fuso horário da rede do Campaign Manager para métricas de conversão (como ações, transações e receita). Quando todas as métricas em um relatório vierem do mesmo fuso horário,
esse fuso horário será retornado na solicitação. Caso contrário, nenhum fuso horário será retornado.
Suas solicitações podem configurar Reports.request.verifySingleTimeZone: true
para gerar relatórios de falha que apresentam métricas de mais de um fuso horário.
Se todas as métricas presentes em um relatório forem de um fuso horário, esse fuso horário será
retornado em Reports.statisticsTimeZoneReports.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-29 UTC.
[null,null,["Última atualização 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)."]]
