chile-hub

title

chile-hub — Datos públicos de Chile, curados y listos para análisis

description

Hub de datos abiertos de Chile — parte del ecosistema Tooltician. 19 capas de datos públicos curados: DPA, Censo 2024, indicadores económicos, salud, educación, finanzas municipales, empresas, electoral y más. Instalable vía pip, consumible en Python, DuckDB, Parquet o Excel.

chile-hub

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

El hub de datos abiertos de Chile — parte del ecosistema Tooltician.

Instalación · Capas · Arquitectura · CLI · Licencias

⚡ Instalar y usar en segundos

pip install chile-hub

from chile_hub import ChileHub

hub = ChileHub()
comunas = hub.load_polars("comunas")          # 346 comunas como DataFrame
indicadores = hub.load_polars("indicadores")  # Serie histórica UF, Dólar, Euro, UTM, IPC

# Cruce territorial garantizado — códigos CUT siempre VARCHAR
censo = hub.load_polars("censo_comunal")
df = comunas.join(censo, on="codigo_comuna")
print(df.head())

La primera ejecución descarga automáticamente 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. También puedes administrarlo explícitamente:

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 para desarrolladores del 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.

En la práctica, sirve para responder preguntas comunes sin rehacer limpieza base:

¿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?

¿Por qué existe?

Trabajar con datos públicos chilenos implica enfrentar los mismos obstáculos una y otra vez:

❌ Sin chile-hub	✅ Con chile-hub
Enlaces rotos y APIs inconsistentes	Pipeline automatizado con fallbacks y verificación de integridad
Planillas Excel deformes con celdas combinadas	Parquet, DuckDB y JSON listos para producción
Códigos CUT que pierden ceros al leerse como `int`	CUT garantizados como `VARCHAR` de largo fijo (`"01101"`)
Nombres de comunas imposibles de cruzar (Ñuñoa vs Nunoa)	Columna `nombre_comuna_clean` normalizada para cruces exactos
Cero trazabilidad sobre origen y vigencia del dato	Metadatos con fuente, fecha de extracción, licencia y modo

chile-hub empaqueta esas decisiones en una capa reproducible: extrae desde fuentes oficiales, normaliza schemas, valida reglas territoriales y publica artefactos listos para consumo local o CI/CD.

¿Qué entrega chile-hub?

Curado y validado Cada capa pasa por validaciones automáticas de integridad referencial, cardinalidad exacta (346 comunas) y formato de códigos territoriales. El pipeline falla ruidosamente antes de publicar datos corruptos.	Cruzable por diseño Todos los datasets se vinculan mediante códigos CUT (`codigo_comuna`, `codigo_provincia`, `codigo_region`). Una sola clave une demografía, salud, educación, finanzas municipales, indicadores urbanos y distritos electorales.
Múltiples formatos Parquet para analítica de alto rendimiento, DuckDB para consultas SQL locales, SQLite para aplicaciones embebidas, JSON para pipelines y Excel para usuarios de planillas. Todos generados desde la misma fuente.	Trazabilidad total Cada artefacto incluye: fuente original, fecha de extracción, modo (en vivo/respaldo), hash SHA256, licencia y estatus de redistribución. Sabes exactamente qué estás consumiendo.
Una línea de código from chile_hub import ChileHub hub = ChileHub() df = hub.load_polars("comunas")	CI/CD transparente Pipeline determinista en GitHub Actions: extracción → build → verificación → tests → pruebas de humo. Todo reproducible en local con `make refresh`.

Las 19 capas de datos

#	Capa	Registros	Modo	Fuente	Licencia	Actualización
1	Regiones	16	🟢 live	BCN ArcGIS	CC BY	—
2	Provincias	56	🟢 live	BCN ArcGIS	CC BY	—
3	Comunas	346	🟢 live	BCN ArcGIS	CC BY	—
4	Comunas Enriquecidas	346	🟢 live	BCN + INE	CC BY	—
5	Indicadores Económicos	Serie histórica	🟢 live	BCCh / mindicador.cl	Libre c/cita	Diaria
6	Censo Comunal 2024	346	🟢 live	INE	CC BY 4.0	Decenal
7	Censo Hogares y Viviendas	346	🟢 live	INE	CC BY 4.0	Decenal
8	Establecimientos de Salud	5707	🟢 live	MINSAL / datos.gob.cl	CC0	Mensual
9	Distritos Electorales	346	🟢 live	BCN / Ley 20.840	CC0	—
10	Establecimientos Educacionales	~12 898	🟢 live	MINEDUC	CC BY 3.0 CL	Anual
11	Finanzas Municipales ⚠️	345 (parcial, 345/346)	🔶 parcial	SINIM / SUBDERE	Revisión términos	Anual
12	Resultados Educacionales	345	🟢 live	MINEDUC	CC BY 3.0 CL	Anual
13	Indicadores Urbanos SIEDU	6 701 (parcial)	🟢 live	INE / SIEDU	Datos abiertos INE	Anual
14	Perfil Territorial Comunal	346	🟡 fallback	chile-hub derivado	Fuentes abiertas	Derivada
15	Empresas (RES)	~1 572 116	🟢 live	Min. Economía / datos.gob.cl	CC-BY 3.0 CL	Mensual
16	Pobreza Comunal (SAE)	3	🟡 fallback	MDS / Observatorio Social	Datos abiertos MDS	Bienal/trienal
17	Consumo Eléctrico Comunal	3	🟡 fallback	CNE / Energía Abierta	CC BY	Anual
18	Partidos Políticos	36	🟢 live	Cámara de Diputados	CC BY	Bajo_demanda
19	Autoridades Electas	205	🟢 live	Cámara de Diputados + Senado	CC BY	Bajo_demanda
20	Delincuencia Comunal 🆕	—	🔜 próximamente	CEAD / SPD	Revisión términos	—
21	Autoridades Locales 🆕	—	🔜 próximamente	BCN SIIT + Wikipedia	CC BY / CC BY-SA	—

🟢 live: datos extraídos directamente desde la fuente oficial en cada ejecución del pipeline. 🟡 fallback: datos servidos desde un respaldo curado mientras se completa la extracción en vivo. 🔶 parcial: cobertura inferior al 50% del universo esperado. Capa candidata, no completa. 🔜 próximamente: capa en carril candidate — extractor implementado, datos no incluidos en el bundle público. Para auditar el estado exacto de cada capa: chile-hub provenance y chile-hub health.

🔒 Por qué puedes confiar en estos datos

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. Seis pilares de confiabilidad, auditables y verificables en cada build:

Pilar	Descripción	Artefacto auditable
Procedencia documentada	Cada dataset declara su fuente oficial exacta con URL directa al organismo público emisor (BCN, INE, MINEDUC, BCCh, MINSAL, datos.gob.cl).	`provenance_report.md` — fuente, modo y timestamp por capa
Auditoría legal explícita	Licencia, atribución requerida y permiso de redistribución verificados dataset por dataset. 19 de 19 capas pasan la auditoría (`ready`).	`redistribution_report.md` + `AGENTS.md §6`
Pipeline fail-loud	Si una validación falla, el pipeline aborta — no publica datos corruptos, no emite advertencias silenciosas.	`ADR-001` — fail-loud como decisión de arquitectura
Contratos de esquema	21 contratos JSON Schema (`contracts/datasets/`) definen columnas esperadas, tipos, claves primarias y cobertura. Se validan en cada build automáticamente.	`ADR-005` + `contracts/datasets/*.json`
Salud transparente	Dashboard público con severidad, frescura, cobertura, drift y degradación por dataset. 12 capas `ok`, 7 `warn`, 0 `error`.	`hub_health.md` — estado completo actualizado en cada build
Calidad medida	Puntuación compuesta A-F por dataset: promedio 94.2/100 (18 A, 1 B). Dimensiones: validación, contrato, madurez de fuente, frescura, cobertura, política de reúso.	`dataset_quality.md` — scorecard completo

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

Respaldo adicional

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

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

Ver schema completo de cada capa

1. regiones — Capa derivada de regiones para filtros, joins y referencias administrativas de alto nivel. (PK: codigo_region)

Columna	Tipo	Ejemplo
`codigo_region`	`VARCHAR(2)`	`"01"`
`nombre_region`	`VARCHAR`	`"Tarapacá"`

2. provincias — Capa derivada de provincias para cruces intermedios entre region y comuna. (PK: codigo_provincia)

Columna	Tipo	Ejemplo
`codigo_region`	`VARCHAR(2)`	`"01"`
`nombre_region`	`VARCHAR`	`"Tarapacá"`
`codigo_provincia`	`VARCHAR(3)`	`"011"`
`nombre_provincia`	`VARCHAR`	`"Iquique"`

3. comunas — Base territorial normalizada para cruces por region, provincia y comuna. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Iquique"`
`nombre_comuna_clean`	`VARCHAR`	`"iquique"`
`codigo_provincia`	`VARCHAR(3)`	`"011"`
`codigo_region`	`VARCHAR(2)`	`"01"`
`nombre_region`	`VARCHAR`	`"Tarapacá"`
`latitud_cabecera`	`DOUBLE`	`-20.2138`
`longitud_cabecera`	`DOUBLE`	`-70.1508`
`poblacion_estimada`	`INTEGER`	`223400`

4. comunas_enriquecidas — Comunas con coordenadas de cabecera y poblacion estimada INE, listas para analisis territorial sin joins adicionales. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Iquique"`
`nombre_comuna_clean`	`VARCHAR`	`"iquique"`
`codigo_provincia`	`VARCHAR(3)`	`"011"`
`codigo_region`	`VARCHAR(2)`	`"01"`
`latitud_cabecera`	`DOUBLE`	`-20.2138`
`longitud_cabecera`	`DOUBLE`	`-70.1508`
`poblacion_estimada`	`INTEGER`	`223400`

5. indicadores — Serie de indicadores economicos diarios de referencia para analisis y software. (PK: fecha, codigo_indicador)

Columna	Tipo	Ejemplo
`fecha`	`DATE`	`"2026-05-30"`
`codigo_indicador`	`VARCHAR`	`"uf"`
`valor`	`DOUBLE`	`39420.5`

6. censo_comunal — Perfil demografico comunal del Censo 2024 con sexo y grandes grupos de edad. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_region`	`VARCHAR(2)`	`"01"`
`codigo_provincia`	`VARCHAR(3)`	`"011"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Iquique"`
`poblacion_censada`	`INTEGER`	`223400`
`hombres` / `mujeres`	`INTEGER`	`"111200` / `112200"`
`razon_hombre_mujer`	`DOUBLE`	`99.11`
`poblacion_0_14` … `poblacion_65_mas`	`INTEGER`	`"5 tramos etarios"`

7. censo_hogares_viviendas — Viviendas y hogares censados por comuna, ocupacion y tamano medio del hogar. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`viviendas_censadas`	`INTEGER`	`85000`
`viviendas_particulares_ocupadas`	`INTEGER`	`75000`
`viviendas_colectivas`	`INTEGER`	`200`
`hogares_censados`	`INTEGER`	`73000`
`promedio_personas_hogar`	`DOUBLE`	`3.06`

8. establecimientos_salud — Directorio vigente de establecimientos de salud con tipo, dependencia, urgencia y ubicacion. (PK: codigo_establecimiento)

Columna	Tipo	Ejemplo
`codigo_establecimiento`	`VARCHAR`	`"101101"`
`nombre_establecimiento`	`VARCHAR`	`"Hospital Dr. Ernesto Torres Galdames"`
`tipo_establecimiento`	`VARCHAR`	`"Hospital"`
`nivel_atencion`	`VARCHAR`	`"Alta Complejidad"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`tiene_servicio_urgencia`	`VARCHAR`	`"SI"` / `"NO"`
`latitud` / `longitud`	`DOUBLE`	`"Coordenadas geográficas"`
`estado_funcionamiento`	`VARCHAR`	`"Vigente"`

9. distritos_electorales — Asociación de comunas a distritos electorales (diputados) y circunscripciones senatoriales. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Las Condes"`
`distrito_electoral`	`VARCHAR`	`"10"`
`circunscripcion_senatorial`	`VARCHAR`	`"3"`

10. establecimientos_educacionales — Directorio oficial del Ministerio de Educación (MINEDUC) con Rol Base de Datos (RBD), ubicación y dependencia administrativa. (PK: rbd)

Columna	Tipo	Ejemplo
`rbd`	`VARCHAR`	`"1234-5"`
`dv_rbd`	`VARCHAR`	`"4"`
`nombre_establecimiento`	`VARCHAR`	`"Liceo Abate Molina"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`dependencia_administrativa`	`VARCHAR`	`"Municipal"`
`latitud` / `longitud`	`DOUBLE`	`"Coordenadas geográficas"`
`estado_funcionamiento`	`VARCHAR`	`"Vigente"`

11. finanzas_municipales — Indicadores financieros municipales anuales desde SINIM/SUBDERE. CAPA PARCIAL/CANDIDATO: 3 de 346 comunas (0.9%). Usar con precaución; no representa cobertura nacional. (PK: anio, codigo_comuna)

Columna	Tipo	Ejemplo
`anio`	`INTEGER`	`2024`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`ingresos_totales` / `gastos_totales`	`DOUBLE`	`245000000000.0`
`ingresos_propios_permanentes`	`DOUBLE`	`162000000000.0`
`fondo_comun_municipal`	`DOUBLE`	`39000000000.0`

12. resultados_educacionales — Resultados educacionales agregados por comuna y año, sin registros personales. (PK: anio, codigo_comuna)

Columna	Tipo	Ejemplo
`anio`	`INTEGER`	`2024`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`matricula_total`	`INTEGER`	`122000`
`asistencia_promedio`	`DOUBLE`	`86.2`
`tasa_aprobacion` / `tasa_retiro`	`DOUBLE`	`"91.4` / `4.5"`

13. indicadores_urbanos_siedu — Indicadores urbanos SIEDU en formato largo con cobertura comunal parcial esperada. (PK: anio, codigo_comuna, codigo_indicador)

Columna	Tipo	Ejemplo
`anio`	`INTEGER`	`2024`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`codigo_indicador`	`VARCHAR`	`"siedu_acceso_areas_verdes"`
`categoria`	`VARCHAR`	`"Espacio publico"`
`valor` / `unidad`	`DOUBLE`	`"71.4` / `"porcentaje"`

14. perfil_territorial_comunal — Perfil comunal curado que consolida DPA, censo, salud, educación, finanzas, SIEDU y distritos. (PK: codigo_comuna)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`poblacion_censada`	`INTEGER`	`223400`
`establecimientos_salud_total`	`INTEGER`	`140`
`establecimientos_educacionales_total`	`INTEGER`	`410`
`distrito_electoral`	`VARCHAR`	`"10"`

15. empresas — Registro de Empresas y Sociedades (RES) con RUT, razon social, tipo societario, capital, fecha de constitucion y comuna de domicilio. (PK: rut)

Columna	Tipo	Ejemplo
`rut`	`VARCHAR`	`"76286049-K"`
`razon_social`	`VARCHAR`	`"COMERCIALIZADORA EJEMPLO SPA"`
`codigo_sociedad`	`VARCHAR`	`"SPA"`
`capital`	`INTEGER`	`5000000`
`fecha_actuacion`	`DATE`	`"2020-06-15"`
`anio`	`INTEGER`	`2020`
`comuna_tributaria`	`VARCHAR`	`"SANTIAGO"`
`region_tributaria`	`VARCHAR`	`"13"`

16. pobreza_comunal — Estimaciones de pobreza comunal por ingresos y multidimensional derivadas de la encuesta CASEN mediante metodología SAE (Estimación de Áreas Pequeñas). Incluye tasa, límite inferior y superior del intervalo de confianza por comuna, año y dimensión. (PK: codigo_comuna, anio, dimension)

Columna	Tipo	Ejemplo
`codigo_region`	`VARCHAR(2)`	`"01"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Santiago"`
`anio`	`INTEGER`	`2022`
`dimension`	`VARCHAR`	`"ingresos"` / `"multidimensional"`
`tasa`	`DOUBLE`	`15.3`
`limite_inferior`	`DOUBLE`	`12.1`
`limite_superior`	`DOUBLE`	`18.9`
`metodologia`	`VARCHAR`	`"SAE"`
`fuente`	`VARCHAR`	`"Observatorio Social — MDS"`

17. consumo_electrico_comunal — Consumo eléctrico anual por comuna y tipo de cliente (Residencial, Comercial, Industrial, Agrícola, Alumbrado Público, Otros), publicado por la Comisión Nacional de Energía (CNE) en el portal Energía Abierta. DEPRECATED: la fuente Junar de energiaabierta.cl fue decomisionada (investigado 2026-07-07); el dataset solo publica datos de muestra (FALLBACK_ROWS), no está en el bundle público. Ver data/source_registry.json. (PK: codigo_comuna, anio, tipo_cliente)

Columna	Tipo	Ejemplo
`codigo_region`	`VARCHAR(2)`	`"01"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Santiago"`
`anio`	`INTEGER`	`2023`
`tipo_cliente`	`VARCHAR`	`"Residencial"`
`consumo_kwh`	`DOUBLE`	`1523400.5`
`numero_clientes`	`INTEGER`	`45800`
`fuente`	`VARCHAR`	`"CNE — Energía Abierta"`

18. partidos_politicos — Roster de partidos políticos de Chile (Cámara de Diputadas y Diputados), con estado_legal y fecha_constitucion completados por join de nombre contra el registro público de SERVEL. (PK: id_partido)

Columna	Tipo	Ejemplo
`id_partido`	`VARCHAR`	`"DC"`
`nombre`	`VARCHAR`	`"Partido Demócrata Cristiano"`
`sigla`	`VARCHAR`	`"DC"`
`estado_legal`	`VARCHAR`	`"constituido"` (nulo si no matchea con SERVEL)"`
`fecha_constitucion`	`DATE`	`"1988-05-02"`
`ambito`	`VARCHAR`	`"null` (sin fuente que lo provea)"`
`fuente`	`VARCHAR`	`"Cámara de Diputadas y Diputados"`

19. autoridades_electas — Autoridades electas en ejercicio de Chile (diputados y senadores): partido, distrito electoral/circunscripción senatorial, región y período de mandato. (PK: id_autoridad)

Columna	Tipo	Ejemplo
`id_autoridad`	`VARCHAR`	`"diputado_1009"`
`nombre`	`VARCHAR`	`"Jorge Alessandri Vergara"`
`cargo`	`VARCHAR`	`"diputado"` / `"senador"`
`institucion`	`VARCHAR`	`"Cámara de Diputadas y Diputados"` / `"Senado"`
`partido`	`VARCHAR`	`"Unión Demócrata Independiente"`
`distrito_electoral`	`VARCHAR`	`"10"` (solo diputados)"`
`circunscripcion_senatorial`	`VARCHAR`	`"3"` (solo senadores)"`
`codigo_region`	`VARCHAR(2)`	`"02"` (solo senadores)"`
`periodo_inicio` / `periodo_fin`	`DATE`	`"2026-03-11` / `2030-03-10"`
`estado_mandato`	`VARCHAR`	`"vigente"`

20. delincuencia_comunal — Casos policiales de Delitos de Mayor Connotación Social (DMCS) y otras categorías por comuna y mes, reportados por Carabineros y PDI al Ministerio del Interior. Fuente: CEAD (Centro de Estudios y Análisis del Delito), Subsecretaría de Prevención del Delito. (en carril candidate — datos no incluidos en el bundle público) (PK: anio, mes, codigo_comuna, familia_delito)

Columna	Tipo	Ejemplo
`codigo_comuna`	`VARCHAR(5)`	`"01101"`
`nombre_comuna`	`VARCHAR`	`"Santiago"`
`anio`	`INTEGER`	`2024`
`mes`	`INTEGER`	`1`
`familia_delito`	`VARCHAR`	`"robos_violentos"`
`casos`	`INTEGER`	`245`

21. autoridades_locales — Autoridades locales/subnacionales de Chile: gobernadores regionales (Wikipedia, CC-BY-SA) y alcaldes (BCN SIIT, dato público gubernamental). Wikipedia se mantiene como fuente de gobernadores y enriquecimiento opcional de periodo_inicio para alcaldes. Dataset segregado de autoridades_electas por licencia mixta. (en carril candidate — datos no incluidos en el bundle público) (PK: id_autoridad)

Columna	Tipo	Ejemplo
`id_autoridad`	`VARCHAR`	`"gobernador_01"`
`nombre`	`VARCHAR`	`"null` si no hay evidencia clara del titular"`
`cargo`	`VARCHAR`	`"gobernador_regional"` / `"alcalde"`
`codigo_region`	`VARCHAR(2)`	`"01"`
`codigo_comuna`	`VARCHAR(5)`	`"01101"` (solo alcaldes)"`
`partido`	`VARCHAR`	`"nulo si no identificado"`
`estado_mandato`	`VARCHAR`	`"vigente"` / `"sin_identificar"`

Guía de uso

Consumir datos (instalación desde PyPI)

pip install chile-hub

from chile_hub import ChileHub

hub = ChileHub()

# Catálogo de capas disponibles
print(hub.list_datasets())

# Cargar cualquier capa como Polars DataFrame
comunas = hub.load_polars("comunas")
censo = hub.load_polars("censo_comunal")
salud = hub.load_polars("establecimientos_salud")

# Cruce garantizado: códigos CUT son VARCHAR, no int
df = comunas.join(censo, on="codigo_comuna")
print(df.head())

# Salud operativa del hub
print(hub.health())

La primera ejecución descarga el bundle validado desde GitHub Releases, verifica su integridad SHA256 y lo deja en cache local. También puedes prepararlo explícitamente:

chile-hub cache update     # Descargar el bundle más reciente
chile-hub cache status     # Ver ubicación y estado del cache
chile-hub cache clear      # Liberar espacio en disco

Consultas SQL 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';

Usar en scripts y producción

import polars as pl

comunas = pl.read_parquet("data/normalized/comunas.parquet")
censo = pl.read_parquet("data/normalized/censo_comunal.parquet")

# Cruce garantizado: códigos CUT son VARCHAR, no int
df = comunas.join(censo, on="codigo_comuna")
print(df.head())

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

Desarrollo local del pipeline

Si necesitas ejecutar el pipeline de extracción y build en tu máquina:

git clone https://github.com/cortega26/chile-hub.git
cd chile-hub
make bootstrap          # Crea .venv, instala dependencias + Playwright
make refresh            # extract → build → verify → test → pruebas de humo

Usa pip install chile-hub[pipeline] si quieres las dependencias completas del pipeline (DuckDB, Pandas, XlsxWriter, curl_cffi) pero sin clonar el repositorio.

Casos de uso listos para copiar

1. Ranking comunal con Censo 2024

from chile_hub import ChileHub

hub = ChileHub()
comunas = hub.load_polars("comunas")
censo = hub.load_polars("censo_comunal")

ranking = (
    comunas.join(censo, on="codigo_comuna")
    .select("codigo_comuna", "nombre_comuna", "nombre_region", "poblacion_censada")
    .sort("poblacion_censada", descending=True)
    .head(10)
)
print(ranking)

2. Ú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)

3. 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())

API Python compacta

API	Uso
`ChileHub()`	Inicializa el helper; descarga y verifica el bundle si no hay cache local.
`ChileHub(data_dir="data/normalized")`	Usa artefactos locales generados por el pipeline.
`hub.list_datasets()`	Lista los nombres canónicos disponibles para `load_polars()`.
`hub.load_polars("comunas")`	Carga una capa como `polars.DataFrame` desde Parquet.
`hub.summary()` / `hub.summary_table()`	Resume modo de fuente, filas, validación, frescura y warnings.
`hub.health()` / `hub.status()`	Reporta salud operativa para personas y CI/CD.
`hub.redistribution()`	Expone estado legal de reúso y atribución por dataset.
`hub.provenance()`	Muestra fuente, URL, modo de extracción y timestamps.
`chile-hub cache update/status/clear`	Administra el cache local del bundle publicado.

Arquitectura del Pipeline

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

[!IMPORTANTE] 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.

Extractores incluidos en el paso 1

Dominio	Extractores
Territorio	`subdere_extractor.py`, `electoral_extractor.py`
Demografía	`censo_extractor.py`, `censo_hogares_viviendas_extractor.py`, `pobreza_extractor.py`
Servicios públicos	`salud_extractor.py`, `mineduc_establecimientos_extractor.py`, `mineduc_resultados_extractor.py`
Economía	`bcentral_extractor.py`, `sinim_finanzas_extractor.py`, `sinim_finanzas_live_extractor.py`, `res_extractor.py`, `consumo_electrico_extractor.py`
Indicadores urbanos	`siedu_extractor.py`
Política	`partidos_politicos_extractor.py`, `autoridades_electas_extractor.py`, `autoridades_locales_extractor.py`
Seguridad (carril `candidate`)	`cead_delincuencia_live_extractor.py`

El mapeo autoritativo dataset ↔ extractor vive en data/dataset_catalog_config.json; esta tabla es solo orientativa. Detalle completo en AGENTS.md §2.

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

Grupo	Clave principal	Capas
Territorio base	`codigo_region`, `codigo_provincia`, `codigo_comuna`	`regiones`, `provincias`, `comunas`
Capas comunales	`codigo_comuna`	`comunas_enriquecidas`, `censo_comunal`, `censo_hogares_viviendas`, `establecimientos_salud`, `establecimientos_educacionales`, `distritos_electorales`
Series nacionales	`fecha`, `codigo_indicador`	`indicadores`

Ver schema completo con PK/FK

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"

Formatos de salida

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

Tipo	Archivo	Uso
Base de datos	`chile_data.duckdb`	Analítica local de alto rendimiento
Base de datos	`chile_data.db`	SQLite para aplicaciones embebidas
Intercambio	`chile_data_latest.xlsx`	Excel multipestaña (códigos CUT como texto)
Intercambio	`*.parquet` por capa	Polars / Pandas / DuckDB
Intercambio	`*.json` por capa	Pipelines y automatización
Metadatos	`artifact_manifest.json`	Catálogo físico con SHA256 y tamaños
Metadatos	`hub_health.json` / `.md`	Reporte de salud operativa
Metadatos	`dataset_status.json`	Estado machine-readable por dataset
Metadatos	`dataset_changelog.json`	Deltas de filas, campos, fuente y validación
Metadatos	`dataset_catalog.json` / `.md`	Catálogo con schemas y ejemplos
Metadatos	`redistribution_report.json` / `.md`	Estado legal de reúso por dataset
Metadatos	`provenance_report.json` / `.md`	Trazabilidad de origen y marcas de tiempo
Bundle	`chile-hub-publishable-bundle.zip`	Paquete público con verificación SHA256

CLI de referencia

El paquete instala el comando chile-hub en el PATH. Todos los subcomandos funcionan tanto desde PyPI como desde el entorno de desarrollo.

Inspección y consulta

Comando	Descripción
`chile-hub list`	Lista todos los datasets registrados
`chile-hub version`	Muestra la versión instalada del paquete
`chile-hub cache status`	Muestra ubicación y estado del cache local
`chile-hub cache update`	Descarga y verifica el bundle publicado
`chile-hub cache clear`	Elimina el cache local
`chile-hub show <capa>`	Schema y metadatos detallados de una capa
`chile-hub path <capa> --output parquet`	Ruta física al archivo de una capa
`chile-hub example <capa> --kind duckdb`	Receta de consumo lista para copiar y pegar
`chile-hub overview`	Resumen general del build y estado actual
`chile-hub inventory`	Archivos en `data/normalized/` con tamaños y hashes
`chile-hub snapshot`	Snapshot humano y compacto del hub
`chile-hub summary`	Resumen breve de datasets
`chile-hub search <keyword>`	Busca datasets por keyword, fuente o madurez
`chile-hub cross <a> <b>`	Cruza dos datasets por clave territorial común
`chile-hub export <capa> --output archivo`	Exporta un dataset a CSV, JSON o Parquet

Calidad, salud y auditoría

Comando	Descripción
`chile-hub health`	Reporte consolidado de salud del hub
`chile-hub freshness-audit`	Auditoría de frescura contra el reloj actual
`chile-hub runtime-status`	Salud registrada + vigencia en vivo
`chile-hub top-issue`	Capa con mayor degradación operativa
`chile-hub drift`	Desvíos, fallbacks activos y regresiones
`chile-hub status`	JSON ultraliviano para CI/CD
`chile-hub dataset-status`	Estado detallado machine-readable por dataset
`chile-hub dataset-changelog`	Cambios entre el build actual y el metadata anterior
`chile-hub source-readiness`	Madurez de fuente por dataset
`chile-hub dataset-quality`	Puntuación de calidad A-F por dataset
`chile-hub check-sources`	Verifica conectividad en vivo con las fuentes oficiales
`chile-hub validate <capa>`	Valida un dataset (o un CSV/Parquet propio) contra su schema

Distribución e integridad

Comando	Descripción
`chile-hub bundle`	Metadata consolidada en un solo JSON
`chile-hub redistribution`	Reporte legal de reúso por capa
`chile-hub provenance`	URLs de origen y métodos de extracción
`chile-hub verify-package`	Instrucción de verificación de integridad del ZIP
`chile-hub artifacts`	Artefactos publicables del hub
`chile-hub shared-artifacts`	Artefactos compartidos del hub (reportes, manifest)
`chile-hub reports`	Lista los reportes compartidos disponibles
`chile-hub report <nombre>`	Resuelve la metadata de un reporte compartido
`chile-hub packages`	Paquetes publicables del hub
`chile-hub package`	Metadata del package principal del hub

En entorno de desarrollo, usa python -m chile_hub o python -m src.chile_hub como alternativa al comando chile-hub si el paquete no está instalado en modo editable. Para el listado completo y siempre actualizado: chile-hub --help.

Desarrollo local

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

# Entorno
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

# Tests
./.venv/bin/pytest -v
./.venv/bin/pytest --cov=src --cov-report=term-missing --cov-report=xml
./.venv/bin/pytest tests/test_chile_hub.py::ChileHubTests::test_load_polars -v

Fuentes, licencias y reúso

Semáforo de redistribución

Color	Estado	Acción
🟢 `open-attribution`	CC BY, CC0 o equivalente	Se incluye en el bundle público
🟡 `public-api-review-terms`	API pública sin licencia explícita	Se distribuye tras verificar el origen primario
🔴 `restricted`	Derechos de autor, Ley 19.628	Nunca se integra al bundle público

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.

Próximos pasos

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

Horizonte	Foco	Entregable	Estado
Now	Ejemplos, notebooks, errores claros, referencia API	Usuarios cargan y cruzan datos sin leer el pipeline completo	🟢 En progreso
Next	Contratos de schema, source readiness, criterios públicos	Contribuidores proponen datasets con reglas claras y verificables	🔵 Planeado
Later	Nuevas capas solo si pasan criterios de inclusión	El catálogo crece sin perder mantenibilidad ni claridad legal	⚪ Futuro

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

¿Quieres contribuir?

Revisa AGENTS.md para entender la arquitectura, las reglas no negociables y el flujo de trabajo. 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.

Hecho con datos públicos chilenos, para quienes construyen sobre Chile.

_{Parte del ecosistema Tooltician — datos públicos, interoperables y listos para IA.}

Name		Name	Last commit message	Last commit date
Latest commit History 461 Commits
.agents/skills		.agents/skills
.codegraph		.codegraph
.continue/skills		.continue/skills
.github		.github
contracts/datasets		contracts/datasets
data		data
docs		docs
examples		examples
plans		plans
scripts		scripts
src		src
templates		templates
tests		tests
vendor		vendor
.codecov.yml		.codecov.yml
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CNAME		CNAME
CONTRIBUTING.md		CONTRIBUTING.md
DATA_LICENSES.md		DATA_LICENSES.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
SOURCE_OF_TRUTH.md		SOURCE_OF_TRUTH.md
app.js		app.js
index.html		index.html
lgtm.yml		lgtm.yml
mkdocs.yml		mkdocs.yml
playground.js		playground.js
privacy.html		privacy.html
pyproject.toml		pyproject.toml
robots.txt		robots.txt
sitemap.xml		sitemap.xml
skills-lock.json		skills-lock.json
social-card.png		social-card.png
uv.lock		uv.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

chile-hub

⚡ Instalar y usar en segundos

¿Por qué existe?

¿Qué entrega chile-hub?

Las 19 capas de datos

🔒 Por qué puedes confiar en estos datos

Respaldo adicional

Guía de uso

Consumir datos (instalación desde PyPI)

Consultas SQL con DuckDB

Usar en scripts y producción

Desarrollo local del pipeline

Casos de uso listos para copiar

API Python compacta

Arquitectura del Pipeline

Modelo de Datos — Códigos CUT

Formatos de salida

CLI de referencia

Inspección y consulta

Calidad, salud y auditoría

Distribución e integridad

Desarrollo local

Fuentes, licencias y reúso

Semáforo de redistribución

Licencia del proyecto

Próximos pasos

¿Quieres contribuir?

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 49

Sponsor this project

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages