Início rápido da API de SERP: sua primeira pesquisa em curl, Python e Node.js

Como faço minha primeira pesquisa com curl?

Exporte a chave uma vez e envie uma requisição GET. A flag -G com --data-urlencode monta a query string e codifica espaços e acentos para você. A resposta é um único documento JSON, e jq o mantém legível no terminal.

O exemplo consulta o Google, o motor padrão, por resultados dos EUA em inglês. Mude q, gl ou hl e rode de novo: cada execução bem-sucedida usa um crédito.

export SERPCRYPTO_API_KEY="paste-your-key-here"

curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=best espresso grinder" \
  -d gl=us -d hl=en | jq '.organic_results[:3]'

Como faço a mesma pesquisa em Python?

Use qualquer cliente HTTP. Com requests, passe os parâmetros como um dicionário e a chave no header. raise_for_status() transforma uma resposta de erro, como 401 para uma chave errada, em uma exceção que você pode capturar.

import os

import requests

API_URL = "https://serpcrypto.com/api/v1/search"
API_KEY = os.environ["SERPCRYPTO_API_KEY"]

response = requests.get(
    API_URL,
    params={"q": "best espresso grinder", "gl": "us", "hl": "en"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

print("credits used:", data["search_metadata"]["credits_used"])
for result in data.get("organic_results", [])[:3]:
    print(result["position"], result["title"], result["link"])

E em Node.js?

O Node.js 18 e posteriores já vêm com fetch, então nenhum pacote é necessário. Salve o arquivo com a extensão .mjs para usar await no nível superior e depois rode node first-search.mjs.

// first-search.mjs (Node.js 18 or later: fetch and top-level await are built in)
const API_URL = "https://serpcrypto.com/api/v1/search";
const params = new URLSearchParams({ q: "best espresso grinder", gl: "us", hl: "en" });

const response = await fetch(`${API_URL}?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPCRYPTO_API_KEY}` },
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const data = await response.json();

console.log("credits used:", data.search_metadata.credits_used);
for (const result of (data.organic_results ?? []).slice(0, 3)) {
  console.log(result.position, result.title, result.link);
}

Como verifico quantos créditos ainda tenho?

Chame GET https://serpcrypto.com/api/v1/credits com a mesma chave. É gratuito e retorna três números: créditos restantes, créditos usados hoje e quantas pesquisas sua conta pode executar ao mesmo tempo. Cada conta pode executar um número definido de pesquisas ao mesmo tempo; o limite é exibido no seu painel e aumentado sob solicitação.

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

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

O que vem de volta em uma pesquisa?

Toda resposta tem a mesma estrutura em todos os engines. search_metadata indica se a pesquisa foi bem-sucedida e quantos créditos ela usou. search_parameters repete as configurações aplicadas, incluindo os padrões. Depois vem um array ou objeto por bloco da página de resultados, como organic_results ou people_also_ask.

Um bloco só aparece quando a página o exibe, então leia-o com um valor padrão. A página do formato de resposta descreve cada bloco e campo.

{
  "search_metadata": { "id": "srch_7f3a9c2e41b8", "status": "success", "engine": "google", "credits_used": 1 },
  "search_parameters": { "engine": "google", "q": "best espresso grinder", "gl": "us", "hl": "en", "page": 1 },
  "search_information": { "total_results": 18600000, "query_displayed": "best espresso grinder" },
  "organic_results": [ { "position": 1, "title": "…", "link": "https://www.example.com/…", "snippet": "…" } ],
  "people_also_ask": [ { "question": "…", "snippet": "…", "link": "https://www.example.org/…" } ],
  "related_searches": [ { "query": "best espresso grinder under 300" } ],
  "pagination": { "current": 1, "next_page": 2 }
}

Quanto custa uma pesquisa e quando ela é gratuita?

1 crédito = 1 solicitação de pesquisa bem-sucedida, que retorna uma página de resultados em qualquer engine compatível. Uma solicitação que falha não é cobrada. 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. Uma requisição rejeitada por parâmetro inválido, chave errada, saldo vazio ou conta ocupada também é gratuita, assim como toda chamada ao endpoint de créditos.

Os preços vão de US$ 7,50 para 10.000 pesquisas até US$ 0,30/1K pesquisas no maior pack, em outubro de 2026. Os créditos de pesquisa pré-pagos nunca expiram: as pesquisas não utilizadas ficam na sua conta até você usá-las. A página de erros lista cada código de erro e a forma correta de tentar novamente.