Raporty żądań
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Dostępny jest już nowy interfejs Search Ads 360 Reporting API. Nowy interfejs API daje większą swobodę tworzenia raportów niestandardowych oraz integrowania danych z aplikacjami i procesami służącymi do raportowania. Dowiedz się więcej o przechodzeniu na
nowy interfejs Search Ads 360 Reporting API i jego używaniu.
Po skonfigurowaniu aplikacji klienckiej zgodnie z opisem w sekcji Moja pierwsza aplikacja możesz używać interfejsu Search Ads 360 API do wysyłania żądań i pobierania raportów. Możesz zgłaszać jeden z tych typów żądań:
- Synchroniczny
Wymaga tylko jednego żądania i zwraca raport w odpowiedzi w formacie JSON. Żądania synchroniczne:
Jeśli chcesz korzystać z dużych raportów o reklamodawcy lub koncie wyszukiwarki, zalecamy metodę asynchroniczne.
- Asynchroniczny
Wymaga wysłania wstępnego żądania określającego dane, które chcesz umieścić w raporcie. Następnie wysyłasz kolejne żądania do ankiet Search Ads 360. Gdy Search Ads 360 zakończy generowanie raportu, wysyłasz do niego prośbę o pobranie go w postaci co najmniej 1 pliku. Żądania asynchroniczne:
- Może zwracać dowolny typ raportu.
- Dzielenie bardzo dużych raportów na kilka plików
- Formatuje raporty jako CSV lub TSV
Model danych: wiersze i kolumny
Search Ads 360 porządkuje dane w raporcie w wierszach i kolumnach.
Typ żądanego raportu określa, jakie wiersze będą zwracane.
Jeśli np. poprosisz o raport słów kluczowych, każdy wiersz będzie zawierał dane o jednym słowie kluczowym. Listę wszystkich typów raportów znajdziesz w sekcji dotyczącej typów raportów.
Aby określić, które kolumny mają się znaleźć w raporcie, nadaj im nazwy w prośbie o raport. Listę kolumn, które można zwrócić w przypadku każdego typu raportu, znajdziesz w dokumentacji typów raportów.
Zachowania kolumn
Sposób działania kolumny zależy od typu zawartych w niej danych (opis działania poszczególnych kolumn znajdziesz w sekcji Typy raportów):
Kolumny atrybutów. Kolumna atrybutu zawiera dane, które służą do konfigurowania lub identyfikowania elementu w kampanii, np. nazwa kampanii czy stawka za słowo kluczowe. Interfejs Search Ads 360 API zawsze zwraca bieżącą wartość w kolumnie atrybutu, niezależnie od daty lub zakresu dat określonych w żądaniu. Jeśli np. wczoraj zmienisz stawkę za słowo kluczowe z 2,00 na 1,50, a potem poprosisz o wygenerowanie raportu z danymi z poprzedniego miesiąca, raport zwróci wartość stawki za słowo kluczowe 1,50.
Kolumny danych. Kolumna danych zawiera dane o skuteczności kampanii, takie jak przychody, liczba kliknięć reklamy i liczba wizyt zarejestrowanych przez tag Floodlight. Jeśli nie określisz zakresu czasu obejmującego jeden dzień, API zwraca wartość zbiorczą dla kolumn danych. Jeśli np. poprosisz o raport z danymi z poprzedniego miesiąca, interfejs API zwróci łączną liczbę kliknięć z ostatniego miesiąca.
Kolumny segmentów. Kolumna segmentu dzieli dane na osobne wiersze.
Na przykład date to kolumna segmentu, którą możesz określić na potrzeby wielu typów raportów. Jeśli w raporcie słów kluczowych określisz kolumnę date z zakresem dat od 1.01.2013 do 7.01.2013 r., interfejs API zwróci 7 wierszy dla każdego słowa kluczowego, z których każdy odpowiada jednemu dzieńowi i wyświetli dane z tego dnia. Zobacz raporty podzielone na segmenty.
Waluty
W żądaniu raportu musisz określić walutę danych pieniężnych (atrybuty takie jak dailyBudget i dane, np. cost). Możesz określić jedną z tych opcji:
- Waluta agencji, jeśli raport jest ograniczony do agencji, reklamodawcy lub konta wyszukiwarki.
- Waluta reklamodawcy, jeśli raport obejmuje reklamodawcę lub konto wyszukiwarki.
- Waluta konta wyszukiwarki, jeśli zakres raportu obejmuje to konto wyszukiwarki.
- USD
Aby określić walutę, użyj właściwości żądania Reports.request.statisticsCurrency.
Sam raport będzie wskazywać walutę we właściwości Reports.statisticsCurrencyCode.
Strefa czasowa
Dane Search Ads 360 są przechowywane w datach bez stref czasowych. Odpowiadają one strefie czasowej konta wyszukiwarki używanej z danymi o wyszukiwarce (kliknięcia, wyświetlenia i wizyty) oraz strefie czasowej sieci Campaign Manager na potrzeby danych o konwersjach (dotyczących np. działań, transakcji i przychodów). Gdy wszystkie dane w raporcie pochodzą z tej samej strefy czasowej, ta strefa czasowa jest zwracana w żądaniu. W przeciwnym razie strefa czasowa nie zostanie zwrócona.
Żądania mogą sprawić, że raporty Reports.request.verifySingleTimeZone: true będą zawierały dane z więcej niż 1 strefy czasowej.
Jeśli wszystkie dane w raporcie pochodzą z jednej strefy czasowej, jest ona zwracana w polu Reports.statisticsTimeZoneReports.
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-08-29 UTC.
[null,null,["Ostatnia aktualizacja: 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)."]]
