Berichte anfordern
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Nachdem Sie Ihre Client-App wie unter Meine erste App beschrieben eingerichtet haben, können Sie mit der Search Ads 360 API Berichte anfordern und herunterladen. Sie können eine der folgenden Arten von Anfragen stellen:
- Synchron
Erfordert nur eine einzelne Anfrage und gibt den Bericht in einer JSON-formatierten Antwort zurück. Synchrone Anfragen:
- Es können nur Berichte zu Werbetreibenden und Engine-Konten zurückgegeben werden.
- Kunden blockieren, bis Search Ads 360 den Bericht erstellt hat
Wenn Sie umfangreiche Berichte für Werbetreibende oder Engine-Konten anfordern, empfehlen wir den asynchronen Ansatz.
- Asynchron
Bei dieser Funktion müssen Sie eine erste Anfrage mit den gewünschten Daten für den Bericht senden. Dann senden Sie zusätzliche Anfragen, um Search Ads 360 abzufragen. Wenn Search Ads 360 den Bericht erstellt hat, senden Sie Anfragen zum Herunterladen des Berichts in Form einer oder mehrerer Dateien. Asynchrone Anfragen:
- Es kann jeder Berichtstyp zurückgegeben werden.
- Teilt sehr große Berichte in mehrere Dateien auf
- Formatiert Berichte als CSV oder TSV
Datenmodell: Zeilen und Spalten
Search Ads 360 organisiert Daten in einem Bericht in Zeilen und Spalten.
Welche Zeilen zurückgegeben werden, hängt vom Typ des angeforderten Berichts ab.
Wenn Sie beispielsweise einen Keyword-Bericht anfordern, enthält jede Zeile Daten zu einem einzelnen Keyword. In der Referenz zu Berichtstypen finden Sie eine Liste aller Berichtstypen.
Sie geben an, welche Spalten der Bericht enthalten soll, indem Sie jede Spalte in Ihrer Berichtsanfrage benennen. In der Referenz zu Berichtstypen finden Sie eine Liste der Spalten, die für jeden Berichtstyp zurückgegeben werden können.
Spaltenverhalten
Das Verhalten einer Spalte hängt vom Typ der Daten in der Spalte ab. In der Referenz zu Berichtstypen wird das Verhalten der einzelnen Spalten angezeigt:
Attributspalten: Eine Attributspalte enthält Daten, die eine Entität in einer Kampagne konfigurieren oder identifizieren, z. B. den Kampagnennamen oder ein Keyword-Gebot. Die Search Ads 360 API gibt immer den aktuellen Wert für eine Attributspalte zurück, unabhängig von dem in der Anfrage angegebenen Datum oder Zeitraum. Wenn Sie beispielsweise das Gebot für ein Keyword von 2,00 in 1,50 gestern geändert haben und dann einen Bericht mit den Daten des letzten Monats anfordern, gibt der Bericht für das Keyword-Gebot den Wert 1,50 zurück.
Spalten mit Messwerten: Eine Messwertspalte enthält Daten zur Leistung Ihrer Kampagne, beispielsweise die Anzahl der Klicks auf eine Anzeige, die Anzahl der von einem Floodlight-Tag erfassten Besuche oder der Umsatz. Sofern Sie keinen Zeitraum eines einzelnen Tages angeben, gibt die API einen aggregierten Wert für Messwertspalten zurück. Wenn Sie beispielsweise einen Bericht für die Daten des letzten Monats anfordern, gibt die API die Gesamtzahl der Klicks für den letzten Monat zurück.
Segmentspalten: Eine Segmentspalte teilt Daten in separate Zeilen auf.
Beispielsweise ist date eine Segmentspalte, die Sie für viele Arten von Berichten angeben können. Wenn Sie die Spalte date in einem Keyword-Bericht mit dem Zeitraum 2013-01-01 bis 2013-01-07 angeben, gibt die API sieben Zeilen für jedes Keyword zurück, die jeweils einem Tag entsprechen und Messwerte für diesen Tag anzeigen. Siehe Segmentierte Berichte.
Währungen
In Ihrer Berichtsanfrage muss die Währung der monetären Daten (Attribute wie dailyBudget und Messwerte wie cost) angegeben werden. Sie können eine der folgenden Optionen angeben:
- Die Währung der Agentur, wenn der Bericht einer Agentur, einem Werbetreibenden oder einem Engine-Konto zugewiesen ist.
- Die Währung des Werbetreibenden, wenn der Bericht einem Werbetreibenden oder Engine-Konto zugeordnet ist.
- Die Währung des Engine-Kontos, wenn der Bericht einem Engine-Konto zugeordnet ist.
- USD
Verwenden Sie das Anfrageattribut Reports.request.statisticsCurrency, um eine Währung anzugeben.
Im Bericht selbst wird die Währung in der Reports.statisticsCurrencyCode-Property angezeigt.
Zeitzone
Search Ads 360-Messwerte werden in Datumsangaben ohne Zeitzonen gespeichert. Diese Datumsangaben entsprechen der Zeitzone des Engine-Kontos für Engine-Messwerte (z. B. Klicks, Impressionen und Besuche) und der Zeitzone des Campaign Manager-Netzwerks für Conversion-Messwerte (z. B. Aktionen, Transaktionen und Umsatz). Wenn jeder Messwert in einem Bericht aus derselben Zeitzone stammt, wird diese Zeitzone in der Anfrage zurückgegeben. Andernfalls wird keine Zeitzone zurückgegeben.
Durch Ihre Anfragen können Sie festlegen, dass für Reports.request.verifySingleTimeZone: true keine Berichte erstellt werden, die Messwerte aus mehreren Zeitzonen enthalten.
Wenn alle in einem Bericht enthaltenen Messwerte aus einer Zeitzone stammen, wird diese Zeitzone in Reports.statisticsTimeZoneReports zurückgegeben.
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-29 (UTC).
[null,null,["Zuletzt aktualisiert: 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)."]]
