# Referência da API de SERP: GET /search e GET /credits > Referência da API de SERP do SerpCrypto: parâmetros do GET /search, engines, padrões, resposta e códigos de erro, com curl, Python e Node.js. - URL: https://serpcrypto.com/pt/docs/search/ - Última atualização: 2026-10-22 - Editor: SerpCrypto (https://serpcrypto.com) Todos os parâmetros, padrões e códigos de erro da API SerpCrypto, versão 1. URL base: `https://serpcrypto.com/api/v1`. Todas as requisições usam HTTPS; todas as respostas são JSON em UTF-8. **Resposta rápida — Quais parâmetros o endpoint de pesquisa do SerpCrypto aceita?** `GET https://serpcrypto.com/api/v1/search` aceita um parâmetro obrigatório, `q`, e nove opcionais: `engine`, `gl`, `hl`, `location`, `google_domain`, `device`, `page`, `safe` e `period`. **SerpCrypto** retorna JSON e cobra 1 crédito por pesquisa bem-sucedida em todas as 6 engines; erros são gratuitos. Os pacotes começam a partir de US$ 7,50 por 10.000 pesquisas, pagos com cripto e sem KYC. ## Como faço a autenticação? Envie sua chave de uma das duas formas. A recomendada é o header `Authorization: Bearer YOUR_KEY`. A outra é o parâmetro de consulta `api_key=YOUR_KEY`, prático para um teste rápido em uma aba do navegador. Uma chave ausente, errada ou revogada retorna `401 invalid_api_key` e não custa nada. Chaves de API que você pode criar e revogar a qualquer momento no seu painel, assim você pode dar a cada script ou servidor sua própria chave e revogar uma sem mexer nas outras. ## Executar uma pesquisa `GET /api/v1/search` Executa uma pesquisa na engine escolhida e retorna a página de resultados em JSON. Uma pesquisa bem-sucedida usa 1 crédito, qualquer que seja a engine; um erro não usa nenhum. Os parâmetros vão na query string, com URL encoding. O exemplo pede ao Google por torrefações de café em Austin, Texas; IDs, contagens e resultados são ilustrativos. Autenticação: chave de API no header `Authorization: Bearer API_KEY`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `q` | query | string | Sim | A consulta de pesquisa, como uma pessoa digitaria. Operadores de pesquisa como aspas ou `site:` fazem parte da consulta. | | `engine` | query | string | Não | `google` (padrão), `google_news`, `google_images`, `google_maps`, `google_shopping` ou `bing`. | | `gl` | query | string | Não | País dos resultados: código ISO 3166-1 alpha-2 em minúsculas, como `us`, `de` ou `br`. Padrão `us`. | | `hl` | query | string | Não | Idioma da interface, como `en`, `de` ou `pt-BR`. Padrão `en`. | | `location` | query | string | Não | Local no nível de cidade, escrito `City, Region, Country`, como `Austin, Texas, United States`. Veja [locations](https://serpcrypto.com/pt/docs/locations/). | | `google_domain` | query | string | Não | Domínio do Google a pesquisar, como `google.de`. Padrão: o domínio do país `gl`. Ignorado quando `engine=bing`. | | `device` | query | string | Não | `desktop` (padrão) ou `mobile`. | | `page` | query | integer | Não | Página de resultados de 1 (padrão) a 10. Cada página é uma pesquisa separada e usa 1 crédito. | | `safe` | query | string | Não | `active` filtra resultados explícitos; `off` (padrão) não filtra. | | `period` | query | string | Não | Apenas resultados da última hora (`h`), dia (`d`), semana (`w`), mês (`m`) ou ano (`y`). | | `api_key` | query | string | Não | Sua chave, caso você não envie o header `Authorization`. | **Resposta** `200` ```json { "search_metadata": { "id": "srch_7f3a9c2e41b8", "status": "success", "engine": "google", "created_at": "2026-10-22T09:14:05Z", "credits_used": 1 }, "search_parameters": { "engine": "google", "q": "coffee roasters", "gl": "us", "hl": "en", "location": "Austin, Texas, United States", "google_domain": "google.com", "device": "desktop", "page": 1 }, "search_information": { "total_results": 18600000, "query_displayed": "coffee roasters" }, "local_results": [ { "position": 1, "title": "Example Coffee Roasters", "address": "123 Example St, Austin, TX", "rating": 4.7, "reviews": 312, "type": "Coffee roasters" } ], "organic_results": [ { "position": 1, "title": "The 12 best coffee roasters in Austin", "link": "https://www.example.com/austin/coffee-roasters", "displayed_link": "www.example.com › austin › coffee", "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…", "date": "Sep 30, 2026" }, { "position": 2, "title": "Example Roasting Co. | Fresh beans, roasted in Austin", "link": "https://www.example.org/", "displayed_link": "www.example.org", "snippet": "Small-batch coffee roasted every weekday and shipped the same day…" } ], "people_also_ask": [ { "question": "What is the oldest coffee roaster in Austin?", "snippet": "…", "title": "Austin coffee history", "link": "https://www.example.net/austin-coffee-history" } ], "related_searches": [ { "query": "coffee roasters near me" }, { "query": "coffee roasters austin wholesale" } ], "pagination": { "current": 1, "next_page": 2 } } ``` *curl* ```bash curl -sG "https://serpcrypto.com/api/v1/search" \ -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \ --data-urlencode "q=coffee roasters" \ --data-urlencode "location=Austin, Texas, United States" \ -d gl=us -d hl=en -d device=desktop ``` *Python* ```python import os import requests r = requests.get( "https://serpcrypto.com/api/v1/search", params={ "q": "coffee roasters", "location": "Austin, Texas, United States", "gl": "us", "hl": "en", }, headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}, timeout=60, ) r.raise_for_status() print(r.json()["organic_results"][0]["link"]) ``` *Node.js* ```javascript const params = new URLSearchParams({ q: "coffee roasters", location: "Austin, Texas, United States", gl: "us", hl: "en", }); const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, { headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY }, }); const data = await res.json(); console.log(data.organic_results?.[0]?.link); ``` ## Quais valores de engine existem e o que cada um retorna? O frame (`search_metadata`, `search_parameters`, `search_information`) é o mesmo em todas as engines. Um bloco aparece apenas quando a página o exibe. | `engine` | Fonte | Blocos principais na resposta | | --- | --- | --- | | `google` | Google Search | `ai_overview`, `organic_results`, `ads`, `people_also_ask`, `local_results`, `knowledge_graph`, `top_stories`, `inline_videos`, `shopping_results`, `related_searches`, `pagination` | | `google_news` | Google News | `news_results`: título, link, fonte, data, snippet, thumbnail | | `google_images` | Google Images | `images_results`: URL original e tamanho, thumbnail, página de origem | | `google_maps` | Google Maps | `local_results`: nome, endereço, telefone, site, avaliação, avaliações, categoria, horário, coordenadas | | `google_shopping` | Google Shopping | `shopping_results`: título, preço, preço extraído, moeda, loja, entrega, avaliação | | `bing` | Bing | `organic_results`, `related_searches` | ## Ler seus créditos `GET /api/v1/credits` Retorna os créditos restantes na sua conta, os créditos usados desde a meia-noite UTC e o número de pesquisas que sua conta pode executar ao mesmo tempo. Esta chamada é gratuita. Os valores abaixo são exemplos. Autenticação: chave de API no header `Authorization: Bearer API_KEY`. **Resposta** `200` ```json { "credits_remaining": 84210, "credits_used_today": 1290, "concurrency_limit": 10 } ``` *curl* ```bash curl -s "https://serpcrypto.com/api/v1/credits" \ -H "Authorization: Bearer $SERPCRYPTO_API_KEY" ``` *Python* ```python import os import requests r = requests.get( "https://serpcrypto.com/api/v1/credits", headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}, timeout=30, ) r.raise_for_status() print(r.json()["credits_remaining"]) ``` *Node.js* ```javascript const res = await fetch("https://serpcrypto.com/api/v1/credits", { headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY }, }); const { credits_remaining } = await res.json(); console.log(credits_remaining); ``` ## Quais erros a API pode retornar? Todo erro tem o corpo `{"error": {"code": "…", "message": "…"}}`. A [página de erros](https://serpcrypto.com/pt/docs/errors/) explica cada um e mostra o código de repetição. | HTTP | `code` | Quando acontece | Cobrado | | --- | --- | --- | --- | | 400 | `invalid_parameter` | Um parâmetro obrigatório está faltando ou um valor está fora da lista permitida | Não | | 401 | `invalid_api_key` | A chave está faltando, errada ou foi revogada | Não | | 402 | `insufficient_credits` | Sua conta não tem mais créditos | Não | | 429 | `concurrency_limit` | Muitas pesquisas estão em execução ao mesmo tempo na sua conta | Não | | 502 | `search_failed` | A engine ou a coleta falhou nesta requisição; tente novamente | Não | | 504 | `search_timeout` | Sem resposta a tempo; tente novamente | Não | ## O que é cobrado, exatamente? - **Uma pesquisa bem-sucedida = um crédito**, em todas as engines, incluindo Google Maps e Google Shopping. - **Cada página de resultados é uma pesquisa.** Cerca de 10 resultados orgânicos por página, como o Google vem entregando desde que deixou de respeitar num=100 em setembro de 2025; cada página extra é mais um crédito. - **Erros são gratuitos:** toda resposta com status HTTP diferente de 200 não usa crédito. - **Ler seus créditos é gratuito.** Os créditos de pesquisa pré-pagos nunca expiram: as pesquisas não utilizadas ficam na sua conta até você usá-las. Os packs vão de US$ 7,50 por 10.000 pesquisas a US$ 0,30/1K pesquisas no maior deles; veja [preços](https://serpcrypto.com/pt/pricing/). ## Como devo codificar a consulta? Envie `q` codificado para URL, como qualquer valor de query string: um espaço vira `%20` ou `+`, e letras acentuadas são codificadas em UTF-8. O curl faz isso com `--data-urlencode`, Python `requests` e `httpx` fazem com `params=`, e o Node.js faz com `URLSearchParams`. Escreva a consulta exatamente como uma pessoa digitaria na caixa de pesquisa. Aspas, sinal de menos ou `site:` ficam dentro de `q`; a engine decide como aplicá-los, como faria para um visitante. ## A API tem versionamento? Sim. A versão faz parte do caminho: `/api/v1/`. Novos campos ou blocos podem aparecer em respostas da versão 1, então seu código deve ignorar chaves que não conhece. Remover ou renomear um campo viria com uma nova versão no caminho, não como uma mudança em `v1`. ## Perguntas sobre a referência da API ### Posso enviar uma requisição POST com corpo JSON? Na versão 1, não: os dois endpoints recebem requisições GET com os parâmetros na query string. Isso mantém cada chamada fácil de reproduzir com curl ou no navegador, e fácil de registrar em log sem o corpo. ### Quantos resultados uma pesquisa retorna? Cerca de 10 resultados orgânicos por página, como o Google vem entregando desde que deixou de respeitar num=100 em setembro de 2025; cada página extra é mais um crédito. Para coletar 30 resultados, solicite `page=1`, `page=2` e `page=3`: três pesquisas, três créditos. ### O que acontece quando meus créditos acabam? A próxima pesquisa retorna `402 insufficient_credits` e não consome nada. Compre outro pacote com seu saldo na [página de preços](https://serpcrypto.com/pt/pricing/); sua chave continua funcionando e as pesquisas voltam na hora. ### Posso usar a mesma chave em vários servidores? Sim. Uma chave não está vinculada a um endereço IP. O que é limitado é o número de pesquisas rodando ao mesmo tempo na conta: `concurrency_limit` em `GET /credits` traz o número. --- SerpCrypto: O SerpCrypto é uma API de SERP para desenvolvedores e agentes de IA que retorna resultados de pesquisa do Google e do Bing em JSON, pago com cripto e sem envio de documento de identidade. Os créditos de pesquisa pré-pagos a partir de US$ 0,30/1K pesquisas nunca expiram. Sem KYC — sem documento, sem selfie, sem documentos. Pague com cripto.