En resumen: la Custom Search JSON API de Google está cerrada a nuevos clientes y deja de funcionar para usuarios existentes el 1 de enero de 2027. Si tu app o pipeline envía una consulta y lee resultados de Google en JSON de toda la web, Google Search en Piloterr mantiene el patrón: query in, SERP estructurada out. La mayoría de filtros gl / hl / lr mapean 1:1. Para cargas SERP-only a volumen, el mismo equipo ofrece Autom.dev, una API SERP dedicada con el mismo estilo de parámetros.
Migrar son unas pocas líneas, no un rewrite.
Qué se apaga
Google indica en la overview de Custom Search JSON API:
- La API no está disponible para nuevos clientes.
- Los clientes existentes pueden usarla hasta el 1 de enero de 2027.
- Hasta entonces, el precio se mantiene: 100 consultas gratis al día, luego 5 $ por 1.000 consultas, con tope de 10k consultas al día.
Para buscar hasta unas 50 dominios, Google apunta a Vertex AI Search (a veces Agent Search). Para resultados de toda la web, no hay producto self-serve de Google, solo un formulario de interés.
Fuente: Google for Developers: Custom Search JSON API.
Elige el reemplazo según lo que buscas de verdad
Custom Search cubría varios trabajos. No comparten un solo sucesor.
| Para qué usas Custom Search | Qué usar en su lugar |
|---|---|
| Buscador en tu propio sitio | Programmable Search Element de Google, o site search (Algolia, Typesense, Meilisearch) |
| Un conjunto de dominios o tu corpus en Google Cloud | Google Agent Search / Vertex AI Search (ruta «~50 dominios») |
| Resultados de toda la web en JSON para app, agente o pipeline | Google Search en Piloterr, o Autom.dev si solo necesitas SERP |
| Respuestas generadas con citas (Google AI Mode) | Google AI Mode, opcionalmente con búsqueda orgánica |
| SEO SERP profundo (ads, AI Overviews, muchas páginas) | Google Search con paginación page, más Images / Autocomplete si hace falta |
| El mismo patrón de query en Bing, Brave, Yahoo, DuckDuckGo (o failover multi-motor) | Autom.dev: Google más Bing, Brave, Yahoo, DuckDuckGo, Baidu en un stack SERP |
El resto de esta guía es el caso JSON de toda la web: hoy llamas a customsearch/v1 con «Search the entire web» activado. Los ejemplos de código usan Piloterr; Autom.dev es la misma idea con otro host cuando el SERP basta.
¿Piloterr o Autom.dev?
Autom.dev es nuestro subproducto centrado en SERP. Misma familia que Piloterr, pensado para equipos cuyo trabajo son los resultados de búsqueda: tracking de rankings SEO, agentes que solo necesitan JSON SERP, multi-motor a volumen. La forma del endpoint es familiar: https://api.autom.dev/v1/google/search, x-api-key, query / gl / hl / tbs / page. Ver la doc Autom Google Search. El pricing es especializado SERP (créditos pay-per-use, sin techo tipo CSE de 10k/día).
Elige Piloterr para quedarte en la familia Google: Google Search, Images, Autocomplete, AI Mode.
Elige Autom.dev para Google y otros motores (Bing, Brave, Yahoo, DuckDuckGo, Baidu) en una sola cuenta, o pricing SERP-only a volumen.
Mismo equipo. Mismo patrón de migración desde Custom Search. Superficie distinta según si te quedas Google-only o multi-motor.
Qué obtienes con Google Search de Piloterr
El mismo contrato que ya construiste: enviar una query, recibir resultados ordenados en JSON. Frente a Custom Search:
| Custom Search JSON API | Google Search Piloterr | |
|---|---|---|
| Disponibilidad | Cerrada a nuevos; fin 1 ene 2027 | Abierta |
| Setup | API key + Programmable Search Engine (cx) | Una x-api-key |
| Coste | 100 gratis/día, luego 5 $ / 1k, tope 10k/día | 1 crédito por request |
| Tope diario | 10k consultas | Planes por créditos, sin techo tipo CSE de 10k/día |
| País / idioma | gl, lr, hl | Mismos nombres: gl, hl, lr, más cr |
| Resultados locales | Nivel país | País + location / uule opcional (ciudad) |
| Filtro de sitio | siteSearch / siteSearchFilter | Operadores Google en query (site:, -site:, …) |
| Filtro de fecha | dateRestrict (d7, w1, …) | tbs (qdr:d, qdr:w, qdr:m, qdr:y) |
| Paginación | Limitada | page para siguientes páginas |
| Payload | Items orgánicos + meta | Orgánicos, knowledge graph, related searches, pagination |
| Auth | Parámetro key | Header x-api-key |
Docs: Google Search API · Referencia API. GET y POST están soportados.
Cómo pasar de Custom Search a Piloterr
Sigues enviando una query y leyendo JSON. Tras remapear unos campos, el código que consume títulos y links sigue funcionando.
- Crea una cuenta en app.piloterr.com y copia tu API key.
- Mapea parámetros de request y campos de response con las tablas de abajo.
- Apunta la llamada HTTP a
https://api.piloterr.com/v2/google/search.
Mapeo de parámetros de request
| Parámetro Piloterr | Qué hace | Equivalente Custom Search |
|---|---|---|
query | Cadena de búsqueda (obligatorio). Soporta operadores Google | q |
gl | Sesgo de país (us, es, fr, …) | gl |
hl | Idioma de UI / resultados | hl |
lr | Restringir a idioma(s), p. ej. lang_es | lr |
cr | Restringir a país(es), p. ej. countryES | Más cercano: filtros de país / config del motor |
tbs | Recencia: qdr:h, qdr:d, qdr:w, qdr:m, qdr:y | dateRestrict |
location / uule | SERP a nivel ciudad | Sin equivalente CSE directo |
google_domain | google.com, google.es, … | Locale / dominio del motor |
page | Número de página de resultados | Parcial / limitado en CSE |
safe | SafeSearch active / off | safe |
Header x-api-key | Auth | key |
| No hace falta | cx (ID del motor) |
El include/exclude de siteSearch pasa a la query: site:example.com coffee o -site:pinterest.com coffee.
Mapeo de 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 y después
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": "es",
"hl": "es",
"lr": "lang_es",
"num": 10,
},
timeout=30,
)
for item in resp.json().get("items", []):
print(item["title"], item["link"])
Después: 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": "es",
"hl": "es",
"lr": "lang_es",
},
timeout=30,
)
for result in resp.json().get("organic_results", []):
print(result["position"], result["title"], result["link"])
Qué cambia de verdad:
- URL del endpoint
- Auth de
key(+cx) al headerx-api-key q→queryitems→organic_results(campos comotitleylinksiguen familiares)gl/hl/lrmantienen los mismos valores
GET funciona igual si prefieres query string a body JSON.
En Autom.dev el swap es la misma idea: quita cx, envía query + gl / hl, autentica con x-api-key y apunta a https://api.autom.dev/v1/google/search (library). Los campos de response siguen el estilo organic_results.
Más allá de Google: Bing, Brave, Yahoo, DuckDuckGo
Custom Search era solo Google. Muchos pipelines quieren hoy un segundo índice por redundancia, cobertura geo o SEO multi-motor. En Autom.dev el mismo patrón query → JSON funciona en varios motores:
- Bing Search
- Brave Search
- Yahoo Search
- DuckDuckGo Search
- Baidu Search cuando necesitas ese mercado
- O
/v1/search: prueba Google, luego Brave, Bing, DuckDuckGo, Yahoo, Baidu hasta obtener orgánicos
En Piloterr, quédate en Google con AI Mode, Images y Autocomplete en la misma API key que Google Search.
Migra antes del 1 de enero de 2027
Custom Search JSON API para a principios de 2027. Google no ofrece un reemplazo self-serve JSON de toda la web. Si tu código ya hace «query → resultados JSON», puedes pasar a Google Search (o Autom.dev para SERP-only / multi-motor) cambiando el endpoint, quitando cx y renombrando unos campos.
¿Necesitas dimensionar créditos o validar un mix de queries en prod? Empieza por la docs de Google Search, compara con el pricing de Autom.dev, o abre una conversación desde el sitio.
FAQ
¿Cuándo cierra la Custom Search JSON API de Google?
Google la discontinua el 1 de enero de 2027. Ya está cerrada a nuevos clientes; los existentes pueden usarla hasta esa fecha.
¿Hay una API oficial de Google para toda la web?
No self-serve. Las opciones documentadas cubren búsqueda de sitio / dominios limitados (Agent Search / Vertex AI Search) y grounding enterprise. Para resultados programáticos de toda la web, Google remite a un formulario de interés.
¿Cuál es la mejor alternativa a Custom Search JSON API?
Depende del trabajo. Site search → producto de site search. Hasta ~50 dominios en Google Cloud → Agent Search / Vertex AI Search. JSON de toda la web para apps y pipelines → una API SERP como Google Search de Piloterr. SERP-only a volumen (incluidos motores más allá de Google) → Autom.dev.
¿Piloterr o Autom.dev: cuál?
Misma empresa. Piloterr cubre la familia SERP de Google (Search, Images, Autocomplete, AI Mode). Autom.dev es el subproducto SERP para Google más Bing, Brave, Yahoo, DuckDuckGo y Baidu, con pricing por volumen. Si solo necesitas resultados Google en JSON, ambos valen. Si necesitas otros motores o failover multi-motor, usa Autom.dev.
¿Sigo necesitando un Programmable Search Engine (cx)?
No. Google Search de Piloterr y Autom.dev solo necesitan tu API key y un query.
¿Google Search de Piloterr soporta paginación?
Sí. Pasa page (1, 2, …). Custom Search era mucho más limitado; los jobs SERP multipágina son una razón habitual para dejar CSE pronto.
¿Cómo filtro por fecha tras migrar?
Sustituye dateRestrict por tbs: último día qdr:d, semana qdr:w, mes qdr:m, año qdr:y. Los rangos de calendario exactos de CSE no mapean 1:1; las ventanas relativas cubren la mayoría de casos de monitoring.
