AI SEO In Detail

AI SEO In Detail › Módulo A · Fundamentos › Episodio 4

Episodio 4 · 6:25 · gratis

API de Google Search Console: extrae tus propios datos

Usa la API de Google Search Console para extraer todas las consultas y páginas de tu sitio, más allá de los límites de la interfaz, con una cuenta de servicio y un kit Python gratuito.

Al reproducir el vídeo se carga desde YouTube (modo de privacidad mejorada). El vídeo está en inglés con subtítulos en tu idioma.

Script gratuito

Script de extracción diaria de Search Console + esquema SQLite

gsc_pull.py + schema.sql: extrae cada fila de tus datos de Google Search Console a través de la API, día a día, hacia SQLite. Cuenta de servicio mediante una variable de entorno, tres extracciones al día, paginación completa más allá de 25 000 filas, caché JSON sin procesar y un upsert que nunca duplica un día.

  • Crea una cuenta de servicio — Activa la API de Search Console en un proyecto de Google Cloud, descarga la clave JSON de la cuenta de servicio en tu carpeta personal y añade su dirección como usuario restringido en tu propiedad.
  • Indica la clave al script — Define GSC_KEY_FILE con la ruta de la clave y GSC_SITE con tu propiedad. Ejecuta el selftest y después la extracción: fecha, fecha + página y fecha + página + consulta, todas las filas, en caché y con upsert.
  • Comprueba una vez y luego programa — Compara un día completo con la interfaz usando el comando check y después ejecútalo a diario: vuelve a extraer los últimos cinco días para que las cifras recientes se estabilicen y el histórico siga creciendo.
Descargar el script + el esquema (zip)

Python 3.9+ · SQLite · sin claves incluidas · sin registro

Los archivos están en inglés.

Transcripción completa (traducida)

1,186 palabras · traducción de la narración del episodio.

Introducción

El botón de exportar de Search Console te da mil filas. Si tu sitio tiene más consultas, el resto simplemente no está en el archivo.

Y Search Console solo guarda unos dieciséis meses de historial. Todo lo anterior desaparece, salvo que lo hayas guardado.

Ambos problemas tienen la misma solución: extraer los datos tú mismo, por la API, cada día, a tu propia base de datos. En este episodio haremos justo eso con uno de mis propios sitios. Configuramos el acceso con una cuenta de servicio, escribimos la consulta, paginamos todas las filas y las guardamos para no volver a perder el historial.

Acceso: una cuenta de servicio

Acceso: una cuenta de servicio

Para llamar a la API desde un script, necesitas una identidad que no seas tú. Eso es una cuenta de servicio: un usuario robot en Google Cloud.

Tres pasos. Crea un proyecto en Google Cloud y activa en él la Search Console API. Crea una cuenta de servicio y descarga su clave, que es un archivo JSON. Luego ve a Search Console, abre la configuración de usuarios de tu propiedad y añade el email de la cuenta de servicio como usuario.

¿Qué permiso? Restringido basta para leer datos. Dale el acceso mínimo que funcione. Y usa el scope de solo lectura en tu script, así ni un bug puede cambiar nada.

¿Dónde va la clave? La misma regla que en el episodio anterior. Fuera de la carpeta del proyecto, legible solo por ti. Yo guardo una clave en mi carpeta personal, y el script la encuentra con una variable de entorno.

Una cuenta se puede añadir a muchas propiedades. Uso una cuenta de servicio para todos mis sitios, así un script lo extrae todo.

La consulta: dimensiones y filtros

La consulta: dimensiones y filtros

El método que usarás para casi todo se llama search analytics query. Le das un rango de fechas, una lista de dimensiones y, opcionalmente, filtros.

Las dimensiones son cómo se dividen los datos. Date, page, query, country, device y search appearance. Eliges la combinación y obtienes una fila por combinación con clics, impresiones, CTR y posición.

Aquí va la primera sorpresa. Las dimensiones que eliges cambian los totales. Si pides solo la fecha, Google cuenta por sitio y obtienes el total completo. Añade la dimensión page y cuenta por página. Añade también query y se eliminan filas por privacidad.

Aquí tienes un día en uno de mis sitios. Antes, una nota rápida: los datos son reales, directos de la Search Console API, pero anonimizados. El dominio, las URLs de página y los términos de búsqueda están reemplazados, para centrarnos en los principios y no en las keywords. Los números están intactos.

La extracción solo por fecha da trescientos cincuenta clics ese día. Suma las filas de query y page del mismo día y salen unos sesenta. Mismo sitio, mismo día. No es un bug de tu script. El episodio nueve lo explica todo.

Mi regla práctica: guarda dos extracciones separadas. Una por fecha y página, que te da los totales completos por página. Y otra por fecha, página y query, para el detalle.

Límites de filas y paginación

Cada llamada devuelve como máximo veinticinco mil filas. Si hay más, vuelves a pedir con un desplazamiento startRow, veinticinco mil, luego cincuenta mil, y así hasta que una llamada vuelva vacía.

Así se ve en mi propio sitio, seis días seguidos.

Cada barra es un día de filas de query y page. La línea es el límite de exportación de mil filas. Cada día queda entre unas cuatro mil setecientas y seis mil doscientas filas. Eso es de cinco a seis veces el límite. Todo lo que está sobre la línea son datos que nunca verías con el botón de exportar.

Extrae un día cada vez. Así cada llamada es pequeña y la tarea diaria es sencilla: entra una fecha, salen todas las filas.

Incluso con paginación, la API no te dará todas las consultas. Las consultas muy raras y las que Google considera privadas se excluyen. En el episodio nueve verás cuánto puede ser en este mismo sitio.

Retraso de los datos y datos recientes

Retraso de los datos y datos recientes

Los datos de Search Console no son en tiempo real. Los últimos dos o tres días suelen faltar o estar incompletos. La API puede devolver datos más recientes y preliminares si los pides, pero esos números aún pueden cambiar.

Así que, para el guardado diario, hago dos cosas. Extraigo una fecha de hace unos días, cuando ya es definitiva. Y en la siguiente ejecución vuelvo a extraer los últimos días y los sobrescribo. Nunca tomes los números de ayer en Search Console como la respuesta final.

Al comparar periodos, compara solo días completos. Una semana que acaba ayer siempre parecerá una caída.

Almacenar las extracciones diarias

Almacenar las extracciones diarias

Ahora a guardarlo. Uso SQLite: un archivo, sin servidor, y bastante rápido para millones de filas. Montamos todo el espacio de trabajo en el episodio seis.

Dos tablas, una por cada extracción. Una fila por fecha y página. Una fila por fecha, página y query. La fecha más las otras dimensiones forman la clave, así que si extraes el mismo día dos veces, la fila nueva reemplaza a la antigua en vez de duplicarla.

Guarda también la respuesta en bruto como JSON, como hicimos con DFS. Esta vez los datos son gratis, pero la caché te sigue protegiendo de bugs en tu parseo.

Luego prográmalo. Una tarea diaria que extrae los últimos cinco días y hace upsert. Cuando lleve un año funcionando, tendrás un historial que Search Console ya no te muestra.

Errores habituales

Tres cosas que confunden a la gente.

Tipo de propiedad. Una de dominio cubre todos los subdominios y protocolos. Una propiedad de prefijo de URL cubre solo ese prefijo. Asegúrate de que el script consulta la misma propiedad que ves en la interfaz.

La posición es un promedio, y los promedios ocultan mucho. El episodio ocho trata de cómo leerla bien.

Y no uses el informe de sitemaps de la API para juzgar la indexación. Su cifra "indexed" ha resultado poco fiable en mis propias mediciones. Para el estado de indexación, usa URL Inspection, al que volveremos en el episodio diecisiete.

Comprobaciones de coherencia de la primera extracción

Antes de construir nada sobre los datos, compáralos una vez con la interfaz. Elige un día completo. Aquí está esa comprobación en mi propio sitio.

La extracción solo por fecha debe coincidir con el total de la interfaz ese día, o acercarse mucho. Igual que la suma de tu extracción por página. Si no, probablemente consultas otra propiedad, otro tipo de búsqueda o un día que aún no es definitivo.

La extracción por query será menor. Aquí son unos sesenta clics de trescientos cincuenta. No te asustes por esa diferencia. Son las consultas ocultas de las que acabamos de hablar.

Luego revisa el número de filas por día, como en el gráfico de antes. Un día de repente con muchas menos filas, con clics normales, suele indicar un bug de paginación, no un evento SEO. Diez minutos de comprobación ahora te evitan un gráfico erróneo durante un año.

Resumen final

Una cuenta de servicio, dos extracciones al día, paginación y una base de datos que conserva tu historial. El script y el esquema están enlazados en la descripción. Próximo episodio: unir Analytics, Search Console y DFS en un modelo de datos. Nos vemos allí.