chile-hub

Datos públicos de Chile, curados y listos para análisis en una línea de código.

La última milla de los datos oficiales de Chile — parte del ecosistema Tooltician.

Instalación · Confianza · Capas · Recetas · API y CLI · Licencias

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.47.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

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

• 23 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.

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: 22 capas construibles (make build local, incl. 1 en carril candidate) · 21 publicables (bundle ZIP) · 25 registradas en el catálogo (3 filas sin datos aún: geometría, delincuencia, 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.

flowchart TB
    classDef extract fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0f172a;
    classDef stage fill:#ecfeff,stroke:#0891b2,stroke-width:2px,color:#0f172a;
    classDef build fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#0f172a;
    classDef verify fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#0f172a;
    classDef test fill:#fae8ff,stroke:#c084fc,stroke-width:2px,color:#0f172a;
    classDef publish fill:#ffe4e6,stroke:#f43f5e,stroke-width:2px,color:#0f172a;

    subgraph EXTRACT["1. EXTRACT - fuentes oficiales"]
        direction TB
        X1["Territorio<br/>BCN / SERVEL"]:::extract
        X2["Demografía 2024<br/>INE"]:::extract
        X3["Servicios públicos<br/>MINSAL / MINEDUC"]:::extract
        X4["Economía<br/>BCCh / SINIM / RES"]:::extract
        X5["Indicadores urbanos<br/>SIEDU"]:::extract
    end

    S["data/staging/<br/>CSV + metadata.json"]:::stage
    B["2. BUILD<br/>build_dev_db.py"]:::build
    N["data/normalized/<br/>artefactos publicables"]:::stage
    V["3. VERIFY<br/>verify_pipeline.py"]:::verify
    T["4. TEST<br/>pytest"]:::test
    L["5. SMOKE + PUBLISH<br/>landing + bundle"]:::publish

    X1 --> S
    X2 --> S
    X3 --> S
    X4 --> S
    X5 --> S
    S --> B --> N --> V --> T --> L

[!IMPORTANT] Invariante crítica: El pipeline aborta si la cardinalidad de comunas ≠ 346, si los códigos CUT pierden el formato VARCHAR, o si alguna regla de negocio se rompe. Nunca se publican 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:

flowchart TB
    R["Territorio base<br/><b>REGIONES</b><br/>codigo_region"]
    P["<b>PROVINCIAS</b><br/>codigo_provincia + codigo_region"]
    C["<b>COMUNAS</b><br/>codigo_comuna + codigo_provincia + codigo_region"]
    L["Capas comunales<br/>codigo_comuna<br/>censo · hogares · salud<br/>educación · distritos · enriquecimiento"]

    R --> P --> C --> L

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.

Apéndice: esquemas y modelo de datos

erDiagram
    REGIONES {
        VARCHAR codigo_region PK "Ej: '01' (Tarapacá)"
        VARCHAR nombre_region
    }
    PROVINCIAS {
        VARCHAR codigo_provincia PK "Ej: '011' (Iquique)"
        VARCHAR codigo_region FK
        VARCHAR nombre_provincia
    }
    COMUNAS {
        VARCHAR codigo_comuna PK "Ej: '01101' (Iquique)"
        VARCHAR codigo_provincia FK
        VARCHAR codigo_region FK
        VARCHAR nombre_comuna
        VARCHAR nombre_comuna_clean "Ej: 'iquique' (sin tildes)"
    }
    COMUNAS_ENRIQUECIDAS {
        VARCHAR codigo_comuna PK
        VARCHAR nombre_comuna
        DOUBLE latitud_cabecera
        DOUBLE longitud_cabecera
        INTEGER poblacion_estimada
    }
    CENSO_COMUNAL {
        VARCHAR codigo_comuna PK
        INTEGER poblacion_censada
        INTEGER hombres
        INTEGER mujeres
        INTEGER poblacion_0_14
    }
    CENSO_HOGARES_VIVIENDAS {
        VARCHAR codigo_comuna PK
        INTEGER viviendas_censadas
        INTEGER hogares_censados
        DOUBLE promedio_personas_hogar
    }
    ESTABLECIMIENTOS_SALUD {
        VARCHAR codigo_establecimiento PK
        VARCHAR codigo_comuna FK
        VARCHAR nombre_establecimiento
        VARCHAR tipo_establecimiento
    }
    DISTRITOS_ELECTORALES {
        VARCHAR codigo_comuna PK
        VARCHAR distrito_electoral
        VARCHAR circunscripcion_senatorial
    }
    ESTABLECIMIENTOS_EDUCACIONALES {
        VARCHAR rbd PK "Rol Base de Datos"
        VARCHAR codigo_comuna FK
        VARCHAR nombre_establecimiento
    }
    INDICADORES {
        DATE fecha PK
        VARCHAR codigo_indicador PK "Ej: 'uf', 'dolar'"
        DOUBLE valor
    }

    REGIONES ||--o{ PROVINCIAS : "contiene"
    PROVINCIAS ||--o{ COMUNAS : "contiene"
    COMUNAS ||--|| COMUNAS_ENRIQUECIDAS : "enriquece"
    COMUNAS ||--o| CENSO_COMUNAL : "demografía"
    COMUNAS ||--o| CENSO_HOGARES_VIVIENDAS : "hogares"
    COMUNAS ||--o{ ESTABLECIMIENTOS_SALUD : "salud"
    COMUNAS ||--o{ ESTABLECIMIENTOS_EDUCACIONALES : "educación"
    COMUNAS ||--o| DISTRITOS_ELECTORALES : "electoral"