chile-hub

chile-hub

Deja de pelear con planillas, enlaces rotos y esquemas incompatibles.

Datos públicos de Chile curados, normalizados, validados y listos para Python, SQL, Excel y pipelines.

La última milla entre “el dato existe” y “el dato ya sirve”.

Explorar datos en el navegador · Instalar · Ver capas · Auditar calidad

El dato público existe. El problema es dejarlo listo para usar.

Si trabajas con datos de Chile, probablemente ya conoces la fricción: archivos Excel con formatos cambiantes, códigos territoriales que pierden ceros, fuentes dispersas, APIs inconsistentes y cruces que fallan por diferencias mínimas de nombres.

chile-hub convierte esa última milla en infraestructura reutilizable.

Un artefacto, no una síntesis. Cada cifra viene de una corrida reproducible contra la fuente oficial, con hash, fecha y advertencias. Lo que no se puede verificar, no se publica.

Instalar y usar en 30 segundos

pip install chile-hub

from chile_hub import ChileHub

hub = ChileHub()
comunas = hub.load_polars("comunas")  # 346 comunas, códigos CUT como texto
censo = hub.load_polars("censo_comunal")  # población censada por comuna

# Cruce territorial garantizado: la clave es el CUT, nunca un int
df = (
    comunas.join(censo, on="codigo_comuna")
    .select("codigo_comuna", "nombre_comuna", "nombre_region", "poblacion_censada")
    .sort("poblacion_censada", descending=True)
    .head(5)
)
print(df)

Resultado real (Censo 2024):

shape: (5, 4)
┌───────────────┬───────────────┬─────────────────────────────────┬───────────────────┐
│ codigo_comuna ┆ nombre_comuna ┆ nombre_region                   ┆ poblacion_censada │
│ ---           ┆ ---           ┆ ---                             ┆ ---               │
│ str           ┆ str           ┆ str                             ┆ i64               │
╞═══════════════╪═══════════════╪═════════════════════════════════╪═══════════════════╡
│ 13201         ┆ Puente Alto   ┆ Región Metropolitana de Santia… ┆ 568086            │
│ 13119         ┆ Maipú         ┆ Región Metropolitana de Santia… ┆ 503635            │
│ 13101         ┆ Santiago      ┆ Región Metropolitana de Santia… ┆ 438856            │
│ 02101         ┆ Antofagasta   ┆ Región de Antofagasta           ┆ 401096            │
│ 13110         ┆ La Florida    ┆ Región Metropolitana de Santia… ┆ 374836            │
└───────────────┴───────────────┴─────────────────────────────────┴───────────────────┘

En el sitio puedes consultar los mismos Parquet con SQL en el navegador (motor DuckDB-WASM, sin instalar nada):

La primera ejecución descarga el bundle validado desde GitHub Releases, verifica su integridad SHA256 y lo deja en cache local; a partir de ahí todo corre contra el cache. La comprobación semanal de novedades no envía datos de uso y se desactiva con CHILE_HUB_NO_UPDATE_CHECK=1 (CHILE_HUB_LANG=es|en elige el idioma del aviso).

chile-hub cache update     # Forzar descarga del bundle más reciente
chile-hub cache status     # Ubicación y estado del cache local
chile-hub cache clear      # Liberar espacio

Variante pipeline: pip install chile-hub[pipeline] agrega DuckDB, Pandas, XlsxWriter y curl_cffi para ejecutar el pipeline completo de extracción y build. La instalación mínima solo incluye Polars, PyArrow, requests y platformdirs — suficiente para consumir datos.

[!NOTE] chile-hub no busca “tener todos los datos de Chile”. Busca reducir drásticamente el costo técnico de encontrar, limpiar, validar, cruzar y consumir datasets geográficos, demográficos, electorales y económicos críticos de Chile.

Tampoco es un portal ni una fuente oficial: trabaja aguas abajo de datos.gob.cl y de las instituciones que publican cada dato, y siempre enlaza a la fuente oficial. Es un proyecto independiente, sin afiliación con esas instituciones. Misión y principios: docs/product-spec.md.

En la práctica, responde preguntas como:

• ¿Cómo cruzo mi base de clientes, escuelas o centros de salud con comunas oficiales sin perder ceros en los códigos?
• ¿Qué comunas concentran población censada, establecimientos públicos o indicadores urbanos?
• ¿Cómo llevo datos oficiales a Polars, DuckDB, SQLite, Excel o CI sin depender de enlaces cambiantes?

Versionado: Para entornos productivos, fija la versión exacta en requirements.txt (revisa el badge de PyPI al inicio de este README para la versión más reciente):

chile-hub==1.57.0

El bundle de datos se publica con cada release. La API del módulo ChileHub sigue versionado semántico: cambios de interfaz pública solo en major releases.

Por qué confiar

Cada decisión de ingeniería de este proyecto está diseñada para que no tengas que confiar ciegamente: los datos vienen con la evidencia que los respalda.

Trabajar con datos públicos chilenos suele implicar los mismos obstáculos:

Seis pilares, auditables y verificables en cada build

Cada pilar se audita automáticamente en cada ejecución del pipeline. Los reportes se regeneran en cada build — no son documentos estáticos mantenidos a mano. Para auditar el estado exacto de cualquier capa:

chile-hub provenance   # fuente, modo y timestamp por dataset
chile-hub health       # severidad, frescura, drift y cobertura

El mismo estado se publica en el sitio, con historial de builds y detalle por capa:

Respaldo adicional

• 1505 tests (pytest --collect-only) que validan extracción, contratos e integridad de datos.

• 25 ADRs (docs/adr/) que documentan cada decisión de arquitectura con su contexto, consecuencias y tradeoffs — no solo el “qué”, sino el “por qué”.

• Drift monitoreado: todos los datasets bajo vigilancia de deriva de esquema; cualquier cambio en la fuente se detecta y registra (drift_report.md).
• Trazabilidad completa: cada build registra timestamp, versión de extractor y snapshot de entrada en provenance_report.md.

Menos trabajo repetido

Reconstruir la serie completa de empresas exige 13 archivos anuales (≈215 MB) y parsear 1,6 millones de filas. El bundle con las 22 capas, ya normalizadas y validadas, pesa 31 MB. No medimos el ahorro energético: es una propiedad del diseño —el trabajo pesado se hace una vez por build y se comparte—, no una cifra de carbono.

Para una explicación más detallada de la arquitectura y las decisiones de diseño, lee el caso de estudio: cómo está construido chile-hub.

Qué incluye

Cómo leer los conteos: 23 capas construibles (make build local, incl. 1 en carril candidate) · 22 publicables (bundle ZIP) · 26 registradas en el catálogo (3 sin datos: geometría, delincuencia —rejected— y autoridades locales). La convención completa vive junto al badge superior y en data/source_registry.json.

Mapa territorial interactivo: las 346 comunas con 7 métricas seleccionables (población, pobreza, permisos, equipamiento, MP2.5) y ficha por comuna.

Métricas por build: el modo de la última extracción, el conteo de registros, la cobertura y la frescura viven en hub_health.md, dataset_status.json y dataset_quality.md, regenerados en cada build; los badges resumen frescura y estado: Para auditar el estado exacto de cada capa: chile-hub provenance y chile-hub health.

El schema de columnas, tipos y PK de cada capa vive en contracts/datasets/ y en docs/datasets/; el volcado completo está en el apéndice.

Formatos de salida

Cada ejecución del pipeline genera en data/normalized/:

🍳 Recetas de uso

¿Prefieres notebooks? Las cuatro recetas están en examples/notebooks/ con botón de Colab, o ejecutables en el explorador SQL del sitio.

1. Últimos indicadores económicos disponibles

from chile_hub import ChileHub

df = ChileHub().load_polars("indicadores")
ultimos = (
    df.sort("fecha", descending=True)
    .group_by("codigo_indicador")
    .first()
    .select("codigo_indicador", "fecha", "valor")
    .sort("codigo_indicador")
)
print(ultimos)

2. Salud y educación por comuna

from chile_hub import ChileHub

hub = ChileHub()
salud = hub.load_polars("establecimientos_salud")
educacion = hub.load_polars("establecimientos_educacionales")

salud_por_comuna = salud.group_by("codigo_comuna").len("establecimientos_salud")
educacion_por_comuna = educacion.group_by("codigo_comuna").len("establecimientos_educacionales")

resumen = (
    hub.load_polars("comunas")
    .join(salud_por_comuna, on="codigo_comuna", how="left")
    .join(educacion_por_comuna, on="codigo_comuna", how="left")
    .fill_null(0)
    .select(
        "codigo_comuna", "nombre_comuna", "establecimientos_salud", "establecimientos_educacionales"
    )
)
print(resumen.head())

3. SQL directo con DuckDB

-- Top 10 comunas por población censada
SELECT nombre_comuna, poblacion_censada, hombres, mujeres
FROM 'data/normalized/censo_comunal.parquet'
ORDER BY poblacion_censada DESC
LIMIT 10;

-- Cruce territorial: comunas × distritos electorales
SELECT c.nombre_comuna, c.nombre_region,
       e.distrito_electoral, e.circunscripcion_senatorial
FROM 'data/normalized/comunas.parquet' c
JOIN 'data/normalized/distritos_electorales.parquet' e
  ON c.codigo_comuna = e.codigo_comuna
WHERE c.nombre_region = 'Valparaíso';

🧰 API y CLI

API Python compacta

¿Construyes agentes? El proyecto incluye un servidor MCP con catálogo, consultas y resolución de comunas para que tu agente consuma los datos sin integraciones propias: docs/mcp.md.

CLI: los comandos más usados

⚙️ Cómo funciona

El pipeline es lineal, determinista y estricto: si una validación falla, el build se cancela antes de publicar datos corruptos.

Modelo de datos: códigos CUT

El valor central de chile-hub es que todas las capas se vinculan jerárquicamente mediante los Códigos Únicos Territoriales (CUT) de SUBDERE/INE:

El diagrama entidad-relación completo está en el apéndice.

🗺️ Próximos pasos

El roadmap actual prioriza crecer en usabilidad y confianza antes que agregar más capas.

Especificación completa: docs/product-spec.md Criterios de inclusión: docs/dataset-inclusion-criteria.md Estado del último build: data/normalized/pipeline_status.md

🤝 Desarrollo y contribución

¿Quieres aportar o pedir un dataset?

No necesitas saber programar ni traer los datos limpios: basta con la fuente y para qué sirve (o la necesidad, si solo quieres pedirlo). La guía de 2 minutos y los dos formularios están en Aportar o solicitar un dataset (criterios completos).

Desarrollar el pipeline

Esta sección es para contribuidores que ejecutan el pipeline de extracción, build y verificación en su máquina. Si solo necesitas consumir los datos, usa pip install chile-hub (ver Instalación).

Requiere uv y Git. Python lo gestiona uv (make bootstrap).

# Entorno
git clone https://github.com/cortega26/chile-hub.git
cd chile-hub
make bootstrap          # Crea .venv, instala dependencias + Playwright
make doctor             # Verifica versión de Python y dependencias críticas

# Pipeline completo
make refresh            # extract → build → verify → test → landing

# Pasos individuales
make extract            # Ejecuta los extractores → data/staging/
make build              # Compila artefactos → data/normalized/
make verify             # Verifica integridad (SHA256, conteos, schema)
make test               # pytest (lee data/normalized/, no corre el pipeline)
make coverage           # pytest + cobertura de src/ (term-missing + coverage.xml)
make verify-landing     # Pruebas de humo de landing page con Playwright

autoridades_electas requiere scrapling para no degradar a 155 registros (0 senadores); el comando local está en Carriles de extracción.

El ZIP publicable no se versiona: make build lo genera localmente y el sitio lo descarga desde el asset del último GitHub Release. Para clones más livianos: git clone --filter=blob:none https://github.com/cortega26/chile-hub.

Para entender la arquitectura, las reglas no negociables y el flujo de trabajo, revisa AGENTS.md; el punto de partida rápido es SOURCE_OF_TRUTH.md.

¿Encontraste un error o tienes un caso de uso? Abre un issue — ayuda a priorizar el roadmap.

⚖️ Fuentes, licencias y reúso

Semáforo de redistribución

Licencia del proyecto

El código Python se distribuye bajo MIT. Los datasets conservan las licencias, permisos y requisitos de atribución de sus fuentes oficiales. Consulta DATA_LICENSES.md, chile-hub redistribution y chile-hub provenance antes de redistribuir artefactos derivados.

Cómo citar

Si usas chile-hub en un paper, tesis, curso o informe, cita el software y atribuye la fuente de cada capa. GitHub muestra el botón “Cite this repository” a partir de CITATION.cff; las recetas BibTeX/APA y la ruta para un DOI Zenodo están en docs/citation.md.

Autor y mantenedor: Carlos Ortega — ORCID 0009-0000-3470-6181.

📚 Apéndice: esquemas y modelo de datos