API de Google Search Console
La API de Search Console proporciona acceso programático a la mayoría de Google Search Console: el informe de Rendimiento (Search Analytics), Inspección de URLs, Sitemaps y la lista de propiedades (Sitios). Es una API REST/JSON. Cada llamada necesita OAuth 2.0 y un usuario (o cuenta de servicio) con permiso de Search Console en la propiedad.
La parte difícil no es hacer una llamada. Es obtener datos completos y correctos sin exceder la cuota. La mayor parte de esta habilidad trata sobre eso.
Cuándo usar esta habilidad
- Extraer datos de rendimiento (clics, impresiones, CTR, posición) para análisis, paneles, almacenamiento de datos o investigaciones SEO.
- Verificar el estado de indexación, selección canónica, estado de robots/noindex o validez de resultados enriquecidos para URLs a escala.
- Listar propiedades y permisos, listar o enviar sitemaps.
- Diseñar un trabajo de sincronización programado, o reparar uno que alcanza
quotaExceeded, pierde filas o devuelve números que no coinciden con la interfaz de usuario.
No cubierto por esta API: el informe de indexación de páginas (cobertura), Enlaces, Core Web Vitals, Estadísticas de rastreo, Acciones manuales, eliminaciones y el botón "Solicitar indexación". Para Core Web Vitals de campo, usa la API CrUX; para datos de rendimiento masivos sin procesar en sitios grandes, usa la exportación masiva de datos a BigQuery de Search Console; la API de Indexación independiente solo admite páginas de JobPosting / BroadcastEvent.
Los cuatro servicios
| Servicio | Método | HTTP | Ámbito (mín.) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| Inspección de URLs | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sitios | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sitios | add / delete | PUT / DELETE /webmasters/v3/sites/{siteUrl} | webmasters |
URL raíz: https://searchconsole.googleapis.com/ (documento de descubrimiento actual, servicio searchconsole v1). Las rutas más antiguas https://www.googleapis.com/webmasters/v3/... aún aparecen en la documentación de Google y siguen funcionando para los recursos webmasters/v3.
Ámbitos: https://www.googleapis.com/auth/webmasters.readonly (solo lectura) y https://www.googleapis.com/auth/webmasters (lectura/escritura). Solicita solo lectura a menos que la tarea realmente envíe/elimine sitemaps o añada/elimine sitios.
Identificadores de propiedad (siteUrl) — la fuente n.º 1 de errores 403/404
- Propiedad de dominio:
sc-domain:example.com - Propiedad de prefijo de URL:
https://www.example.com/— el esquema, el host y la barra inclinada final deben coincidir exactamente con lo que está en Search Console. - En las rutas,
siteUrlyfeedpathdeben estar completamente codificados en URL (https%3A%2F%2Fwww.example.com%2F,sc-domain%3Aexample.com). Las bibliotecas cliente hacen esto por ti; HTTP sin procesar no. - Siempre comienza llamando a
sites.listy usa unsiteUrlexactamente como se devuelve.siteUnverifiedUserno puede leer datos.
Cuotas — lee antes de escribir cualquier bucle
Detalle completo y una hoja de cálculo de presupuesto: references/LIMITS.md.
Search Analytics
- Límites de QPM: 1.200 QPM por sitio, 1.200 QPM por usuario, 40.000 QPM y 30.000.000 QPD por proyecto. Ejemplo: un usuario que accede a 3 sitios obtiene 1.200 QPM combinados; dos usuarios en un sitio comparten 1.200 QPM.
- Cuota de carga (la que realmente afecta): costo interno de una consulta, rastreado en ventanas de 10 minutos (corto plazo) y 1 día (largo plazo). El costo aumenta con:
- agrupar/filtrar por
pageoquery(ambos juntos es lo más caro), - la duración del rango de fechas (6 meses ≫ 1 día),
- volver a consultar datos que ya tienes.
- agrupar/filtrar por
- Superar cualquiera de estos límites devuelve el mismo error
quotaExceeded. Corto plazo: espera 15 minutos y reintenta. Si una sola consulta en una ventana de 10 minutos aún falla, has superado la cuota de carga a largo plazo (diaria) — reduce el costo; reintentar no ayudará hasta mañana.
Inspección de URLs: 2.000 QPD y 600 QPM por sitio; 10.000.000 QPD y 15.000 QPM por proyecto. 2.000 por día por propiedad es el techo real — planifica el muestreo, no planifiques "inspeccionar cada URL".
Todo lo demás (sitios, sitemaps): 20 QPS y 200 QPM por usuario; 100.000.000 QPD por proyecto.
El procesamiento por lotes no ahorra cuota: un lote de n llamadas cuenta como n solicitudes. El procesamiento por lotes solo ahorra la sobrecarga HTTP. Uso actual: Consola de Google Cloud → APIs y Servicios → API de Search Console → Cuotas.
Search Analytics: obteniendo datos completos y correctos
Esquema completo de solicitud/respuesta y recetas: references/SEARCH-ANALYTICS.md.
El patrón recomendado (de la guía "todos tus datos" de Google)
- Comprueba la actualización primero. Consulta los últimos ~10 días agrupados solo por
date— sin filtros, sin otras dimensiones. Los días sin datos simplemente están ausentes. Los datos finales suelen tener un retraso de 2–3 días. - Consulta un día a la vez (
startDate == endDate), una vez por día, para cadatypeque necesites. Una consulta diaria de un día no debería exceder tu cuota diaria; un rango de 16 meses agrupado por página+consulta lo hará. - Pagina los resultados:
rowLimitmáximo 25.000 (predeterminado 1.000), incrementastartRowen 25.000 hasta que una página devuelva menos filas de las solicitadas o 0 filas. - Nunca vuelvas a extraer el historial finalizado. Almacénalo; solo obtén nuevos días (y vuelve a obtener días recientes no finalizados si usas
dataState: "all").
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
"startDate": "2026-11-14",
"endDate": "2026-11-14",
"dimensions": ["page", "query", "country", "device"],
"type": "web",
"rowLimit": 25000,
"startRow": 0
}
Límites de datos estrictos que debes explicar a las partes interesadas
- La API devuelve filas principales, no todas las filas: como máximo 50.000 filas por día por tipo de búsqueda (ordenadas por clics), independientemente de la paginación.
- Agrupar/filtrar por
pagey/oqueryelimina algunos datos (para mantener el cálculo acotado) y las consultas raras anonimizadas nunca se devuelven. Por lo tanto, la suma de filas < total de la propiedad. Para totales precisos, consulta sin dimensionespage/query. - Los totales difieren según la agregación:
byProperty(deduplicado por propiedad) vsbyPage(por URL canónica). Si agrupas o filtras porpage,byPropertyno está permitido — usaauto. - Las fechas están en Hora del Pacífico (
America/Los_Angeles), no UTC. - La retención de datos de rendimiento en Search Console es de aproximadamente 16 meses. Persiste los datos si necesitas un historial más largo.
Matemáticas correctas de las métricas
- CTR de un grupo =
sum(clics) / sum(impresiones). Nunca promedies los CTR. - Posición de un grupo = ponderada por impresiones:
sum(posición × impresiones) / sum(impresiones). Nunca promedies las posiciones. positiones la posición superior promedio basada en 1; cuanto menor es el número, mejor.
Campos clave de la solicitud (referencia rápida)
dimensions:date,hour,query,page,country(ISO 3166-1 alpha-3, en minúsculas en los resultados, p. ej.,usa),device(DESKTOP/MOBILE/TABLET),searchAppearance,brandedClassification.type:web(predeterminado),image,video,news(pestaña Noticias),googleNews(news.google.com + app),discover,webMultimodal(Lens / Circle to Search / cargas de imágenes).searchTypees el alias obsoleto.dimensionFilterGroups[].filters[]:{dimension, operator, expression}; operadoresequals(predeterminado, sensible a mayúsculas para página/consulta),notEquals,contains,notContains,includingRegex,excludingRegex(RE2). Los grupos se combinan con AND; solo se admitegroupType: "and".dimensionFilterGroups[].filterLists[]: coincidencia exacta de múltiples valores paracountry/device({"dimension":"country","expressions":["usa","can"]}). No se puede filtrar la misma dimensión enfiltersyfilterLists.aggregationType:auto(predeterminado),byPage,byProperty(no paradiscover/googleNews),byNewsShowcasePanel.dataState:final(predeterminado),all(incluye datos frescos, aún no finalizados),hourly_all(requerido para la dimensiónhour; ~10 días disponibles). La respuestametadata.firstIncompleteDate/firstIncompleteHourmarca dónde los números pueden cambiar.
Problemas comunes
- La apariencia de búsqueda es de dos pasos: consulta con
searchAppearancecomo la única dimensión para listar tipos, luego filtrasearchAppearance equals <TIPO>y agrega otras dimensiones — una consulta por tipo. brandedClassification(BRANDED/NON_BRANDED): soloequals; no se puede combinar con un filtroqueryen la misma solicitud; datos a partir del 2026-02-21 y solo para propiedades de nivel superior con suficiente volumen.- Los resultados se ordenan por clics descendente, excepto cuando se agrupan por
date(fecha ascendente). Los empates son arbitrarios — no confíes en el orden para la deduplicación. - Un
startRowfuera de rango devuelve 200 con cero filas, no un error. Los datos exactamente en un límite de 25.000 devuelven una página siguiente vacía. rowsestá ausente (no[]) cuando no hay datos.
Inspección de URLs
Esquema completo, enumeraciones y una tabla de clasificación: references/URL-INSPECTION.md.
POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
- Informa solo de la versión indexada. No puede probar una URL en vivo y no puede solicitar indexación.
inspectionUrldebe estar bajositeUrl.- Lee
indexStatusResult:verdict(PASS = válido, NEUTRAL = excluido, FAIL = error),coverageState(la cadena legible, p. ej., "Enviada e indexada"),robotsTxtState,indexingState,pageFetchState,lastCrawlTime,googleCanonicalvsuserCanonical,crawledAs. - La señal masiva más útil es
googleCanonical != userCanonical(Google eligió una canónica diferente). mobileUsabilityResultestá obsoleto.ampResult/richResultsResultestán ausentes cuando no corresponden.- Presupuesto: 2.000/día/propiedad. Prioriza una muestra: páginas principales por clics, plantillas modificadas recientemente, una URL por plantilla/patrón, URLs de nuevos sitemaps.
Sitios y Sitemaps
Consulta references/SITES-AND-SITEMAPS.md. sites.list → siteEntry[] {siteUrl, permissionLevel} con siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser. sitemaps.list → sitemap[] con path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted (contents[].indexed está obsoleto — no lo informes). submit / delete no toman cuerpo y necesitan el ámbito de lectura/escritura. Estas son escrituras. Confirma con el usuario antes de llamarlas.
Autenticación y configuración
Paso a paso, más líneas de instalación de la biblioteca para cada lenguaje: references/AUTH-AND-SETUP.md.
- Crea/selecciona un proyecto de Google Cloud → habilita la API de Google Search Console.
- Elige una credencial:
- Cliente OAuth de escritorio/instalado: para un humano que ejecuta scripts localmente; el usuario da su consentimiento en un navegador y tú almacenas el token de actualización.
- Cuenta de servicio: para trabajos no supervisados. Luego agrega el correo electrónico de la cuenta de servicio como usuario en la propiedad en Search Console (Configuración → Usuarios y permisos). Restringido es suficiente para lecturas; Propietario/Completo es necesario para escrituras. Sin este paso, cada llamada devuelve 403.
- Las claves de API no son aceptadas para estos recursos; OAuth 2.0 es el único protocolo admitido.
- Usa una biblioteca cliente (recomendado) — p. ej., Python
google-api-python-clientconbuild("searchconsole", "v1", credentials=creds), Nodegoogleapiscongoogle.searchconsole("v1").
from google.oauth2 import service_account
from googleapiclient.discovery import build
creds = service_account.Credentials.from_service_account_file(
"sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)
resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
"startDate": "2026-11-14", "endDate": "2026-11-14",
"dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", []) # ausente cuando está vacío
Nunca imprimas, registres ni confirmes tokens, secretos de cliente o claves de cuenta de servicio.
Errores y reintentos
Mapa completo: references/ERRORS.md.
| Síntoma | Causa | Acción |
|---|---|---|
401 authError / expired | token malo/expirado | actualiza el token; verifica los ámbitos |
403 insufficientPermissions / "El usuario no tiene permiso suficiente para el sitio" | forma incorrecta de siteUrl, o el principal no es un usuario en la propiedad | sites.list, usa el siteUrl exacto; agrega la cuenta de servicio en Search Console |
403 accessNotConfigured | API no habilitada en el proyecto | habilita la API de Search Console |
403/429 rateLimitExceeded, userRateLimitExceeded | QPS/QPM | retroceso exponencial con fluctuación aleatoria |
403/429 quotaExceeded (Search Analytics) | cuota de carga | espera 15 min una vez; si una sola consulta aún falla → carga a largo plazo: reduce el rango de fechas o elimina page/query, reanuda mañana |
400 invalidParameter / badRequest | enumeración incorrecta, orden de fechas, filters/filterLists mezclados en la misma dimensión, byProperty con página | corrige la solicitud; no reintentes |
500 / 503 backendError | transitorio | retrocede y reintenta (acotado) |
Rendimiento
references/BATCH-AND-PERFORMANCE.md: gzip (Accept-Encoding: gzip y un User-Agent que contenga gzip), respuestas parciales mediante fields= (p. ej., fields=rows(keys,clicks,impressions)), y lotes HTTP (multipart/mixed, ≤ 1.000 llamadas, ejecutadas en cualquier orden, cada llamada aún cuenta contra la cuota).
El script auxiliar
scripts/gsc.py es un CLI de un solo archivo que usa solo la biblioteca estándar de Python 3.9+. Escribe el progreso en stderr y los datos en stdout (JSONL de forma predeterminada, o CSV/JSON). Pagina, respeta los límites y maneja los errores transitorios con un retroceso exponencial.