Docs · Referência da API · versão 1

Referência da API de SERP: GET /search e GET /credits

Q: 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; sua chave continua funcionando e as pesquisas voltam na hora.

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.

Última atualização: 22 de outubro de 2026 · 7 min de leitura

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.
`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`

{
  "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
  }
}

Exemplos de código

curl

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

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

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`

{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}

Exemplos de código

curl

curl -s "https://serpcrypto.com/api/v1/credits" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY"

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

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 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.

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; 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.

Como faço a autenticação?

Executar uma pesquisa

Parâmetros

Resposta 200

Exemplos de código

Quais valores de engine existem e o que cada um retorna?

Ler seus créditos

Resposta 200

Exemplos de código

Quais erros a API pode retornar?

O que é cobrado, exatamente?

Como devo codificar a consulta?

A API tem versionamento?

Perguntas sobre a referência da API

Posso enviar uma requisição POST com corpo JSON?

Quantos resultados uma pesquisa retorna?

O que acontece quando meus créditos acabam?

Posso usar a mesma chave em vários servidores?

Páginas relacionadas

Resposta `200`

Resposta `200`