Amazon Ads Report-Formate: JSON, CSV und Parquet im Vergleich

Kurz gesagt: Amazon Ads Reports werden als Datei in benannten Formaten ausgeliefert. Reporting API v1 und Exports liefern JSON komprimiert in gzip; Amazon nennt das "JSON compressed in gzip format". Reports enthalten Performance-Daten wie Impressionen oder Klicks. Exports enthalten Kampagnen-Metadaten wie Budget oder Status. Amazon Marketing Stream v2 schreibt Parquet nach S3, AMC gibt CSV aus.

Welche Formate Amazon für Reports und Exports nutzt

Die Frage "amazon ads to json" entsteht, weil Werbetreibende eine Datei aus dem Werbekonto ziehen und in ein eigenes System laden wollen. Amazon liefert die Dateien je nach Oberfläche in unterschiedlichen Formaten, und die Antwort hängt davon ab, welche Oberfläche Sie benutzen.

Für Reporting API v1 und die Exports API gilt: Die Datei wird als JSON komprimiert in gzip ausgeliefert. Das gilt für Reports (Performance-Daten) genauso wie für Exports (Kampagnen-Metadaten). Ein Report enthält Kennzahlen wie Impressionen, Klicks oder Conversions, ein Export Metadaten wie Budget oder Status. Amazon empfiehlt, Metadaten über die Export-Ressource anzufordern, weil das die Performance verbessert.

Der Amazon Marketing Stream in Version 2 schreibt keine JSON-Dateien mehr, sondern Apache-Parquet-Dateien in Ihren S3-Bucket. Version 1 des Streams lieferte noch JSON über Firehose oder SQS, wird aber wie die Reporting API v3 und das Version 2 Reporting für Sponsored Ads am 30. Juni 2027 abgeschaltet.

Amazon Marketing Cloud selbst gibt Ergebnisse als CSV aus: Ein Workflow erzeugt eine Datei mit der Endung -ver1.csv und legt sie in Ihren S3-Bucket oder stellt sie über eine Download-URL bereit.

OberflächeDatei-FormatInhalt
Reporting API v1JSON in gzip (GZIP_JSON, auch PARTITIONED_GZIP_JSON)Performance-Daten: Kennzahlen je Dimension
Exports APIJSON in gzipKampagnen-Metadaten wie Budget oder Status
Amazon Marketing Stream v2Apache Parquet in S3Vollständige Datensätze, alle 15 Minuten
Amazon Marketing Stream v1 (alt)JSON über Firehose oder SQSDelta-Meldungen, wird 2027 abgeschaltet
Amazon Marketing CloudCSV (-ver1.csv)SQL-Ergebnis aus Ihrer Abfrage

Die Formate sind kein Zufall: JSON in gzip ist das Austauschformat der Ads API, weil es jede verschachtelte Struktur abbildet und sich gut komprimieren lässt. Parquet ist das Spaltenformat für Daten, die Sie in AWS abfragen wollen, weil es partitioniert und spaltenweise gelesen werden kann. CSV ist das Ergebnisformat von AMC, weil SQL-Ergebnisse tabellarisch sind.

So laden Sie eine Amazon Ads Datei als JSON

Wer die Datei aus der Ads API ziehen will, läuft immer über denselben asynchronen Ablauf: Request stellen, auf Abschluss warten, Download ziehen. Der Unterschied zwischen Report und Export liegt im Inhalt, nicht im Ablauf.

Wann Sie JSON in ein anderes Format umwandeln

Der häufigste Grund für die Suchanfrage ist nicht das Herunterladen, sondern das Weiterverarbeiten: Das Tool am Ende der Kette nimmt CSV oder Parquet, nicht JSON in gzip. Die Umwandlung ist dann ein Schritt in der Pipeline, kein Amazon-Feature.

Zwei Fälle sind typisch. Erstens BI-Tools: Excel, Power BI oder Looker Studio lesen CSV, nicht gzip-JSON. Zweitens AWS-Abfragen: Athena oder Glue lesen Parquet direkt, JSON in gzip aber nur über zusätzliche Schritte. Wer Marketing Stream v2 abonniert, bekommt Parquet und braucht keine Umwandlung für AWS-Queries.

Was Amazon nicht liefert, ist ein Schalter, der Reporting-API-v1-Ergebnisse direkt als CSV oder Parquet ausgibt. Die Formate PARTITIONED_GZIP_JSON und PARTITIONED_CSV der Reporting API v1 teilen nur große Reports in Dateien auf; das Format bleibt JSON in gzip beziehungsweise CSV.

  • **BI-Tool am Ende:** JSON in gzip entpacken, dann in CSV überführen, bevor das Tool die Datei liest.
  • **Athena oder Glue am Ende:** Marketing Stream v2 abonnieren und Parquet direkt abfragen statt JSON zu wandeln.
  • **AMC-Ergebnis am Ende:** Die CSV aus dem Workflow übernehmen, sie liegt schon vor.
  • **Metadaten ergänzen:** Export per ID zum Report joinen, statt beide Daten im Report zu wiederholen.

Checkliste: was vor der Weiterverarbeitung stimmen muss

Bevor die Datei in ein Dashboard oder ein Modell läuft, prüfen Sie vier Punkte. Sie kosten Minuten und verhindern stille Fehler in der Auswertung.

  • **Download-URL:** Sie ist nur eine Stunde gültig; laden Sie die Datei direkt nach dem Abruf und speichern Sie die URL nicht langfristig.
  • **Leere Zeilen:** Ein Report ohne Klicks oder Views kann ein leeres JSON-Array liefern; prüfen Sie das, bevor Sie Nullwerte interpretieren.
  • **Aktualisierung:** Klickdaten sind frühestens nach 12 Stunden da, Conversions können bis zu 60 Tage zurück revidiert werden; rufen Sie Reports monatlich erneut ab.
  • **Gleichzeitigkeit:** Reporting API v1 erlaubt einen Report je Client-ID; verteilen Sie Requests über den Tag, sonst folgt ein 429.

Schritt für Schritt

  1. Report oder Export anfordern. POST auf den Report- bzw. Export-Endpunkt mit den gewünschten Feldern; die Antwort enthält eine reportId oder exportId mit dem Status IN_PROGRESS.
  2. Status abfragen. GET auf den Status-Endpunkt mit der ID, bis der Status COMPLETED lautet. Amazon empfiehlt für Reports etwa einmal pro Minute abzufragen.
  3. Datei herunterladen und entpacken. Die Download-URL ist nur eine Stunde gültig; die Datei ist JSON in gzip und wird mit gunzip entpackt, danach liegt rohes JSON vor.
  4. In das Zielsystem laden. JSON-Zeilen in das Zielsystem laden, Metadaten aus dem Export per ID anreichern und das Datum als eigene Spalte ausgeben, damit sich Zeilen später nicht mehr nach Tag aufteilen lassen.

Häufige Fragen

Liefert Amazon Ads Reports direkt als JSON?

Ja, aber komprimiert: Reports der Reporting API v1 und der Exports API werden als JSON in gzip ausgeliefert. Nach dem Entpacken mit gunzip liegt rohes JSON vor. Ein direkter Download als unkomprimiertes JSON oder als CSV-Schalter existiert für die Reporting API v1 nicht.

Warum liefert der Marketing Stream Parquet statt JSON?

Weil der Stream für Abfragen in AWS gebaut ist: Parquet ist ein spaltenorientiertes Format, das partitioniert und spaltenweise gelesen werden kann. Version 1 des Streams lieferte noch JSON über Firehose oder SQS, Version 2 liefert Parquet nach S3 und wird so dem Use Case Dashboard, Optimierung und Modellierung gerecht.

Sind Reports und Exports dasselbe Format?

Beide werden als JSON in gzip ausgeliefert, aber sie tragen verschiedene Inhalte. Ein Report enthält Performance-Daten wie Impressionen oder Klicks, ein Export Kampagnen-Metadaten wie Budget oder Status. Amazon empfiehlt, Metadaten über die Export-Ressource anzufordern, weil das die Performance verbessert.

Gibt es AMC-Ergebnisse als JSON?

Nein: Amazon Marketing Cloud gibt das Ergebnis einer Abfrage als CSV aus, entweder als -ver1.csv im S3-Bucket oder über eine Download-URL. Wer AMC-Ergebnisse in ein JSON-basiertes System laden will, wandelt die CSV selbst in der Pipeline um.

Wann sollte ich den Marketing Stream statt der Reporting API wählen?

Wenn Sie Rohdaten in eigene Systeme schreiben, Dashboards bauen, Optimierungslogik fahren oder Modelle trainieren wollen, empfiehlt Amazon den Marketing Stream v2: Er liefert Parquet ohne Polling und ohne Drosselung. Für vorbereitete Stakeholder-Reports und periodische Auswertungen ist die Reporting API v1 die passende Oberfläche.

Quellen: Amazon Ads API: Amazon Ads reporting overview · Amazon Ads API: Get started with exports · Amazon Ads API: Amazon Marketing Stream v2 overview · Amazon Ads API: New features of the reporting API v1 · Amazon Ads API: Get your AMC results · Amazon Ads API: Limits and best practices (abgerufen am 2026-11-17)

Weiterlesen: Amazon Ads Reporting · Ergebnisse in Amazon S3 · AMC-Ergebnisse in BI-Werkzeugen