Antwortformate

Eine Suchressource, sechs Schreibweisen der Antwort. Die Auswahl erfolgt mit format=; JSON ist der Standard und die Referenz, anhand derer die anderen beschrieben werden.

`format`	Content-Type	Aufbau
`json`	`application/json`	Ein Objekt, Ergebnisse in einem Array.
`ndjson`	`application/x-ndjson`	Ein JSON-Objekt pro Zeile. Die erste Zeile enthält die Metadaten, markiert mit `"object":"meta"`.
`xml`	`application/xml`	Dasselbe Dokument als XML, Zeilen als `<result>`.
`csv`	`text/csv`	Durch Semikolon getrennt, ohne Kopfzeile.
`tsv`	`text/tab-separated-values`	Wie CSV, durch Tabulator getrennt.
`txt`	`text/plain`	Eine URL pro Zeile.

jsonl wird als weiterer Name für ndjson akzeptiert.

Welches Format wofür

json für alles, was in den Speicher passt. ndjson für alles andere: Es gibt kein umschließendes Array, auf das man warten müsste, die Metadaten kommen vor den Zeilen, und ein Leser kann mit dem ersten Ergebnis arbeiten, während der Rest noch eintrifft. csv, tsv und txt für Tabellenkalkulationen, Shell-Pipelines und um ein Skript von den alten Export-URLs umzustellen, ohne seinen Parser zu ändern.

ndjson

{"object":"meta","query":"\"angular.min.js\"","page":1,"per_page":2,"total":278,"total_pages":139,"returned":2,"truncated":false,"took_ms":2}
{"domain":"imgbox.com","url":"https://imgbox.com/","rank":4187,"ranked":true}
{"domain":"angularjs.org","url":"https://angularjs.org/","rank":12376,"ranked":true}

Spalten auswählen

json und xml liefern alle Felder. Die flachen Formate liefern stattdessen standardmäßig die gewohnten Felder, sodass ein Skript, das von den alten Export-URLs kommt, keine Parser-Änderung braucht:

Anfrage	Ausgabe
`format=csv`	`imgbox.com;4187`
`format=csv&columns=url,rank`	`https://imgbox.com/;4187`
`format=csv&columns=domain`	`imgbox.com`
`format=txt`	`https://imgbox.com/`
`format=csv&snippets=1`	`imgbox.com;4187;the matching text`
`format=csv&header=1`	zuerst eine Zeile `domain;rank`
`format=csv&delimiter=,`	`imgbox.com,4187`

columns funktioniert mit jedem Format, daher liefert format=json mit columns=domain Objekte, die nur dieses Feld enthalten.

Details der flachen Formate

Ein Wert wird nur dann in Anführungszeichen gesetzt, wenn er die Zeile sonst zerstören würde - wenn er das Trennzeichen, ein Anführungszeichen oder einen Zeilenumbruch enthält. Gewöhnliche domain;rank-Ausgabe bleibt ohne.
Anführungszeichen innerhalb eines Werts in Anführungszeichen werden verdoppelt, wie CSV es erwartet.
Code-Schnipsel sind eine Liste und werden daher mit ... zu einer Zelle verbunden.
Eine Website ohne Rang hat eine leere Rang-Zelle - so schreibt sich null hier.
Die Gesamtzahlen passen in keine Zeile, daher stehen sie stattdessen in den Headern X-Total-Results, X-Returned-Results und X-Truncated. Diese werden bei jedem Format gesendet.

Dies sind eigene Serialisierungen der neuen API, keine Neuauflage der alten Exporte. Der Aufbau ist bewusst vertraut, aber nur die alten URLs garantieren byte-genau dieselbe Ausgabe.

Formate und Fehler

csv, tsv und txt sind Formen für Zeilen und nichts anderes, daher führt eine Anfrage danach an /v1/account zu 400 format_not_available. Fehler selbst kommen als JSON zurück - oder als XML, wenn dies angefordert wurde.

Weiter Kontingente und Ratenlimits