Formatos de resposta

Um recurso de busca, seis formas de escrever a resposta. Escolha com format=; JSON é o padrão e a referência com base na qual os outros são descritos.

`format`	Content-Type	Estrutura
`json`	`application/json`	Um objeto, com os resultados em um array.
`ndjson`	`application/x-ndjson`	Um objeto JSON por linha. A primeira linha são os metadados, marcados com `"object":"meta"`.
`xml`	`application/xml`	O mesmo documento em XML, com as linhas como `<result>`.
`csv`	`text/csv`	Separado por ponto e vírgula, sem linha de cabeçalho.
`tsv`	`text/tab-separated-values`	Como o CSV, separado por tabulação.
`txt`	`text/plain`	Uma URL por linha.

jsonl é aceito como outro nome para ndjson.

Qual usar

json para tudo o que cabe na memória. ndjson para o que não cabe: não há array externo pelo qual esperar, os metadados chegam antes das linhas, e quem lê pode começar a processar o primeiro resultado enquanto o restante ainda está chegando. csv, tsv e txt para planilhas, pipelines de shell e para migrar um script das URLs de exportação antigas sem mudar o 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}

Como escolher as colunas

json e xml retornam todos os campos. Já os formatos planos usam por padrão as colunas conhecidas, para que um script vindo das URLs de exportação antigas não precise mudar o parser:

Requisição	Saída
`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`	primeiro, uma linha `domain;rank`
`format=csv&delimiter=,`	`imgbox.com,4187`

columns funciona em todos os formatos, então format=json com columns=domain retorna objetos só com esse campo.

Detalhes dos formatos planos

Um valor só vai entre aspas quando, sem elas, quebraria a linha: quando contém o delimitador, aspas ou uma quebra de linha. A saída comum domain;rank vem sem aspas.
Aspas dentro de um valor entre aspas são duplicadas, como o CSV exige.
Os trechos, por serem uma lista, são unidos com ... em uma única célula.
Um site sem posição no ranking tem a célula de rank vazia, que é como null se escreve aqui.
Os totais não cabem em uma linha, então ficam nos cabeçalhos X-Total-Results, X-Returned-Results e X-Truncated. Eles são enviados em todos os formatos.

Estas são serializações próprias da nova API, não uma reedição das exportações antigas. A estrutura é familiar de propósito, mas só as URLs antigas garantem exatamente os mesmos bytes.

Formatos e erros

csv, tsv e txt são formatos para linhas e nada mais, então pedir um deles em /v1/account resulta em 400 format_not_available. Os próprios erros voltam em JSON, ou em XML se for isso o que foi pedido.

A seguir Cotas e limite de requisições