Em resumo: a Custom Search JSON API da Google está fechada a novos clientes e encerra para utilizadores existentes a 1 de janeiro de 2027. Se a sua app ou pipeline envia uma query e lê resultados Google em JSON da web inteira, Google Search na Piloterr mantém o padrão: query in, SERP estruturada out. A maioria dos filtros gl / hl / lr mapeia 1:1. Para cargas SERP-only em volume, a mesma equipa oferece Autom.dev, uma API SERP dedicada com o mesmo estilo de parâmetros.
Migrar são poucas linhas, não um rewrite.
O que está a ser desligado
A Google indica na overview da Custom Search JSON API:
- A API não está disponível para novos clientes.
- Clientes existentes podem usá-la até 1 de janeiro de 2027.
- Até lá, o preço mantém-se: 100 queries grátis por dia, depois 5 $ por 1.000 queries, com teto de 10k queries por dia.
Para pesquisar até cerca de 50 domínios, a Google aponta para Vertex AI Search (por vezes Agent Search). Para resultados da web inteira, não há produto self-serve da Google, só um formulário de interesse.
Fonte: Google for Developers: Custom Search JSON API.
Escolha o substituto conforme o que pesquisa de verdade
Custom Search cobria vários trabalhos. Não partilham o mesmo sucessor.
| Para que usa Custom Search | O que usar em vez disso |
|---|---|
| Caixa de pesquisa no seu próprio site | Programmable Search Element da Google, ou site search (Algolia, Typesense, Meilisearch) |
| Conjunto de domínios ou o seu corpus no Google Cloud | Google Agent Search / Vertex AI Search (caminho «~50 domínios») |
| Resultados da web inteira em JSON para app, agente ou pipeline | Google Search na Piloterr, ou Autom.dev se só precisa de SERP |
| Respostas geradas com citações (Google AI Mode) | Google AI Mode, opcionalmente com pesquisa orgânica |
| SEO SERP profundo (ads, AI Overviews, muitas páginas) | Google Search com paginação page, mais Images / Autocomplete se precisar |
| O mesmo padrão de query em Bing, Brave, Yahoo, DuckDuckGo (ou failover multi-motor) | Autom.dev: Google mais Bing, Brave, Yahoo, DuckDuckGo, Baidu num stack SERP |
O resto deste guia é o caso JSON da web inteira: hoje chama customsearch/v1 com «Search the entire web» ativo. Os exemplos de código usam Piloterr; Autom.dev é a mesma ideia com outro host quando o SERP chega.
Piloterr ou Autom.dev?
Autom.dev é o nosso subproduto focado em SERP. Mesma família que a Piloterr, pensado para equipas cujo trabalho são resultados de pesquisa: tracking de rankings SEO, agentes que só precisam de JSON SERP, multi-motor em volume. A forma do endpoint é familiar: https://api.autom.dev/v1/google/search, x-api-key, query / gl / hl / tbs / page. Ver a doc Autom Google Search. O pricing é especializado SERP (créditos pay-per-use, sem teto tipo CSE de 10k/dia).
Escolha Piloterr para ficar na família Google: Google Search, Images, Autocomplete, AI Mode.
Escolha Autom.dev para Google e outros motores (Bing, Brave, Yahoo, DuckDuckGo, Baidu) numa só conta, ou pricing SERP-only em volume.
Mesma equipa. Mesmo padrão de migração desde Custom Search. Superfície diferente consoante se fica Google-only ou multi-motor.
O que obtém com Google Search da Piloterr
O mesmo contrato que já construiu: enviar uma query, receber resultados ordenados em JSON. Face a Custom Search:
| Custom Search JSON API | Google Search Piloterr | |
|---|---|---|
| Disponibilidade | Fechada a novos; fim 1 jan 2027 | Aberta |
| Setup | API key + Programmable Search Engine (cx) | Uma x-api-key |
| Custo | 100 grátis/dia, depois 5 $ / 1k, teto 10k/dia | 1 crédito por request |
| Teto diário | 10k queries | Planos por créditos, sem teto tipo CSE de 10k/dia |
| País / idioma | gl, lr, hl | Mesmos nomes: gl, hl, lr, mais cr |
| Resultados locais | Nível país | País + location / uule opcional (cidade) |
| Filtro de site | siteSearch / siteSearchFilter | Operadores Google em query (site:, -site:, …) |
| Filtro de data | dateRestrict (d7, w1, …) | tbs (qdr:d, qdr:w, qdr:m, qdr:y) |
| Paginação | Limitada | page para páginas seguintes |
| Payload | Items orgânicos + meta | Orgânicos, knowledge graph, related searches, pagination |
| Auth | Parâmetro key | Header x-api-key |
Docs: Google Search API · Referência API. GET e POST são suportados.
Como passar de Custom Search para Piloterr
Continua a enviar uma query e a ler JSON. Depois de remapear alguns campos, o código que consome títulos e links continua a funcionar.
- Crie uma conta em app.piloterr.com e copie a API key.
- Mapeie parâmetros de request e campos de response com as tabelas abaixo.
- Aponte a chamada HTTP para
https://api.piloterr.com/v2/google/search.
Mapeamento dos parâmetros de request
| Parâmetro Piloterr | Função | Equivalente Custom Search |
|---|---|---|
query | String de pesquisa (obrigatório). Suporta operadores Google | q |
gl | Viés de país (us, pt, br, …) | gl |
hl | Idioma de UI / resultados | hl |
lr | Restringir a idioma(s), ex. lang_pt | lr |
cr | Restringir a país(es), ex. countryPT | Mais próximo: filtros de país / config do motor |
tbs | Recência: qdr:h, qdr:d, qdr:w, qdr:m, qdr:y | dateRestrict |
location / uule | SERP ao nível da cidade | Sem equivalente CSE direto |
google_domain | google.com, google.pt, … | Locale / domínio do motor |
page | Número da página de resultados | Parcial / limitado no CSE |
safe | SafeSearch active / off | safe |
Header x-api-key | Auth | key |
| Não é necessário | cx (ID do motor) |
Include/exclude de siteSearch passa para a query: site:example.com coffee ou -site:pinterest.com coffee.
Mapeamento dos campos de response
| Custom Search | Google Search Piloterr |
|---|---|
items[].title | organic_results[].title |
items[].link | organic_results[].link |
items[].snippet | organic_results[].snippet |
items[].displayLink | organic_results[].domain |
items[].formattedUrl | organic_results[].displayed_link |
searchInformation.totalResults | search_information.total_results |
organic_results[].position, knowledge_graph, related_searches, pagination |
Python: antes e depois
Antes: Custom Search JSON API:
import os
import requests
resp = requests.get(
"https://www.googleapis.com/customsearch/v1",
params={
"key": os.environ["GOOGLE_API_KEY"],
"cx": os.environ["SEARCH_ENGINE_ID"],
"q": "best coffee shops",
"gl": "pt",
"hl": "pt",
"lr": "lang_pt",
"num": 10,
},
timeout=30,
)
for item in resp.json().get("items", []):
print(item["title"], item["link"])
Depois: Google Search Piloterr:
import os
import requests
resp = requests.post(
"https://api.piloterr.com/v2/google/search",
headers={"x-api-key": os.environ["PILOTERR_API_KEY"]},
json={
"query": "best coffee shops",
"gl": "pt",
"hl": "pt",
"lr": "lang_pt",
},
timeout=30,
)
for result in resp.json().get("organic_results", []):
print(result["position"], result["title"], result["link"])
O que muda de verdade:
- URL do endpoint
- Auth de
key(+cx) para o headerx-api-key q→queryitems→organic_results(campos comotitleelinkcontinuam familiares)gl/hl/lrmantêm os mesmos valores
GET funciona da mesma forma se preferir query string a body JSON.
No Autom.dev o swap é a mesma ideia: retire cx, envie query + gl / hl, autentique com x-api-key e aponte para https://api.autom.dev/v1/google/search (library). Os campos de response mantêm o estilo organic_results.
Para além do Google: Bing, Brave, Yahoo, DuckDuckGo
Custom Search era só Google. Muitos pipelines querem hoje um segundo índice por redundância, cobertura geo ou SEO multi-motor. Em Autom.dev o mesmo padrão query → JSON funciona em vários motores:
- Bing Search
- Brave Search
- Yahoo Search
- DuckDuckGo Search
- Baidu Search quando precisa desse mercado
- Ou
/v1/search: tenta Google, depois Brave, Bing, DuckDuckGo, Yahoo, Baidu até haver orgânicos
Na Piloterr, fique do lado Google com AI Mode, Images e Autocomplete na mesma API key que Google Search.
Migre antes de 1 de janeiro de 2027
A Custom Search JSON API para no início de 2027. A Google não oferece um substituto self-serve JSON para a web inteira. Se o seu código já faz «query → resultados JSON», pode passar para Google Search (ou Autom.dev para SERP-only / multi-motor) mudando o endpoint, removendo cx e renomeando alguns campos.
Precisa de dimensionar créditos ou validar um mix de queries em prod? Comece nas docs Google Search, compare com o pricing Autom.dev, ou abra uma conversa a partir do site.
FAQ
Quando encerra a Custom Search JSON API da Google?
A Google descontinua-a a 1 de janeiro de 2027. Já está fechada a novos clientes; os existentes podem usá-la até essa data.
Existe uma API oficial da Google para a web inteira?
Não self-serve. As opções documentadas cobrem pesquisa de site / domínios limitados (Agent Search / Vertex AI Search) e grounding enterprise. Para resultados programáticos da web inteira, a Google remete para um formulário de interesse.
Qual é a melhor alternativa à Custom Search JSON API?
Depende do trabalho. Site search → produto de site search. Até ~50 domínios no Google Cloud → Agent Search / Vertex AI Search. JSON da web inteira para apps e pipelines → uma API SERP como Google Search da Piloterr. SERP-only em volume (incluindo motores além do Google) → Autom.dev.
Piloterr ou Autom.dev: qual?
Mesma empresa. Piloterr cobre a família SERP Google (Search, Images, Autocomplete, AI Mode). Autom.dev é o subproduto SERP para Google mais Bing, Brave, Yahoo, DuckDuckGo e Baidu, com pricing por volume. Se só precisa de resultados Google em JSON, ambos servem. Se precisa de outros motores ou failover multi-motor, use Autom.dev.
Ainda preciso de um Programmable Search Engine (cx)?
Não. Google Search da Piloterr e Autom.dev só precisam da sua API key e de um query.
O Google Search da Piloterr suporta paginação?
Sim. Passe page (1, 2, …). Custom Search era bem mais limitado; jobs SERP multipágina são um motivo frequente para sair do CSE cedo.
Como filtro por data depois da migração?
Substitua dateRestrict por tbs: último dia qdr:d, semana qdr:w, mês qdr:m, ano qdr:y. Intervalos de calendário exactos do CSE não mapeiam 1:1; janelas relativas cobrem a maioria dos casos de monitoring.
