google-search-console-api

Trabaja con la API de Google Search Console (searchconsole v1 / webmasters v3): Consultas de Search Analytics, Inspección de URLs, Sitemaps y Sitios, manteniéndose dentro de sus cuotas. Úsalo cuando te pidan

¿Qué es google-search-console-api?

Esta habilidad proporciona acceso programático completo a la API de Google Search Console, cubriendo los cuatro servicios principales: Search Analytics (rendimiento), Inspección de URLs, Sitemaps y Sitios. Está diseñada para desarrolladores y profesionales de SEO que necesitan extraer datos de rendimiento (clics, impresiones, CTR, posición) para análisis, paneles o almacenamiento, verificar el estado de indexación de URLs a gran escala, gestionar sitemaps o propiedades, o construir pipelines de sincronización programados. La habilidad se enfoca en los aspectos más desafiantes de la API: cómo obtener datos completos y correctos respetando estrictos límites de cuota, incluyendo cuotas por minuto (QPM), por día (QPD) y la cuota de carga interna que depende de la complejidad de la consulta. Proporciona estrategias como consultar un día a la vez, paginar correctamente (hasta 25,000 filas por página), evitar volver a consultar datos ya finalizados, y elegir las dimensiones adecuadas para minimizar el costo de las consultas. También cubre la autenticación (OAuth 2.0 con cuentas de servicio o cliente de escritorio), el manejo de errores comunes (401, 403, 429, cuota excedida), y las mejores prácticas para evitar la pérdida de datos, como no promediar CTRs ni posiciones y entender los límites de 50,000 filas por día por tipo de búsqueda.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more Investigación y análisis de datos skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

ServicioMétodoHTTPÁmbito (mín.)
Search Analyticssearchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
Inspección de URLsurlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
Sitemapslist / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
Sitemapssubmit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
Sitioslist / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
Sitiosadd / deletePUT / 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, siteUrl y feedpath deben 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.list y usa un siteUrl exactamente como se devuelve. siteUnverifiedUser no 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 page o query (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.
  • 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)

  1. 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.
  2. Consulta un día a la vez (startDate == endDate), una vez por día, para cada type que 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á.
  3. Pagina los resultados: rowLimit máximo 25.000 (predeterminado 1.000), incrementa startRow en 25.000 hasta que una página devuelva menos filas de las solicitadas o 0 filas.
  4. 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 page y/o query elimina 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 dimensiones page/query.
  • Los totales difieren según la agregación: byProperty (deduplicado por propiedad) vs byPage (por URL canónica). Si agrupas o filtras por page, byProperty no está permitido — usa auto.
  • 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.
  • position es 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). searchType es el alias obsoleto.
  • dimensionFilterGroups[].filters[]: {dimension, operator, expression}; operadores equals (predeterminado, sensible a mayúsculas para página/consulta), notEquals, contains, notContains, includingRegex, excludingRegex (RE2). Los grupos se combinan con AND; solo se admite groupType: "and".
  • dimensionFilterGroups[].filterLists[]: coincidencia exacta de múltiples valores para country / device ({"dimension":"country","expressions":["usa","can"]}). No se puede filtrar la misma dimensión en filters y filterLists.
  • aggregationType: auto (predeterminado), byPage, byProperty (no para discover/googleNews), byNewsShowcasePanel.
  • dataState: final (predeterminado), all (incluye datos frescos, aún no finalizados), hourly_all (requerido para la dimensión hour; ~10 días disponibles). La respuesta metadata.firstIncompleteDate / firstIncompleteHour marca dónde los números pueden cambiar.

Problemas comunes

  • La apariencia de búsqueda es de dos pasos: consulta con searchAppearance como la única dimensión para listar tipos, luego filtra searchAppearance equals <TIPO> y agrega otras dimensiones — una consulta por tipo.
  • brandedClassification (BRANDED / NON_BRANDED): solo equals; no se puede combinar con un filtro query en 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 startRow fuera 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.
  • rows está 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.
  • inspectionUrl debe estar bajo siteUrl.
  • Lee indexStatusResult: verdict (PASS = válido, NEUTRAL = excluido, FAIL = error), coverageState (la cadena legible, p. ej., "Enviada e indexada"), robotsTxtState, indexingState, pageFetchState, lastCrawlTime, googleCanonical vs userCanonical, crawledAs.
  • La señal masiva más útil es googleCanonical != userCanonical (Google eligió una canónica diferente).
  • mobileUsabilityResult está obsoleto. ampResult / richResultsResult está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.

  1. Crea/selecciona un proyecto de Google Cloud → habilita la API de Google Search Console.
  2. 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.
  3. Usa una biblioteca cliente (recomendado) — p. ej., Python google-api-python-client con build("searchconsole", "v1", credentials=creds), Node googleapis con google.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íntomaCausaAcción
401 authError / expiredtoken malo/expiradoactualiza 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 propiedadsites.list, usa el siteUrl exacto; agrega la cuenta de servicio en Search Console
403 accessNotConfiguredAPI no habilitada en el proyectohabilita la API de Search Console
403/429 rateLimitExceeded, userRateLimitExceededQPS/QPMretroceso exponencial con fluctuación aleatoria
403/429 quotaExceeded (Search Analytics)cuota de cargaespera 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 / badRequestenumeración incorrecta, orden de fechas, filters/filterLists mezclados en la misma dimensión, byProperty con páginacorrige la solicitud; no reintentes
500 / 503 backendErrortransitorioretrocede 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.

Skills relacionados