fn_registry/python/functions/datascience/pull_gsc_search_analytics.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
pull_gsc_search_analytics	function	py	datascience	1.0.0	impure	def pull_gsc_search_analytics(service: object, site_url: str, start_date: str, end_date: str, dimensions: list = None, row_limit: int = 25000, max_total_rows: int = 0, search_type: str = 'web') -> list	Extrae datos de la Search Analytics API de Google Search Console (GSC): impresiones, clicks, CTR y posicion por las dimensiones pedidas (query, page, date, country, device, searchAppearance). Recibe un objeto service GSC ya autenticado (el que devuelve gsc_auth, inyectado) y llama a service.searchanalytics().query(siteUrl, body).execute(). Pagina automaticamente con startRow en pasos de row_limit (tope duro 25000 filas/request) hasta que una pagina devuelve menos de row_limit filas o se alcanza max_total_rows. Aplana cada fila mapeando el array keys posicionalmente a los nombres de dimensions y añade clicks, impressions, ctr y position. Si la API no devuelve filas (rows ausente), retorna lista vacia sin error. Es el extractor principal de datos SEO para alimentar un pipeline hacia DuckDB/Postgres.	seo gsc datascience search-console google extractor				false	error_go_core	typing.Any	name desc service objeto service autenticado de la Google Search Console API (el que devuelve gsc_auth_py_infra). Se inyecta ya construido; esta funcion NO lo crea ni llama a gsc_auth internamente. Debe exponer .searchanalytics().query(siteUrl=..., body=...).execute(). name desc site_url propiedad de Search Console. Formato 'sc-domain:ejemplo.com' para propiedad de dominio, o URL completa 'https://ejemplo.com/' para propiedad de prefijo. El formato importa: usar el que coincida con como la propiedad esta dada de alta en GSC. name desc start_date fecha inicial inclusiva en formato YYYY-MM-DD. name desc end_date fecha final inclusiva en formato YYYY-MM-DD. La API tiene ~2-3 dias de lag; el caller deberia pedir hasta hoy-3 para datos completos. name desc dimensions lista de dimensiones a desglosar. Por defecto ['query', 'page']. Otras validas: 'date', 'country', 'device', 'searchAppearance'. El orden define el orden de las keys en cada fila. name desc row_limit filas por request y tamaño de paso de la paginacion. Rango 1..25000 (se clampa al tope duro de la API). Por defecto 25000. name desc max_total_rows tope total de filas acumuladas en todas las paginas. 0 = sin tope (trae todo lo disponible). Si >0, recorta el resultado al llegar a ese numero. name desc search_type tipo de busqueda: 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews'. Va en el body de la API como 'type'. Por defecto 'web'.	list de dicts aplanados. Cada dict tiene una clave por cada dimension (con su nombre real, ej. query, page) mas clicks, impressions, ctr y position. Ejemplo con dimensions=['query','page']: {'query': '...', 'page': '...', 'clicks': 5, 'impressions': 100, 'ctr': 0.05, 'position': 12.3}. Lista vacia si la API no devuelve filas.	true	test_aplanado_mapea_keys_a_nombres_de_dimension test_paginacion_recorre_varias_paginas_y_para_en_pagina_corta test_max_total_rows_recorta test_rows_ausente_retorna_lista_vacia test_dimension_unica_date	python/functions/datascience/pull_gsc_search_analytics_test.py	python/functions/datascience/pull_gsc_search_analytics.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from infra import gsc_auth
from datascience import pull_gsc_search_analytics

# 1. Autenticar (service account JSON via env var GSC_SA_JSON o ruta explicita)
service = gsc_auth()  # o gsc_auth("/ruta/fuera/del/repo/sa.json")

# 2. Extraer datos SEO por query + page de los ultimos dias (hasta hoy-3 por el lag)
rows = pull_gsc_search_analytics(
    service,
    site_url="sc-domain:ejemplo.com",      # propiedad de dominio
    # site_url="https://ejemplo.com/",     # alternativa: propiedad de prefijo
    start_date="2026-06-01",
    end_date="2026-06-17",
    dimensions=["query", "page"],
)

print(len(rows), "filas")
# rows[0] -> {'query': 'comprar zapatillas', 'page': 'https://ejemplo.com/zapatillas',
#             'clicks': 5, 'impressions': 100, 'ctr': 0.05, 'position': 12.3}

# Desglose temporal (1 fila por dia) con tope de filas:
serie = pull_gsc_search_analytics(
    service, "sc-domain:ejemplo.com", "2026-06-01", "2026-06-17",
    dimensions=["date"], max_total_rows=1000,
)

Cuando usarla

Cuando necesites ingerir datos SEO de Google Search Console (impresiones, clicks, CTR, posicion por query/pagina/fecha/pais/dispositivo) para volcarlos a DuckDB o Postgres. Es el paso de extraccion del pipeline SEO: primero gsc_auth para construir el service, luego esta funcion para traer las filas paginadas y aplanadas, listas para upsert en una tabla.

Gotchas

• Lag de 2-3 dias: GSC no tiene los datos del dia actual ni los 1-2 previos completos. Pide end_date = hoy-3 para evitar dias parciales que luego cambian.
• Privacy threshold (anonimizacion): las queries de baja frecuencia se ocultan por privacidad de Google. La suma de clicks/impressions por query NO cuadra con el total agregado sin dimension query — falta la "cola" anonimizada. Para totales exactos, pide tambien una consulta sin la dimension query (ej. solo ["date"]).
• Formato de site_url: sc-domain:ejemplo.com para propiedad de dominio; URL completa con esquema y barra final https://ejemplo.com/ para propiedad de prefijo. Si no coincide con como esta dada de alta la propiedad, la API devuelve 403/permission.
• Tope 25000 filas/request: row_limit se clampa a 25000. Para propiedades grandes la paginacion puede dar muchas requests; vigila los rate limits de la API (la funcion no reintenta — el error de quota se propaga al caller).
• Permisos: la service account debe estar añadida como usuario (al menos lectura) en la propiedad de GSC; si no, error de permisos al ejecutar el query.

Notas

service se inyecta ya construido (separacion auth/extraccion), por eso esta funcion no aparece acoplada a gsc_auth en uses_functions: no la importa ni la llama. El test ejercita la logica de paginado y aplanado con un service mock, sin red ni credenciales. Funcion impura: hace I/O de red contra la API de Google; cualquier error HTTP (auth, permisos, quota) se propaga.