Search Console: API, BigQuery y análisis SEO

A escala, Search Console plantea un problema de contrato de datos: interfaz, API y exportación masiva difieren en cobertura, histórico y mantenimiento. Elegir mal la fuente deja incompleto incluso un análisis con SQL correcto.

Usa la interfaz para investigar y formular la pregunta; la API, para extracciones filtradas y repetibles; la exportación masiva, para conservar y cruzar datos diarios. Decide la fuente antes de diseñar el almacén.

La guía presupone una propiedad verificada y familiaridad con clics, impresiones, CTR y posición media. La guía práctica de Google Search Console cubre la configuración. Aquí tratamos la extracción, la calidad y el análisis a escala.

Escoge la superficie más pequeña que responda a la pregunta

Empieza por la interfaz cuando el siguiente paso dependa de una revisión humana: localizar una caída por dispositivo, comparar una página o probar un filtro. Revisa allí las anotaciones antes de extraer. La tabla de rendimiento muestra un máximo de 1.000 filas, mientras que los totales pueden incluir registros que no aparecen en ella (explicación de Google sobre los datos de Search Console). No es una base de datos completa.

Pasa a la API para repetir una pregunta sobre páginas y consultas fijas o recuperar fechas anteriores a la exportación masiva. Los filtros y la agregación quedan en código para que otro analista pueda revisarlos.

Elige la exportación masiva cuando importen más la cobertura y la continuidad que la comodidad. Search Console la define como una exportación diaria de datos de rendimiento a BigQuery e indica que facilita todos los datos de rendimiento disponibles salvo las consultas anonimizadas. No revela el texto de las consultas protegidas por privacidad (documentación de la exportación masiva de Search Console). El resultado supera las filas principales de la interfaz o la API y queda bajo control de la organización.

En una web pequeña pueden bastar un script versionado y una tabla. Varias propiedades, cruces e histórico superan pronto las hojas de cálculo. La escala depende también del trabajo repetido.

Lee las cifras como observaciones agregadas

Search Console entrega datos agregados, no un registro de eventos sin procesar. Sus informes agrupan por propiedad o página, y la API reúne en una fila todos los valores que comparten las dimensiones elegidas (documentación sobre agregación y referencia de Search Analytics). Al cambiar las dimensiones cambia la granularidad; por eso, unir extracciones distintas sin respetarla puede duplicar rendimiento.

Las fechas requieren cuidado. Search Console etiqueta el rendimiento diario según la hora del Pacífico y la API espera el intervalo de fechas en esa misma zona. Google señala que los datos recopilados suelen estar disponibles al cabo de dos o tres días, aunque publica actualizaciones a intervalos (información oficial sobre los datos de Search Console). El parámetro dataState de la API puede incluir datos recientes y preliminares cuando vale all; si se omite, devuelve datos definitivos (referencia de la consulta de Search Analytics). Una canalización diaria debe guardar si aceptó filas preliminares y si después las sustituyó.

La protección de la privacidad explica otra discrepancia aparente. Las consultas raras o sensibles pueden anonimizarse y sus métricas contar en el gráfico aunque no aparezca el texto (datos de Search Console). Aplicar un filtro de consulta también puede cambiar el cálculo de esos totales. En la exportación masiva, is_anonymized_query identifica esas filas y el campo de consulta queda vacío. Así puedes conservar sus clics e impresiones agregados sin fingir que conoces los términos (referencia de tablas de la exportación masiva).

Publica las consultas identificadas como subtotal, no como “todas las consultas”, y no atribuyas la diferencia a un tema inventado. Usa la agregación de propiedad para ese nivel y la tabla de URL para las páginas; si muestras ambas, sepáralas y documenta su granularidad.

La posición media es ponderada, no la media aritmética de los promedios de cada fila. En la exportación masiva, la posición de propiedad se calcula con SUM(sum_top_position) / SUM(impressions) + 1; para URL se aplica la misma fórmula con sum_position. La referencia de Google define ambos campos como sumas con base cero (referencia de tablas de la exportación masiva). Si vuelves a promediar valores ya promediados, las filas con muchas y pocas impresiones pesan lo mismo y el resultado es incorrecto.

Pagina la API sin confundir alcance con integridad

El endpoint de Search Analytics admite intervalo de fechas, dimensiones, filtros, tipo de búsqueda, tipo de agregación y estado de los datos. Cada respuesta puede contener hasta 25.000 filas; startRow define el desplazamiento desde cero para paginar (referencia de la consulta de Search Analytics). Un extractor sólido solicita el tamaño máximo de página, incrementa el desplazamiento según las filas recibidas y termina cuando la respuesta queda vacía o devuelve menos registros que el máximo.

Ese bucle no convierte la fuente en completa. Google documenta otro límite: Search Analytics expone como máximo 50.000 filas al día y por tipo de búsqueda, ordenadas por clics. Agrupar en detalle por página o consulta puede perder datos incluso antes de llegar a ese techo (cómo obtener los datos de rendimiento). La paginación recupera las filas principales disponibles; no puede obtener las que el servicio nunca expone.

Para extraer sin perder el control:

1. Consulta un día y un tipo de búsqueda si importa la cobertura.
2. Guarda petición, propiedad, hora y dataState.
3. Pagina con rowLimit: 25000 y aumenta startRow.
4. Detente ante una página corta y marca como truncable cualquier día con 50.000 filas.
5. Sustituye de forma idempotente las fechas preliminares cuando sean definitivas.
6. Separa los totales de propiedad del detalle página-consulta.

Search Analytics aplica cuotas de carga diarias y a corto plazo cuya capacidad numérica Google no publica; los intervalos amplios y las agrupaciones o filtros simultáneos por página y consulta consumen más carga. También fija cuotas de 1.200 consultas por minuto y sitio, 1.200 por minuto y usuario, y 40.000 por minuto más 30.000.000 al día y proyecto (límites de uso de la API de Search Console). Una sola consulta costosa puede agotar un límite de carga mucho antes de que importe el recuento de solicitudes.

Divide por fechas y guarda en caché los periodos definitivos. Reintenta con retroceso exponencial, tope y alerta. Separa horarios si varios clientes comparten proyecto y mantén OAuth en solo lectura.

La API sirve de puente para el histórico porque la exportación masiva nativa solo mira hacia delante. Google indica que la primera exportación incluye los datos del día en que se inicia y recomienda usar la API o los informes para las fechas anteriores (guía de configuración de la exportación masiva). Guarda los datos recuperados por API con su fuente y sus marcas de cobertura. No los unas en silencio a las filas de la exportación como si ambos canales ofrecieran la misma integridad.

Decide propiedad y ubicación antes de activar la exportación

La exportación masiva necesita un proyecto de Google Cloud con facturación activa, además de las API de BigQuery y BigQuery Storage. La cuenta de servicio [email protected] debe tener los roles BigQuery Job User y BigQuery Data Editor en ese proyecto. La persona que inicie la exportación tiene que ser propietaria de la propiedad de Search Console (pasos oficiales de configuración).

Como esos roles son amplios, asigna un responsable y revisa IAM periódicamente. Separa la cuenta de servicio que escribe los datos de Search Console de las identidades que los consultan. Da a los analistas acceso al conjunto de datos o a vistas aprobadas según su función; no compartas permisos de propietario del proyecto. Los trabajos de consulta necesitan permiso para crear un trabajo de BigQuery y permiso para leer los datos correspondientes (documentación para ejecutar consultas).

Escoge la ubicación del conjunto de datos antes de activarlo. Search Console lo crea durante la primera exportación y no permite cambiar su ubicación de forma nativa después. En un trabajo de una sola ubicación, todos los conjuntos de datos leídos o escritos deben coincidir con la ubicación del trabajo; BigQuery devuelve un error si especificas otra. Una reserva solo se usa cuando su ubicación coincide con la del trabajo y, si no hay una compatible, se factura bajo demanda. Ambas reglas exceptúan las consultas globales (ubicaciones de BigQuery).

Las consultas globales están en vista previa y permiten leer datos de varias regiones (documentación de consultas globales). Hay que habilitar su ejecución en la región y proyecto que consulta, habilitar el acceso a datos en cada región y proyecto remoto, y conceder bigquery.jobs.createGlobalQuery (requisitos oficiales). BigQuery copia temporalmente los datos remotos a una ubicación principal; el coste suma el cómputo remoto y final, la copia entre ubicaciones y 24 horas de almacenamiento temporal. La transferencia entre regiones también añade latencia y las consultas globales no funcionan con endpoints regionales. Por eso conviene elegir desde el principio una ubicación compatible con residencia, cruces y reservas. EU y una región europea concreta no son intercambiables (ubicaciones de BigQuery).

Antes de activarlo, comprueba estos puntos (guía de configuración de la exportación):

• el ID correcto del proyecto de Google Cloud, no su número, y las API necesarias activadas;
• responsable de facturación, presupuesto y centro de coste;
• identidad exportadora con sus dos roles obligatorios;
• un nombre de conjunto de datos que empiece por searchconsole y sea único si el proyecto aloja varias propiedades;
• ubicación compatible con el resto de datos;
• propietario que active la exportación y responsable de comprobar entregas y fallos.

La primera exportación puede tardar hasta 48 horas tras configurar todo correctamente y no recupera datos anteriores. Una vez creadas las tablas, Search Console aconseja no alterar su esquema y recomienda un mínimo de 14 días si configuras la caducidad de particiones, pues un periodo menor puede impedir nuevas escrituras (guía de configuración de la exportación masiva). Si el objetivo del almacén es conservar histórico, una caducidad agresiva contradice el diseño.

Entiende las tres tablas antes de escribir SQL

El conjunto de datos predeterminado searchconsole contiene tres tablas (referencia de tablas):

• searchdata_site_impression, con rendimiento agregado a nivel de propiedad;
• searchdata_url_impression, que añade la URL de destino al nivel de detalle;
• ExportLog, que registra las escrituras correctas en las dos tablas de rendimiento.

Las dos tablas de rendimiento se particionan por data_date. Entre sus dimensiones están la propiedad, consulta, país, tipo de búsqueda y dispositivo; la tabla de URL incorpora además url y marcas de aparición en búsqueda. ExportLog contiene la fecha de los datos, el espacio de nombres de destino, la hora de publicación y un epoch_version que aumenta si Search Console revisa después una fecha (referencia de tablas de la exportación masiva).

Las filas no tienen garantizada la consolidación por fecha ni por ninguna otra clave. Por tanto, cada consulta analítica debe agregar clics, impresiones y sumas de posición aunque las dimensiones elegidas parezcan únicas. Google lo exige de forma expresa en sus directrices para consultar la exportación masiva.

Este patrón parametrizado devuelve rendimiento por URL para consultas web identificadas y acota el intervalo de particiones por fecha:

SELECT
  data_date,
  url,
  query,
  SUM(clicks) AS clicks,
  SUM(impressions) AS impressions,
  SAFE_DIVIDE(SUM(clicks), SUM(impressions)) AS ctr,
  SAFE_DIVIDE(SUM(sum_position), SUM(impressions)) + 1 AS avg_position
FROM `your-project.searchconsole.searchdata_url_impression`
WHERE data_date BETWEEN @start_date AND @end_date
  AND search_type = 'WEB'
  AND NOT is_anonymized_query
GROUP BY data_date, url, query;

El filtro de partición debe estar en la consulta base, no en una capa del panel que primero lea la tabla completa. Selecciona solo las columnas necesarias. BigQuery documenta que la poda de particiones reduce los datos examinados, mientras que SELECT * y las columnas innecesarias elevan el procesamiento (prácticas de cálculo de BigQuery). LIMIT cambia el número de filas devueltas, pero no reduce los bytes leídos en una tabla no agrupada.

Crea una capa de modelado compartida. Separa los totales definitivos del detalle consulta-URL y sus marcas de cobertura. Relaciona la fecha del Pacífico con la del informe y conserva intactas las tablas originales.

Integra el control de costes en la ruta de consulta

BigQuery ofrece análisis bajo demanda, facturado por bytes procesados, y análisis por capacidad, facturado mediante capacidad reservada. El almacenamiento se cobra por separado. El modelo y el precio adecuados dependen de la ubicación, la carga y las condiciones de la cuenta; dar una cifra universal por consulta resultaría engañoso. Contrasta la página oficial de precios de BigQuery con la región y el modelo de facturación escogidos.

Antes de ejecutar:

• previsualiza las tablas cuando baste con conocer su forma;
• acota data_date y selecciona columnas concretas;
• estima bytes con una prueba o el validador;
• fija maximum bytes billed en trabajos bajo demanda;
• materializa transformaciones reutilizadas;
• etiqueta los trabajos y revisa bytes, fallos y slots por responsable.

La guía de costes de Google confirma que las ejecuciones de prueba estiman los bytes y que un límite máximo de bytes rechaza una consulta antes de generar un cargo si la estimación lo supera. También advierte de que LIMIT no controla el coste en tablas no agrupadas (prácticas de control de costes de BigQuery). Estas barreras funcionan mejor que una previsión mensual fija, porque tanto el volumen de datos como la mezcla de consultas cambiarán.

Cada consulta programada necesita responsable, destino, hora límite y alerta. Un cero puede ser un fallo de exportación, no de demanda. Muestra frescura e integridad en el panel.

Haz QA del dato antes de interpretar el SEO

Primero, usa ExportLog para confirmar que tanto searchdata_site_impression como searchdata_url_impression se completaron en cada fecha esperada. Pueden llegar en momentos distintos. El registro refleja escrituras correctas, no intentos fallidos. Search Console reintenta las fechas omitidas durante aproximadamente una semana. Tras alrededor de un mes de intentos fallidos puede detener por completo la exportación. Los propietarios y usuarios completos reciben mensajes cuando se produce o se corrige un error de exportación (guía para monitorizar la exportación masiva).

Compara una fecha cerrada con una referencia estable. Una diferencia puede proceder del estado del dato, filas anonimizadas, agregación, tipo de búsqueda, zona horaria o correcciones tardías. Documenta las decisiones y, si cambia epoch_version, reconstruye las filas derivadas.

Separa los invariantes del contrato de las pruebas que dependen de tu modelo. Google exige agregar las métricas antes de calcularlas: el CTR sale de SUM(clicks) / SUM(impressions) y la posición media pondera las sumas de posición (directrices de consulta). Un informe de consultas identificadas debe excluir is_anonymized_query; uno de totales debe conservar esas filas (referencia de tablas). Estas comprobaciones sí pueden bloquear una publicación.

Alerta sobre fechas futuras, recuentos negativos, dimensiones desconocidas y URL sin correspondencia. Investiga los clics superiores a impresiones sin declararlo invariante antes de validar agregación y modelo. Pon en cuarentena lo dudoso: el umbral detecta cambios, pero depende del esquema.

Prueba aparte las clasificaciones de negocio y dales fecha de vigencia si pueden cambiar. La guía sobre observabilidad SEO y CI/CD ayuda a asignar responsables; la guía de medición SEO con GA4 cubre qué sucede después del clic.

Análisis que justifican el almacén de datos

BigQuery compensa cuando resuelve una decisión que la interfaz o una extracción acotada no cubren bien.

Estabilidad de consulta y URL

Cuenta cada semana las URL de destino por consulta y revisa cambios repetidos de la principal. Puede señalar competencia interna, migraciones o cambios de intención, pero no prueba canibalización: sitelinks, varios resultados útiles y pocas impresiones requieren revisión manual.

Cohortes de lanzamiento

Cruza publicación y URL de Search Console. Compara ventanas equivalentes por país, dispositivo y tipo de página, con la estacionalidad y los cambios del sitio visibles. La cohorte muestra si las páginas entraron en las consultas previstas; no atribuye todos los clics al lanzamiento.

Tendencias de marca y no marca

Aplica una expresión regular versionada con las grafías verificadas, sin distinguir mayúsculas. Separa el rendimiento anonimizado. Registra la versión del clasificador y revisa falsos positivos cuando cambien productos o nombres de mercado.

Colas de oportunidades

Materializa páginas con impresiones sostenidas, posición estable y CTR inferior al de páginas comparables. Evita umbrales universales: SERP, marca, país, dispositivo e intención cambian el clic.

Diagnóstico internacional

Asigna cada URL a su idioma previsto y compara grupos de país, dispositivo y consulta. La dimensión de país agrupa por el país donde se originó la búsqueda (documentación de dimensiones de Search Console). Como interpretación analítica, ese campo no basta para deducir el idioma ni la residencia del usuario. Úsalo para revisar hreflang, localización y demanda, y valida después la implementación con la guía de SEO internacional.

Apoyo para atribuir cambios

Cruza despliegues, redirecciones, ediciones de contenido e incidencias con el rendimiento diario. Una anotación acota la investigación, pero no prueba causalidad. El marco de forecasting SEO por impacto, confianza y esfuerzo ayuda a separar el impacto medido de la confianza y el coste de implementación.

Decide la siguiente implementación con cuatro preguntas

1. ¿Es exploratorio o recurrente? Explora en la interfaz; automatiza cuando entiendas dimensiones y decisión.
2. ¿Las filas ausentes cambiarían la decisión? Si no, puede bastar la API. Si sí, activa pronto la exportación: no es retroactiva.
3. ¿Necesitas cruces, histórico o reglas compartidas? Favorecen BigQuery y una capa gobernada.
4. ¿Puede mantenerlo el equipo? Asigna IAM, facturación, monitorización, transformaciones, QA y métricas; si faltan, reduce el alcance.

Empieza pequeño: activa la exportación en la ubicación correcta, comprueba las tablas y ExportLog, modela un día con filtro de partición, concilia una semana y publica un análisis con notas de cobertura. Añade clasificaciones y cruces cuando funcione de extremo a extremo.

Exige criterios observables: dos registros correctos por fecha, estados preliminar y definitivo separados, filtro de partición en producción, límites de bytes y responsables, totales identificados como incompletos y última fecha correcta visible. Escalar significa reproducir una decisión sin redescubrir las reglas.

Preguntas frecuentes

¿La API de Search Console es más completa que la interfaz?

Puede devolver más filas y permite repetir filtros, dimensiones y paginación, pero sigue sujeta a los límites internos de Search Console. La API de Search Analytics expone como máximo 50.000 filas diarias por tipo de búsqueda y devuelve las filas principales, no un conjunto de consultas cuya integridad esté garantizada. La exportación masiva encaja mejor cuando necesitas un conjunto de datos continuo y más completo.

¿La exportación masiva a BigQuery incluye las consultas anonimizadas?

No revela el texto de las consultas protegidas por privacidad. Los datos exportados pueden contener filas anonimizadas, identificadas mediante una marca y con el valor de consulta vacío. Sus clics e impresiones cuentan en los totales, pero no se convierten en términos de búsqueda utilizables. No interpretes la suma de consultas con nombre como toda la demanda de búsqueda.

¿Puedo recuperar datos antiguos de Search Console en BigQuery?

La exportación masiva nativa empieza con los datos del día en que se inicia y no recupera fechas anteriores. Para el histórico puedes usar la API de Search Analytics o exportaciones guardadas, dentro de su disponibilidad y límites. Conserva esa recuperación separada o normalízala con cuidado, porque la cobertura de la API y la exportación masiva puede ser distinta.

¿Cómo mantengo bajo control el coste de las consultas de Search Console en BigQuery?

Filtra la columna de fecha que particiona la tabla, selecciona solo las columnas necesarias, previsualiza las tablas o haz una ejecución de prueba de la consulta, limita los bytes facturados en trabajos bajo demanda y materializa las transformaciones que reutilices a menudo. LIMIT no reduce por sí solo los bytes leídos en una tabla no agrupada. Consulta el precio vigente para la ubicación y el modelo de facturación elegidos en vez de partir de una cifra fija.

¿Qué tabla de BigQuery debo usar para el análisis SEO?

Usa searchdata_site_impression para tendencias a nivel de propiedad y searchdata_url_impression cuando la URL de destino forme parte de la pregunta. Comprueba en ExportLog que las dos tablas de rendimiento se escribieron correctamente para cada fecha. No sumes las tablas de propiedad y URL: son vistas de agregación alternativas sobre el mismo rendimiento de búsqueda.

Empieza con un modelo de una semana cerrada

No empieces por los paneles. Activa la fuente, espera una semana cerrada y modela un día con zona horaria, tipo de búsqueda, anonimización y agregación explícitos. Responde una pregunta y pide a otro analista que reproduzca el resultado. Entonces sabrás si invertir en API, almacén o una vista guardada.