chemavx-seo-tools/MANUAL-GSC.md

El marcador — Search Console (seo_gsc.py)

Lo que faltaba en toda la caja de herramientas: datos de resultado. El resto mira hacia dentro (enlaces, sitemap, reglas de metas); esto mira lo único que decide si el trabajo sirvió — cuánta gente nos encuentra y cuánta pincha.

Es de solo lectura. No escribe en los blogs ni en Search Console.

Puesta en marcha (cuatro pasos de navegador, una sola vez)

La API es gratis. Hace falta una cuenta de servicio, no OAuth: en esta máquina no hay navegador y el flujo interactivo no funciona headless — la misma piedra con la que ya tropezamos en Gemini.

1. Proyecto y API. En https://console.cloud.google.com crea un proyecto (o reutiliza uno) y activa Google Search Console API en APIs y servicios → Biblioteca.

2. Cuenta de servicio. IAM y administración → Cuentas de servicio → Crear. No necesita ningún rol de IAM: el permiso que importa se da en el paso 4. Luego Claves → Añadir clave → Crear nueva → JSON y descarga el fichero.

3. La clave, en su sitio. En esta máquina:

   mkdir -p ~/.config/gsc
   mv ~/Descargas/EL-FICHERO.json ~/.config/gsc/service-account.json
   chmod 600 ~/.config/gsc/service-account.json
   

   La herramienta se niega a arrancar si el fichero es legible por otros. Está fuera de cualquier repo; no la metas en git.

4. Permiso en Search Console. Este es el paso que se olvida. Para cada una de las dos propiedades (theexclusionzone.com y zonadeexclusion.com): Configuración → Usuarios y permisos → Añadir usuario → pega el client_email de la credencial (algo como nombre@proyecto.iam.gserviceaccount.com) → permiso Restringido, que basta para leer.

   ⚠️ Si zonadeexclusion.com no está dada de alta en Search Console, hay que verificarla antes. Del blog ES no había ni una sola exportación, así que es probable que ni exista la propiedad.

5. Arrancar el vigilante. El timer se instala parado a propósito: sin credencial fallaría cada lunes, y un timer que falla siempre enseña a ignorar los avisos. Se enciende cuando el canario pasa:

   seo-gsc comprueba && sudo systemctl enable --now seo-gsc-watch.timer
   

Comprobación:

seo-gsc sitios        # tienen que salir las dos propiedades
seo-gsc comprueba     # canario: recorre el camino real eslabón por eslabón

Si el nombre que devuelve sitios no coincide con el configurado (puede ser sc-domain:x.com o https://www.x.com/, con barra final), corrige el diccionario SITIOS en seo_gsc.py con el nombre exacto.

Es lo que pasó al estrenarlo: las dos propiedades no son del mismo tipo. EN es de dominio y ES es de prefijo de URL (https://zonadeexclusion.com/), que solo ve lo que cuelga de ese prefijo exacto — ni www, ni http. Sirve porque el canónico del ES es el apex, pero si algún día se publica bajo www no aparecería aquí. Darla de alta como propiedad de dominio lo arreglaría de raíz.

Uso diario

seo-gsc pull          # descarga y acumula en SQLite (idempotente)
seo-gsc               # sin argumentos = informe de 28 días
seo-gsc informe --dias 7

La primera descarga pide 16 meses, que es todo lo que Google guarda, pero lo que llega es lo que haya. Medido el 2026-07-28: el dato más antiguo es del 2026-05-09 en las dos propiedades, porque se dieron de alta entonces. Google no guarda nada de antes de que exista la propiedad, así que no hay histórico anterior a mayo de 2026 y nunca lo habrá. Cuidado con leer «16 meses» y creer que se puede comparar contra el año pasado.

La pregunta pendiente

El remate de metas fue el 23 de junio y los únicos datos que había eran del 17. En cuanto haya credencial:

seo-gsc antes-despues --corte 2026-06-23 --dias 28

Qué mira el informe

• Movimiento de clics, impresiones y CTR contra el periodo anterior.
• Páginas que posicionan y no se pinchan. Es la lista que importa: si algo está en posición 6 con 2.400 impresiones y 0,16% de CTR, no tiene un problema de posicionamiento, tiene un problema de titular. Cada línea estima los clics que faltan si el CTR fuese el normal de esa posición.
• Consultas con impresiones y cero clics, que son temas donde ya salimos y no convencemos.

El CTR "normal" sale de una curva de referencia del sector, no de una medición nuestra: sirve para ordenar candidatas, no para prometer tráfico. Solo se avisa por encima de 150 impresiones, porque por debajo el CTR es ruido.

Automático

seo-gsc-watch.timer — lunes 06:15 UTC: descarga y manda el informe por Telegram, pero solo si hay páginas desperdiciadas y el informe ha cambiado desde el último aviso. Misma disciplina que seo-watch: si no hay nada que decir, se calla.

systemctl status seo-gsc-watch.timer
journalctl -u seo-gsc-watch -n 40

Notas de implementación

• Sin librerías de Google. El JWT se firma con PyJWT y se canjea a mano. Son treinta líneas y evita arrastrar media docena de dependencias para tres peticiones.
• Los datos tardan 2-3 días en consolidarse. Todo termina 3 días atrás y se pide dataState=final; pedir "ayer" devuelve cifras que luego cambian solas.
• La posición se pondera por impresiones. Promediar posiciones a pelo da el mismo peso a un día de 2 impresiones que a uno de 500.
• La API pagina de 25.000 en 25.000 y no avisa de que quedan más filas.
• El almacén es SQLite en ~/.local/state/seo-gsc/gsc.db; pull es idempotente y resolapa un día por si el último se consolidó después.