Formati di risposta

Una sola risorsa di ricerca, sei modi di scrivere la risposta. Si sceglie con format=; JSON è il predefinito e quello su cui sono descritti gli altri.

`format`	Content-Type	Struttura
`json`	`application/json`	Un oggetto, con i risultati in un array.
`ndjson`	`application/x-ndjson`	Un oggetto JSON per riga. La prima riga sono i metadati, contrassegnati da `"object":"meta"`.
`xml`	`application/xml`	Lo stesso documento in XML, con le righe come `<result>`.
`csv`	`text/csv`	Separato da punto e virgola, senza riga di intestazione.
`tsv`	`text/tab-separated-values`	Come CSV, separato da tabulazioni.
`txt`	`text/plain`	Un URL per riga.

jsonl è accettato come nome alternativo di ndjson.

Quale usare

json per tutto ciò che sta in memoria. ndjson per tutto ciò che non ci sta: non c'è un array esterno da aspettare, i metadati arrivano prima delle righe e un lettore può iniziare a lavorare sul primo risultato mentre il resto sta ancora arrivando. csv, tsv e txt per fogli di calcolo, pipeline della shell e per spostare uno script dai vecchi URL di esportazione senza cambiarne il parser.

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}

Scegliere le colonne

json e xml restituiscono tutti i campi. I formati piatti invece restituiscono di default quelli già noti, così uno script che arriva dai vecchi URL di esportazione non deve cambiare parser:

Richiesta	Output
`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`	prima una riga `domain;rank`
`format=csv&delimiter=,`	`imgbox.com,4187`

columns funziona con tutti i formati, quindi format=json con columns=domain restituisce oggetti con quel solo campo.

Dettagli dei formati piatti

Un valore viene messo tra virgolette solo quando altrimenti romperebbe la riga, cioè se contiene il delimitatore, una virgoletta o un a capo. Il normale output domain;rank è senza virgolette.
Le virgolette dentro un valore tra virgolette vengono raddoppiate, come prevede il CSV.
Gli snippet, essendo un elenco, vengono uniti con ... in un'unica cella.
Un sito senza posizione ha la cella della posizione vuota: è così che qui si scrive null.
I totali non possono stare in una riga, quindi si trovano negli header X-Total-Results, X-Returned-Results e X-Truncated. Questi vengono inviati con ogni formato.

Queste sono le serializzazioni proprie della nuova API, non una riedizione delle vecchie esportazioni. La struttura è volutamente familiare, ma solo i vecchi URL garantiscono gli stessi identici byte.

Formati ed errori

csv, tsv e txt sono strutture per righe e nient'altro, quindi chiederne uno su /v1/account restituisce 400 format_not_available. Gli errori stessi tornano in JSON, oppure in XML se è stato richiesto quello.

Successivo Quote e limiti di frequenza