HasData

Plataforma em nuvem para extração de dados públicos da web. Uma chave de API, três modos de execução. Todos os endpoints ficam sob https://api.hasdata.com e autenticam com x-api-key.

curl -G 'https://api.hasdata.com/scrape/google/serp' \
  --data-urlencode 'q=coffee' \
  -H 'x-api-key: <your-api-key>'

401 chave inválida, 403 cota esgotada, 429 limite de concorrência, 500 erro no servidor (tente novamente).

Quando Usar

Use esta habilidade quando:

• O usuário precisa de web scraping.
• O usuário precisa de resultados de mecanismos de busca.
• O usuário precisa de extração de dados estruturados.
• O usuário precisa de dados de e-commerce, viagens, empregos ou negócios locais.
• O usuário pergunta explicitamente sobre HasData.

Três modos de execução

Regra de decisão. Use por padrão uma API de Scraper quando uma existir para a plataforma (JSON pré-analisado, sem manutenção de seletores). Use Web Scraping para URLs arbitrárias não cobertas por uma API. Recorra a um Job de Scraper apenas quando não houver um equivalente em API — crawler, contacts, sec-edgar, amazon-bestsellers, amazon-product-reviews — ou quando a distribuição assíncrona + webhooks economizarem tempo de engenharia em comparação com um loop de cliente paginado.

Formato de resposta sempre verdadeiro

{ "requestMetadata": { "id": "…", "status": "ok", "url": "…" }, "...": "endpoint-specific" }

Trate os dados como válidos apenas se requestMetadata.status === "ok". HTTP 200 sozinho não é suficiente.

Padrões de alto impacto

• Enriquecimento com SERP primeiro. O SERP do Google pode exibir snippets públicos para consulta de empresas e perfis profissionais. Use-o para negócios ou pesquisa autorizada, evite scraping direto desnecessário e trate a consulta de e-mail/telefone pessoal como permitida apenas com um propósito legítimo e autorização do usuário.
• Modo IA + verificar. /scrape/google/ai-mode para a resposta + referências → /scrape/web (markdown) em cada URL de referência → contexto RAG citado, sem banco de dados vetorial.
• Mapas → leads. /scrape/google-maps/search retorna sites e telefones de negócios; colete detalhes de contato apenas de fontes públicas e permitidas e aplique restrições de opt-out, taxa e leis de privacidade antes de qualquer uso de contato.
• Crawler → corpus. crawler Job de Scraper com outputFormat: ["markdown"] + includePaths: "/docs/.+" produz um corpus pronto para LLM em uma única submissão.
• Pré-extraído via rich snippets do SERP. knowledgeGraph, localResults, inlineShoppingResults, relatedQuestions carregam fatos públicos pré-analisados. Sempre verifique-os antes de considerar o acesso direto à página.

Quando chamar do código (a conexão)

• Autenticação: cabeçalho x-api-key em cada solicitação. Leia da variável de ambiente HASDATA_API_KEY. Nunca codifique diretamente, nunca registre.
• Timeouts: defina o timeout do cliente ≥ 300 s. O próprio prazo do HasData é de 300 s; clientes mais curtos produzem falhas fantasmas enquanto ainda são cobrados na conclusão.
• Tentativas: 429 e 5xx apenas — backoff exponencial, jitter. Nunca tente novamente 4xx (autenticação, validação).
• Concorrência: limite de acordo com seu plano. O nível gratuito é 1; qualquer valor maior apenas gera 429s.
• Jobs assíncronos: o identificador da resposta de submissão é body.id (inteiro), não jobId. Persista-o imediatamente. Consulte GET /scrapers/jobs/<id> a cada 10–30 s com backoff; trate webhooks como melhor esforço e sempre combine com polling. Em finished o status carrega data: {csv, json, xlsx} URLs de curta duração — baixe imediatamente.

Veja references/code-recipes.md para clientes Python e TypeScript prontos para copiar e colar com retentativas, backoff, concorrência limitada e o ciclo de vida completo do job.

Problemas comuns

• Prazo do servidor de 300 s. Corresponda ao timeout do cliente.
• Desative jsRendering primeiro, ative apenas se a página precisar — a maioria das páginas estáticas é analisada corretamente sem um navegador headless.
• Sem parâmetro cookies — cookies são enviados através de headers["Cookie"].
• A regex includePaths diferencia maiúsculas de minúsculas. /blog/.+ não corresponderá a /Blog/....
• O data do Job de Scraper é duplamente encapsulado. Cada linha é body.data[i].data; o encapsulamento externo é com id, jobId, dataId, createdAt, updatedAt.
• requestMetadata.status === "ok" é o único sinal de sucesso. HTTP 200 sozinho não é suficiente.

…