API de Search Console

TL;DR — La API de Search Console te permite obtener tus datos de Google Search Console con código en lugar de hacer clic en la interfaz. Así es como obtienes más de lo que la interfaz te ofrece: la exportación en la interfaz llega a un máximo de 1 000 filas, mientras que la API te da hasta 25 000 por solicitud. Inicias sesión con Google (OAuth, no una clave de API simple), y solo obtienes datos para sitios que hayas verificado.

Qué es la API de Search Console

Search Console te muestra cómo le va a tu sitio en Google: qué consultas posicionas, cuántos clics e impresiones obtienes, si tus páginas están indexadas. La API te da acceso programático a gran parte de esos mismos datos y esos mismos controles, para que puedas alimentar una hoja de cálculo, un panel o un script que se ejecute según un horario. Sin embargo, no es una paridad total con la interfaz: algunas cosas (como probar una URL en vivo) solo existen en la interfaz, y tener acceso a la API o automatización no garantiza por sí mismo la indexación, los rankings, el diagnóstico de tráfico ni la visibilidad en la búsqueda con IA.

Hay cuatro partes:

1. API de Search Analytics — tus números del informe de rendimiento (clics, impresiones, CTR, posición promedio), desglosados por consulta, página, país, dispositivo y fecha.
2. API de URL Inspection — el estado de indexación de una sola URL. Informa la versión actualmente en el índice de Google; la herramienta URL Inspection de la interfaz también puede ejecutar una prueba en vivo, que la API no puede hacer.
3. API de Sitemaps — lista, envía o elimina tus sitemaps.
4. API de Sites — lista, agrega o elimina las propiedades de tu cuenta.

Límite de propiedad de plataforma: Search Console ahora tiene propiedades separadas de Instagram, TikTok, X y YouTube, pero la documentación actual de plataformas de Google describe sus informes de interfaz y exportación de informes, no un identificador siteUrl ni un contrato de soporte para estos endpoints heredados. Por lo tanto, el flujo de trabajo de la API en este artículo cubre solo propiedades de sitios web. LinkedIn no es una propiedad de plataforma compatible.

Por qué usarla en lugar de la interfaz

La gran razón: filas. Si exportas el informe de rendimiento desde la interfaz de Search Console, obtienes aproximadamente 1 000 filas. La API devuelve hasta 25 000 filas por solicitud, y puedes paginar para obtener más. Si tienes un sitio con miles de consultas o páginas, la interfaz simplemente no te muestra la mayor parte de tus datos.

La otra razón es la automatización. Una vez que es una llamada a la API, puedes ejecutarla cada mañana, volcarla en un panel o alertarte cuando los clics bajen.

El inconveniente

Solo puedes extraer datos de propiedades que hayas verificado en Search Console. Si apuntas la API a un sitio que no te pertenece, no obtienes nada: ese es el error más común para principiantes.

Y la API no te proporciona todo. Devuelve las filas principales, no la lista completa, y nunca muestra las consultas que Google anonimiza por privacidad. Para un sitio grande que necesita una visión completa, la herramienta adecuada es la exportación masiva de datos a BigQuery, explicada en la versión avanzada.

TL;DR — La API de Search Console son cuatro API REST bajo webmaster-tools/v1 — Search Analytics, URL Inspection, Sitemaps, Sites — todas con OAuth 2,0, todas limitadas solo a propiedades verificadas. Search Analytics devuelve 1–25 000 filas por solicitud (por defecto 1 000) pero “no garantiza devolver todas las filas de datos, sino las principales”, así que para completitud a escala pasas a la exportación de datos masivos a BigQuery. URL Inspection tiene un límite máximo de 2 000 QPD / 600 QPM por sitio — esa aritmética es lo que limita el monitoreo de indexación a gran escala.

Esta guía de la API está limitada a propiedades de sitios web. No asumas que los endpoints de Sites, Search Analytics, URL Inspection o Sitemaps admiten propiedades de plataforma de Instagram, TikTok, X o YouTube hasta que Google documente el identificador y el contrato de endpoint.

Las cuatro APIs de un vistazo

La propia descripción de Google sobre lo que hace la API: permite “ver, añadir o eliminar propiedades y sitemaps, ejecutar consultas avanzadas para datos de resultados de búsqueda de Google para las propiedades que gestionas en Search Console, y probar páginas individuales.” Eso se corresponde claramente con los cuatro recursos, todos bajo webmaster-tools/v1:

• API de Search Analytics — el informe de rendimiento, de forma programática: clics, impresiones, CTR, posición por dimensión (consulta, página, país, dispositivo, apariencia de búsqueda, fecha, hora).
• API de URL Inspection — el estado de indexación de una URL individual, el equivalente programático de la herramienta URL Inspection.
• API de Sitemaps — listar, obtener, enviar y eliminar sitemaps.
• API de Sites — listar, añadir y eliminar propiedades verificadas.

Expone gran parte de lo que ya usas en la interfaz — el informe de rendimiento y la herramienta URL Inspection — como endpoints que puedes automatizar. Sin embargo, no es un espejo 1:1: la API no garantiza una paridad total con la interfaz (la prueba en vivo de URL Inspection, por ejemplo, es solo de interfaz — ver más abajo), y ni el acceso a la API ni la automatización por sí solos garantizan indexación, rankings, diagnóstico de tráfico o visibilidad en la búsqueda con IA.

Autenticación: OAuth 2,0, dos ámbitos, solo propiedades verificadas

No hay clave de API. Cada llamada es OAuth 2,0 — Google es explícito: “all requests to the Google Search Console API must be authorized by an authenticated user.” (traducción) «todas las solicitudes a la API de Google Search Console deben estar autorizadas por un usuario autenticado». Registras una aplicación en Google Cloud, solicitas un ámbito y obtienes un token de acceso de corta duración. Existen dos ámbitos:

• https://www.googleapis.com/auth/webmasters — lectura/escritura.
• https://www.googleapis.com/auth/webmasters.readonly — solo lectura.

Para automatización de servidor a servidor (un trabajo de informes nocturno, un monitor de indexación) concedes acceso a una cuenta de servicio a la propiedad y omites el flujo de consentimiento interactivo.

Para propiedades de sitio web, también importan aquí dos formatos de identificador de propiedad: una propiedad de prefijo de URL se pasa como URL completa de propiedad (el propio ejemplo de Google es http://www.example.com/), y una propiedad de dominio usa la forma sc-domain:example.com — debes pasar la forma que coincida con cómo está verificada la propiedad en Search Console. En cualquier caso, la cuenta de servicio (o el usuario) debe tener acceso concedido a esa exacta propiedad; no es un bypass para la propiedad ni una concesión general en todas las propiedades de la cuenta.

Y la barrera con la que tropieza todo el mundo: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (traducción) «debes tener acceso adecuado —propietario, completo o lectura— a cualquier cuenta de Google Search Console a la que desees acceder mediante la API». Si llamas a la API para una propiedad en la que no estás verificado, devuelve nada — no un error que necesariamente notes, solo datos vacíos.

API de Search Analytics — el informe de rendimiento, a escala

Empieza con el límite, no con la conveniencia: la propia advertencia de Google es que “La API está limitada por las limitaciones internas de Search Console y no garantiza devolver todas las filas de datos, sino las principales.” La paginación extiende hasta dónde puedes paginar en esa lista de filas principales — no elimina el límite. Cuando necesitas cada fila, esa es la señal para recurrir a la exportación masiva de BigQuery (más abajo), no a un rowLimit mayor.

Dentro de ese límite, esta sigue siendo la que la mayoría busca. La razón por la que supera a la interfaz es el parámetro rowLimit: “[Opcional; el rango válido es 1–25 000; el valor predeterminado es 1 000].” La exportación de la interfaz se limita a cerca de 1 000 filas; la API te da hasta 25 000 por solicitud, y paginas más allá de eso con startRow. En un sitio con una cola larga de consultas, esa es la diferencia entre ver la parte superior de tus datos y ver más de ellos — aún no todos.

Dos cosas más determinan lo que se devuelve. Primero, dataState controla la frescura: final (el valor predeterminado) devuelve solo datos finalizados, all incluye datos frescos y recientemente recopilados, y hourly_all proporciona desgloses por hora que son explícitamente parciales: los metadatos de la respuesta marcan un first_incomplete_date o first_incomplete_hour, y Google señala que los valores posteriores a ese punto aún pueden cambiar. Segundo, las cuotas de Search Analytics no son un número único: la página de límites de uso las divide en límites de carga (una asignación basada en recursos medida en bloques de 10 minutos y 1 día: rangos de fechas más amplios, más dimensiones y un filtrado más intenso la agotan más rápido) y los límites de tasa de solicitudes QPS/QPM/QPD que se cubren a continuación. Puedes alcanzar el techo de carga antes de alcanzar el techo de tasa de solicitudes.

API de URL Inspection — y la cuota que realmente te limita

La API de URL Inspection “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (traducción) «ve el estado indexado o indexable de la URL proporcionada. A día de hoy, la API solo ofrece el estado de la versión presente en el índice de Google y no permite comprobar la indexabilidad de una URL en vivo». Esa última cláusula es un límite real del alcance, no un tecnicismo: la herramienta URL Inspection de la interfaz puede ejecutar una prueba en vivo contra la página tal como existe ahora; la API solo puede informar sobre la versión que Google ya tiene indexada. Usa la API para crear un monitoreo de cobertura de índice en muchas URLs, no como sustituto de la prueba en vivo de la interfaz.

Aquí es donde las matemáticas importan. Por sitio, obtienes 2 000 consultas por día y 600 por minuto. (Por proyecto, el techo es mucho más alto: 10 000 000/día y 15 000/minuto, pero el límite por sitio es el que afecta). Si quieres monitorear el estado del índice de un sitio de 50 000 URLs, no puedes inspeccionarlas todas en un día; las procesas por lotes y las programas a lo largo de varios días, o priorizas. Pocas publicaciones hacen esta aritmética, y es la mayor restricción de planificación para el monitoreo de índices a gran escala.

Por el contrario, Search Analytics es generoso: 1 200 QPM por sitio y por usuario — y los otros recursos (Sitemaps, Sites) se sitúan en 20 QPS / 200 QPM por usuario. URL Inspection es el más restrictivo.

APIs de Sitemaps y Sites

La API de Sitemaps es la capa de gestión de tus sitemaps: “submits a sitemap for a site,” (traducción) «envía un sitemap para un sitio», “deletes a sitemap from this site,” (traducción) «elimina un sitemap de este sitio», “retrieves information about a specific sitemap,” (traducción) «recupera información sobre un sitemap específico» y “lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (traducción) «enumera las entradas de sitemaps enviadas para este sitio, o incluidas en el archivo de índice de sitemaps». El recurso de sitemap que devuelve incluye campos como path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors y un array contents, útil para auditar la salud de los sitemaps a escala.

La API de Sites enumera, agrega y elimina propiedades verificadas, útil si gestionas muchas propiedades y quieres aprovisionarlas o auditarlas mediante programación.

Cuándo usar la exportación masiva a BigQuery en su lugar

Para sitios grandes, el modelo de solo filas superiores y 25 000 filas por solicitud de la API se convierte en un techo. La respuesta de Google no es un quinto recurso de API que devuelva la misma forma de datos, sino una canalización de exportación programada separada: la exportación masiva de datos a BigQuery. Piensa en la elección como extracción (pull) frente a envío programado (push), no como “API A frente a API B”. El propio marco de Google: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (traducción) «Programa una exportación diaria de los datos de rendimiento de Search Console a BigQuery, donde puedes ejecutar consultas complejas sobre tus datos o exportarlos a un servicio de almacenamiento externo. Con la función de exportación masiva de datos, verás todos los datos de rendimiento disponibles para Search Console para tu propiedad, con la excepción de las consultas anonimizadas».

Esa es la regla de decisión:

• Exportación de la interfaz — ~1 000 filas, una mirada rápida y puntual.
• API de Search Analytics — hasta 25 000 filas/solicitud, paginación, programable; excelente para extracciones moderadas bajo demanda y paneles.
• Exportación masiva a BigQuery — todos los datos de rendimiento disponibles, a diario, sin límite de filas; la herramienta adecuada una vez que tienes decenas de miles de páginas o consultas.

Lo único que ninguno de ellos te ofrece son consultas anonimizadas: los términos que Google oculta por privacidad. Es una brecha real, no un error que puedas solucionar. Conozco la magnitud de primera mano: como Embajador de Marca de Ahrefs, ayudé a sacar a la luz un estudio en el que extrajimos todos los datos disponibles de la API en una muestra muy grande de sitios y descubrimos que Google oculta el término de búsqueda en una gran parte de los clics. Más tarde lo incorporamos a Ahrefs Rank Tracker: historial completo de tus datos de GSC, el porcentaje de clics que van a consultas anonimizadas y una curva de CTR personalizada basada en tus propios números. Cuando alguien te dice que la API devuelve “todos tus datos”, esa porción anonimizada es el asterisco honesto.

Casos de uso comunes

• Informes automatizados: extracciones programadas a Hojas de cálculo o un almacén de datos.
• Paneles de BI: Looker Studio o BigQuery sobre los datos de rendimiento.
• Monitoreo de indexación/cobertura a gran escala: URL Inspection, en lotes dentro de la cuota de 2 000/día.
• Creación de curvas de CTR: modela el CTR esperado por posición a partir de tus propios datos.
• Alertas de anomalías: detecta automáticamente caídas de clics/impresiones.

Así es también como funcionan las herramientas de terceros: cuando Ahrefs o un conector de Looker Studio “se integra con Search Console”, están llamando a estas mismas API (y cada vez más, a la exportación de BigQuery) en tu nombre.

Resumen de IA

Una versión condensada de la versión avanzada:

• La API de Search Console = cuatro API REST bajo webmaster-tools/v1: Search Analytics (datos de rendimiento), URL Inspection (estado de indexación), Sitemaps y Sites. No es una paridad total con la interfaz: algunas cosas, como la prueba en vivo de URL Inspection, solo existen en la interfaz, y el acceso a la API por sí solo no garantiza la indexación, los rankings ni el diagnóstico de tráfico.
• La autenticación es OAuth 2,0, sin clave de API. Dos alcances (webmasters, webmasters.readonly); cuentas de servicio para servidor a servidor, pero aún necesitan acceso explícito a la propiedad exacta. siteUrl acepta una propiedad de prefijo de URL o una propiedad de dominio sc-domain:example.com: haz que coincida con cómo está verificada. La API solo devuelve datos de las propiedades que has verificado: el error más común para principiantes.
• Search Analytics devuelve primero las filas principales, no un volcado completo: “does not guarantee to return all data rows but rather top ones”, independientemente de la paginación. Dentro de ese límite: 1–25 000 filas por solicitud (por defecto 1 000), frente a ~1 000 en la exportación de la interfaz, y las cuotas se dividen en límites de carga y límites de tasa de solicitudes QPS/QPM/QPD.
• URL Inspection: 2 000 consultas/día, 600/minuto por sitio, y solo informa de la versión indexada: no puede ejecutar una prueba en vivo. Esa cuota es la restricción real para el monitoreo de indexación a gran escala: procesa por lotes y programa en torno a ella.
• La API de Sitemaps lista/obtiene/envía/elimina sitemaps; la API de Sites lista/añade/elimina propiedades.
• Para sitios grandes, usa la exportación masiva de datos de BigQuery: una canalización programada separada (no un quinto recurso de API) que proporciona todos los datos de rendimiento disponibles a diario, sin límite de filas, excepto consultas anonimizadas.
• Las consultas anonimizadas son una brecha genuina que ninguna API o exportación cubre: el trabajo de Patrick en Ahrefs cuantificó cuán grande es esa porción oculta.

Documentación oficial

Documentación de fuente primaria de Google.

Referencia de la API de Search Console

• Descripción general de la API de Search Console — qué hace la API y el requisito de propiedad verificada.
• Search Analytics: referencia de consultas — los parámetros rowLimit (1–25 000) y de dimensión.
• Referencia de la API de inspección de URLs — qué datos de estado de indexación devuelve el método inspect.
• Referencia de la API de Sitemaps — listar, obtener, enviar, eliminar.
• Referencia de la API de Sites — listar, añadir, eliminar propiedades verificadas.
• Límites de uso — la tabla completa de cuotas por sitio, por usuario y por proyecto.
• Autorización de solicitudes (OAuth 2.0) — ámbitos y flujo de autenticación.

Exportación de datos masivos

• Acerca de la exportación de datos masivos (Ayuda de Search Console) — programa una exportación diaria de BigQuery de todos los datos de rendimiento, excepto las consultas anónimas.
• Anuncio de exportación de datos masivos (blog de Search Central) — la publicación de lanzamiento que posiciona la exportación masiva para sitios grandes.

Citas de la fuente

Declaraciones oficiales de la documentación de Google. Cada enlace es un enlace profundo que salta al pasaje citado en la página de origen.

Google — qué hace la API y quién puede usarla

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (traducción) «ver, añadir o eliminar propiedades y sitemaps, ejecutar consultas avanzadas para los datos de resultados de Google Search de las propiedades que gestionas en Search Console, y probar páginas individuales». — Documentación general de la API de Google Search Console. Ir a la cita
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (traducción) «Debes tener acceso adecuado (propietario, completo, lectura) a cualquier cuenta de Google Search Console a la que desees acceder mediante la API». — Documentación de la API de Google Search Console (Descripción general). Ir a la cita
• “All requests to the Google Search Console API must be authorized by an authenticated user.” (traducción) «Todas las solicitudes a la API de Google Search Console deben ser autorizadas por un usuario autenticado». — Guía de autorización de solicitudes. Ir a la cita

Google — API de Search Analytics

• “[Optional; Valid range is 1–25,000; Default is 1,000]” (traducción) «[Opcional; el rango válido es 1–25 000; el valor predeterminado es 1 000]» — el parámetro rowLimit. — Search Analytics: referencia de consultas. Ir a la cita
• “The URL of the property as defined in Search Console.” (traducción) «La URL de la propiedad tal como se define en Search Console» — el parámetro siteUrl, cuyos ejemplos dan tanto la forma de prefijo de URL (http://www.example.com/) como la forma de propiedad de dominio (sc-domain:example.com). — Search Analytics: referencia de consultas. Ir a la cita
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (traducción) «La API está limitada por las limitaciones internas de Search Console y no garantiza devolver todas las filas de datos, sino las principales». — Search Analytics: referencia de consultas. Ir a la cita

Google — API de inspección de URLs

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (traducción) «Ver el estado indexado, o indexable, de la URL proporcionada. Actualmente solo está disponible el estado de la versión en el índice de Google; no puedes probar la indexabilidad de una URL en vivo». — Referencia de la API de inspección de URLs. Ir a la cita

Google — API de Sitemaps

• “Submits a sitemap for a site.” (traducción) «Envía un sitemap para un sitio». / “Deletes a sitemap from this site.” (traducción) «Elimina un sitemap de este sitio». / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (traducción) «Enumera las entradas de sitemaps enviadas para este sitio o incluidas en el archivo de índice de sitemaps». — Referencia de la API de Sitemaps. Ir a la cita

Google — exportación masiva de datos

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (traducción) «Programa una exportación diaria de tus datos de rendimiento de Search Console a BigQuery… verás todos los datos de rendimiento disponibles para Search Console para tu propiedad, con la excepción de las consultas anonimizadas.» — Ayuda de Search Console: Acerca de la exportación masiva de datos. Ir a la cita

Configuración de OAuth y lista de verificación para la primera llamada

Pasar de cero a una llamada funcional a la API de Search Console:

• Confirma que tienes acceso verificado (propietario, completo o de lectura) a la propiedad en Search Console — la API no devuelve nada para propiedades no verificadas.
• Crea un proyecto en Google Cloud Console.
• Habilita la API de Search Console para ese proyecto.
• Crea credenciales: un cliente OAuth 2,0 (para aplicaciones interactivas/de usuario) o una cuenta de servicio (para automatización de servidor a servidor).
• Si usas una cuenta de servicio, concédele acceso a la propiedad en la configuración de Search Console.
• Solicita el ámbito correcto: webmasters.readonly para informes, webmasters si vas a enviar sitemaps o gestionar propiedades.
• Obtén un token de acceso mediante el flujo de OAuth (o la clave de la cuenta de servicio).
• Confirma que el formato de siteUrl coincide con cómo se verifica la propiedad: una URL completa para una propiedad de prefijo de URL, o sc-domain:example.com para una propiedad de dominio.
• Haz una llamada de prueba a searchAnalytics.query con un rango de fechas pequeño y rowLimit: 10 para confirmar que los datos regresan.
• Planifica en torno a las cuotas: las tasas de solicitud de Search Analytics son generosas, pero también consumen una cuota de carga separada; URL Inspection está limitada a 2 000/día, 600/min por sitio — procesa por lotes en consecuencia. No esperes que URL Inspection ejecute una prueba en vivo — eso es solo de la interfaz.
• Para decenas de miles de filas, configura la exportación masiva de BigQuery en lugar de paginar.

Los modelos mentales

1. Cuatro APIs, una autenticación. Search Analytics (lee tus datos de rendimiento), URL Inspection (lee el estado de indexación de una URL), Sitemaps (gestiona sitemaps), Sites (gestiona propiedades). Las cuatro pasan por la misma puerta de OAuth 2,0 y respetan la misma regla de propiedad verificada.

2. La escalera de escala de datos. Elige la herramienta según el volumen:

• Vistazo rápido → exportación de la interfaz (~1 000 filas).
• Programable, moderado → API de Search Analytics (hasta 25 000/solicitud, paginación).
• Sitio grande, completo → exportación masiva de BigQuery (todos los datos, diaria, sin límite de filas). Sube en la escalera cuando el escalón inferior deje de ajustarse a tus datos.

3. Filas principales, no todas las filas. Interioriza que la API devuelve “las principales”, no todo, y que las consultas anonimizadas están excluidas tanto de la API como de la exportación. Si la completitud importa, BigQuery está más cerca — pero la porción anonimizada se pierde independientemente.

4. Aritmética de cuotas antes de construir. Antes de diseñar un monitor de indexación, haz los cálculos: URL Inspection es 2 000/día por sitio. Un sitio de 50 000 URLs no puede inspeccionarse diariamente — así que procesa por lotes, prioriza o programa a lo largo de los días. Diseña en torno al límite, no lo descubras en producción.

Search Console API — hoja de referencia

Las cuatro APIs y sus límites clave

Autenticación

• Solo OAuth 2,0 — sin clave de API.
• Ámbitos: webmasters (lectura/escritura), webmasters.readonly (lectura).
• Cuentas de servicio para servidor a servidor (concédeles acceso a la propiedad).
• Solo las propiedades verificadas devuelven datos.

Datos rápidos

• La API devuelve solo filas principales — no se garantiza que estén completas — independientemente de la paginación.
• La exportación de la interfaz se limita a cerca de 1 000 filas; la API ofrece hasta 25 000/solicitud, pagina con startRow.
• Las cuotas de Search Analytics se dividen en límites de carga (basados en recursos, en bloques de 10 min / 1 día) y los límites de tasa de solicitud QPS/QPM/QPD anteriores.
• siteUrl acepta una propiedad de prefijo de URL (http://www.example.com/) o una propiedad de dominio (sc-domain:example.com) — haz coincidir cómo está verificada.
• URL Inspection informa solo la versión indexada — no puede ejecutar una prueba en vivo; eso es solo de interfaz.
• Las consultas anónimas se excluyen de la API y de la exportación de BigQuery.
• Para decenas de miles de filas → exportación masiva de datos de BigQuery — un pipeline programado separado, no un quinto recurso de API.
• Expone gran parte del informe de rendimiento (Search Analytics) y la herramienta URL Inspection, pero no es una paridad completa con la interfaz.

Una solicitud mínima de Search Analytics

Esto es ilustrativo, no listo para copiar y pegar — necesitarás configurar tus propias credenciales de OAuth y ajustar las fechas y la propiedad. Muestra la forma de una llamada searchAnalytics.query: el cuerpo de la solicitud con un rango de fechas, las dimensiones que quieras y el rowLimit.

El cuerpo de la solicitud (la parte que importa)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Bosquejo en Python (con la librería google-api-python-client)

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

Para ir más allá de 25 000 filas, haz un bucle e incrementa startRow en 25 000 hasta que una solicitud devuelva cero filas. Recuerda que el resultado sigue siendo “filas principales”, no un volcado completo — para eso, usa la exportación masiva de BigQuery.

Herramientas que usan (o envuelven) la API de Search Console

• Google Cloud Console — donde creas el proyecto, habilitas la API y generas las credenciales de OAuth/cuenta de servicio.
• Bibliotecas cliente oficiales — las bibliotecas cliente de la API de Google para Python, Java, JavaScript/Node, PHP y .NET envuelven las llamadas REST.
• BigQuery — el destino para la exportación masiva de datos; consulta todos tus datos de rendimiento con SQL.
• Looker Studio — se conecta a Search Console (y a BigQuery) para paneles construidos sobre los mismos datos.
• Ahrefs — integra la API de Search Console; su Rank Tracker muestra el historial completo de GSC, la proporción de clics que van a consultas anónimas y una curva de CTR personalizada a partir de tus propios datos.
• Interfaz de Search Console — el informe de rendimiento y la herramienta de inspección de URLs son las contrapartes manuales de las API de Search Analytics y de inspección de URLs, con una brecha que la API no puede cerrar: solo la herramienta de la interfaz puede ejecutar una prueba en vivo en una URL.

Indicaciones para planificar el trabajo con la API de Search Console

Usa estas indicaciones para dar forma a un código o a un plan de análisis. Mantén las credenciales, los tokens de actualización y las claves de cuenta de servicio fuera de cualquier entrada de chat.

Diseñar una solicitud de Search Analytics

Pega la URL de tu propiedad, el rango de fechas, las dimensiones, los filtros y el objetivo del informe.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Planificar un programa de inspección de URLs seguro para la cuota

Pega un resumen CSV o recuentos por prioridad de URL en lugar de tokens confidenciales.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

Elegir entre API y exportación a BigQuery

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Recursos que valen tu tiempo

Mi trabajo relacionado

• Blog de Ahrefs — mis publicaciones — incluido el trabajo sobre datos de GSC a escala y consultas anónimas.
• Ahora en Ahrefs Rank Tracker: historial completo de GSC + proporción de consultas anónimas — la función de curva de CTR e historial de GSC que anuncié.

Documentación de Google

• Descripción general de la API de Search Console y la página de límites de uso — las dos páginas que debes marcar primero.
• Acerca de la exportación masiva de datos — cuándo y cómo migrar a BigQuery.

De otros

• Palabras clave ocultas en GSC — el estudio de Ahrefs (cobertura de Search Engine Journal) — artículo de terceros sobre los hallazgos de consultas anónimas.
• Análisis mejorado de Search Console con BigQuery (SEJ) — una mirada práctica a la ruta de exportación masiva.
• Exportación masiva de datos: una forma nueva y potente de acceder a tus datos de Search Console (blog de Google Search Central) — la publicación de lanzamiento de febrero de 2023 del equipo de Search Console que posiciona la exportación masiva para sitios grandes.
• google-api-python-client (PyPI) — la biblioteca cliente oficial de Python utilizada para llamar a la API de Search Console; también disponible para Node, Java, PHP y .NET a través de la familia de bibliotecas cliente de las API de Google.
• r/TechSEO — la comunidad para solucionar problemas de API y extracción de datos.

Estadísticas que vale la pena citar

• Límite de filas de Search Analytics: 25 000 por solicitud (por defecto 1 000) — frente al límite de ~1 000 filas de la exportación de la interfaz. Esta es la razón principal para usar la API. Fuente
• Cuota de URL Inspection: 2 000 consultas/día y 600/minuto por sitio — el límite máximo para el monitoreo de índices a gran escala (10M/día, 15 000/minuto por proyecto). Fuente
• Las consultas anonimizadas están excluidas incluso de la ruta más completa (exportación masiva de BigQuery) — una brecha real e inevitable en tus datos de consultas. Fuente
• Google oculta el término de la palabra clave en una gran parte de los clics — del estudio de Ahrefs que ayudé a sacar a la luz, que extrajo todos los datos disponibles de la API en una muestra muy grande de sitios. Cobertura

Ponte a prueba: API de Search Console

Cinco preguntas rápidas sobre las API, la autenticación, los límites de datos y la escala. Elige una respuesta para cada una y luego comprueba tu resultado.

Registro de cambios