Como fazer requisições

/v1/search recebe a mesma consulta que você digitaria na caixa de busca, mais alguns parâmetros. Ele responde a GET e a POST; os parâmetros são os mesmos nos dois casos.

Parâmetros

Nome	Padrão	Significado
`query`	obrigatório	A string de busca. Mesma sintaxe do site; veja sintaxe de consulta.
`page`	1	Começa em 1.
`per_page`	100	Até o limite de linhas do seu plano, assim como `page × per_page`: um plano cobre as primeiras N linhas de uma consulta, e a paginação não vai além delas (`400 page_too_deep`); `/v1/account` informa esse valor como `max_per_page`.
`snippets`	desativado	`1` para incluir o texto correspondente. Consome a cota de trechos.
`format`	`json`	Um de seis; veja formatos de resposta.
`columns`	depende do formato	Subconjunto, separado por vírgulas, de `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / tab	Para `csv` e `tsv`.
`header`	desativado	`1` para incluir uma linha de cabeçalho em `csv` e `tsv`.

GET

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&page=2&per_page=50"

Lembre-se de codificar a consulta para URL. Aspas, barras e + fazem diferença.

POST

Os mesmos parâmetros, como corpo JSON. Use quando a consulta for longa ou tiver várias frases: uma consulta de várias linhas em uma URL esbarra nos limites de tamanho de proxies e clientes muito antes de incomodar o servidor.

curl https://api.publicwww.com/v1/search \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": ["\"angular.min.js\"", "\"bootstrap.min.css\""],
          "per_page": 50,
          "snippets": true}'

Um array de frases significa todas elas, exatamente como se você as separasse com quebras de linha na string query. No exemplo acima, 278 sites contêm a primeira frase e 99 contêm as duas.

Os tipos JSON são reconhecidos: true funciona onde a query string precisa de 1. Quando um parâmetro é informado tanto na URL quanto no corpo, vale o do corpo.

A resposta

Campo	Significado
`total`	Quantos sites correspondem, no índice inteiro. Uma contagem real, não uma estimativa.
`total_pages`	`total` dividido por `per_page`, arredondado para cima.
`returned`	Quantas linhas esta página de fato traz.
`truncated`	Se o limite de posições exibidas do seu plano removeu alguma delas.
`took_ms`	Quanto tempo a busca levou, em milissegundos.
`results`	As linhas.

Uma linha

Campo	Significado
`domain`	O site.
`url`	A página em que a correspondência foi encontrada, que em buscas com `depth:` não é a página inicial.
`rank`	Posição no ranking; quanto menor, mais popular. `null` quando o site não tem posição no ranking.
`ranked`	`false` exatamente quando `rank` é `null`.
`snippets`	Apenas com `snippets=1`. Até cinco pares `{"text", "match"}`, em que `match` é o que correspondeu e `text` é esse mesmo trecho com o contexto ao redor.

Paginação e grandes volumes

Navegue pelas páginas com page ou peça tudo de uma vez com um per_page alto, até o max_per_page informado por /v1/account, que em um plano pago é um milhão. Não há endpoint de exportação separado; a resposta é escrita à medida que é montada, então um milhão de linhas não significa também um milhão de linhas guardadas na memória em algum lugar.

A seguir Formatos de resposta