API

A API executa a mesma busca que o site e devolve os resultados como dados: JSON por padrão, ou XML, CSV, TSV, NDJSON e texto simples. Tudo é leitura: nada aqui cria ou altera coisa alguma.

URL base https://api.publicwww.com

Em um único comando

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&per_page=3"
{
  "query": "\"angular.min.js\"",
  "page": 1,
  "per_page": 3,
  "total": 278,
  "total_pages": 93,
  "returned": 3,
  "truncated": false,
  "took_ms": 2,
  "results": [
    { "domain": "imgbox.com", "url": "https://imgbox.com/", "rank": 4187, "ranked": true }
  ]
}

Endpoints

EndpointMétodosO que faz
/v1/search GET, POST Executa uma busca. Parâmetros, formatos.
/v1/account GET Plano, cota e limites. Não consome nada.
/mcp POST O servidor MCP para assistentes e agentes de IA: a mesma busca como ferramenta, com o mesmo token.
/ GET A API descrevendo a si mesma, incluindo os códigos de erro. Não exige chave.
/openapi.json GET O mesmo como descrição OpenAPI 3.1, para importar no Postman, n8n, Make, Power Automate e outras ferramentas. Não exige chave.

Não há endpoint de exportação separado. Para grandes volumes, use /v1/search com um per_page alto, que em um plano pago chega a um milhão de linhas; a resposta é transmitida à medida que é gerada.

O que a API garante

  • Os resultados nunca são reduzidos em silêncio. Quando a cota diária de um navegador acaba, o site volta discretamente aos limites do plano gratuito e mostra menos. Um script não consegue perceber isso, então aqui isso é um erro, 429 quota_exceeded, e não uma resposta curta que parece completa.
  • Uma resposta encurtada vem marcada como tal: truncated no corpo e X-Truncated nos cabeçalhos, em todos os formatos.
  • Sites sem posição no ranking dizem isso: rank: null e ranked: false, nunca um valor interno provisório que um cliente possa confundir com uma posição real muito alta.
  • Ser avisado para esperar é melhor do que ser forçado a esperar. Se as requisições chegarem rápido demais, a resposta volta na hora com um Retry-After, em vez de a conexão ficar presa.

Como obter uma chave

Gere um token no seu perfil ou deixe que um aplicativo obtenha um para você via OAuth 2.1. É preciso ter um plano pago; veja os preços. Scripts existentes que chamam as URLs antigas com ?export= continuam funcionando sem mudanças; veja as URLs de exportação antigas.

A seguir Autenticação