Formats de réponse

Une seule ressource de recherche, six façons d’écrire la réponse. Choisissez avec format= ; JSON est le format par défaut et celui qui sert de référence pour décrire les autres.

`format`	Content-Type	Structure
`json`	`application/json`	Un seul objet, les résultats dans un tableau.
`ndjson`	`application/x-ndjson`	Un objet JSON par ligne. La première ligne contient les métadonnées, marquées `"object":"meta"`.
`xml`	`application/xml`	Le même document en XML, chaque ligne sous forme de `<result>`.
`csv`	`text/csv`	Séparé par des points-virgules, sans ligne d’en-tête.
`tsv`	`text/tab-separated-values`	Comme CSV, séparé par des tabulations.
`txt`	`text/plain`	Une URL par ligne.

jsonl est accepté comme autre nom de ndjson.

Lequel choisir

json pour tout ce qui tient en mémoire. ndjson pour tout le reste : il n’y a pas de tableau englobant à attendre, les métadonnées arrivent avant les lignes, et un lecteur peut commencer à traiter le premier résultat pendant que la suite arrive. csv, tsv et txt pour les tableurs, les pipelines shell, et pour migrer un script depuis les anciennes URL d’export sans modifier son analyseur.

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}

Choisir les colonnes

json et xml renvoient tous les champs. Les formats plats s’en tiennent par défaut aux colonnes habituelles, si bien qu’un script venant des anciennes URL d’export n’a pas besoin de modifier son analyseur :

Requête	Résultat
`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`	d’abord une ligne `domain;rank`
`format=csv&delimiter=,`	`imgbox.com,4187`

columns fonctionne avec tous les formats : format=json avec columns=domain renvoie des objets ne contenant que ce champ.

Détails des formats plats

Une valeur n’est mise entre guillemets que si elle casserait sinon la ligne - lorsqu’elle contient le délimiteur, un guillemet ou un saut de ligne. Une sortie domain;rank ordinaire n’en a pas.
Les guillemets à l’intérieur d’une valeur entre guillemets sont doublés, comme le veut le CSV.
Les extraits, qui forment une liste, sont réunis dans une seule cellule avec ....
Un site sans rang a une cellule de rang vide : c’est ainsi que null s’écrit ici.
Les totaux ne tiennent pas dans une ligne : ils figurent donc dans les en-têtes X-Total-Results, X-Returned-Results et X-Truncated. Ces en-têtes sont envoyés quel que soit le format.

Ce sont les sérialisations propres à la nouvelle API, pas une réédition des anciens exports. La structure est volontairement familière, mais seules les anciennes URL garantissent un résultat identique à l’octet près.

Formats et erreurs

csv, tsv et txt sont des structures destinées aux lignes de résultats et à rien d’autre : en demander un sur /v1/account renvoie donc 400 format_not_available. Les erreurs elles-mêmes sont renvoyées en JSON, ou en XML si c’est ce qui a été demandé.

Suivant Quotas et limites de débit