Colombia Open

Datasets públicos de Colombia, curados, normalizados y validados, para que cualquiera los use desde Python sin lidiar con los portales, APIs y Excels inconsistentes de cada institución oficial.

from colombia_open import ColombiaOpen

hub = ColombiaOpen()
municipios = hub.load_polars("municipios")
departamentos = hub.load_polars("departamentos")

Proyecto en MVP activo. Tres fuentes están implementadas (DIVIPOLA: departamentos + municipios, DANE; demografía: proyecciones de población municipal, DANE; y educación: directorio de establecimientos, MEN). Publicado en PyPI (pip install colombia-open), con GitHub Releases para el bundle de datos y landing page en vivo en davidcasr.com/colombia-open — ver Estado del proyecto.

Por qué existe

Los datos públicos de Colombia existen, son abiertos, y están dispersos en decenas de portales con formatos, convenciones de código y calidad de API distintas (DANE, IDEAM, ICFES, DNP, Banco de la República, XM...). El trabajo real casi nunca es "¿existe el dato?" sino "¿cuánto tiempo me toma normalizarlo, validarlo, y confiar en que no tiene errores silenciosos (ej. un código de municipio que perdió el cero inicial en Excel)?"

colombia-open hace ese trabajo una vez, por fuente, y lo distribuye como tablas Polars/Parquet listas para usar — con su fuente oficial, licencia y fecha de actualización siempre visibles.

Instalación

pip install colombia-open

Para correr el pipeline localmente (extraer datos en vivo, no solo leerlos):

git clone https://github.com/davidcasr/colombia-open.git
cd colombia-open
make bootstrap   # crea .venv e instala con extras pipeline+dev
make build       # extract -> normalize -> validate -> data/normalized/
make test

Uso

from colombia_open import ColombiaOpen

hub = ColombiaOpen()

hub.list_datasets()
# ["departamentos", "municipios", "demografia", "educacion_establecimientos",
#  "delincuencia_hurto_personas", "delincuencia_lesiones_personales",
#  "delincuencia_hurto_modalidades"]

municipios = hub.load_polars("municipios")
municipios.filter(municipios["cod_dpto"] == "05")  # municipios de Antioquia

hub.resolve_municipios(["Medellín", "cali", "BOGOTA"])
# resuelve nombres a código DIVIPOLA, sin fuzzy matching (coincidencia exacta
# normalizada: sin tildes, minúsculas)

hub.cross_view(["municipios", "departamentos"], on="cod_dpto")
# join listo entre dos datasets que comparten una clave territorial

hub.provenance("municipios")
# {"source_name": "DANE — DIVIPOLA...", "source_url": "...", "source_mode": "live", ...}

CLI equivalente:

colombia-open list
colombia-open show municipios
colombia-open path municipios --output parquet
colombia-open example municipios --kind python
colombia-open validate municipios

Datasets disponibles

Ver docs/roadmap/roadmap.md para las ~14 fuentes mapeadas (implementadas y pendientes) y docs/licenses/data_licenses.md para el detalle legal de cada una.

Instalación con extras

pip install "colombia-open[pipeline]"

Servidor MCP

pip install "colombia-open[mcp]"
colombia-open mcp   # stdio — agregalo como comando en tu cliente MCP

Config típica de cliente MCP (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "colombia-open": { "command": "colombia-open", "args": ["mcp"] }
  }
}

Expone 3 tools: list_datasets(), describe_dataset(dataset) (metadata + esquema de columnas) y query(sql, limit=None) — SQL de solo lectura contra todos los datasets como tablas nombradas, con JOIN entre datasets en una sola query. Las filas siempre se limitan automáticamente (hasta 1000) para no volcarle a un agente un dataset de 600k filas crudo. Detalle completo, incluida la validación de seguridad del SQL, en docs/mcp.md.

Filosofía: una fuente por fin de semana

Este proyecto no se construye de golpe. Cada fuente nueva se implementa de punta a punta (extractor + builder + validación + registro + tests + docs) antes de empezar la siguiente. El resto de las fuentes candidatas quedan mapeadas en docs/roadmap/roadmap.md con su dificultad de acceso, sin implementar, hasta que les toque su turno.

La razón de ingeniería: la prioridad #1 no es "cuántas fuentes tenemos" sino "qué tan fácil es agregar la fuente número N+1 sin releer todo el código cada vez" — por eso existe la skill .claude/skills/new-source/ y el comando /next-source. Ver CLAUDE.md para el detalle completo.

Arquitectura

src/
├── colombia_open/     # librería pública (pip install), deps livianas
├── extractors/        # uno por fuente institucional — fetch + fallback + raw snapshot
├── builders/          # staging -> normalizado (parquet/json) + catálogo
├── validation/        # reglas por dominio, funciones puras
└── registry/          # qué datasets existen, su esquema y su licencia

data/
├── raw/           # snapshots crudos, write-once (no se edita después)
├── staging/       # CSV normalizado + metadata.json por extractor
├── normalized/    # parquet/json finales + dataset_catalog.json (lo que lee la librería)
└── registry/      # datasets.json — fuente de verdad estática del registro

La librería pública (colombia_open/) nunca importa código de pipeline (extractors/, builders/, validation/) — así pip install colombia-open se mantiene liviano. El primer uso descarga y cachea el bundle de datos publicado en GitHub Releases (con verificación SHA256); en desarrollo, lee directamente data/normalized/ si ya corriste make build.

Estado del proyecto

• ✅ Patrón extractor/builder/validación/registro probado con seis fuentes (DIVIPOLA, demografía, educación y tres de delincuencia) de dominios distintos (API Socrata pequeña, descarga directa de Excel, API Socrata grande y paginada).
• ✅ GitHub Releases publicados (último: v0.7.0, bundle de datos con SHA256, incluye las seis fuentes) — ColombiaOpen() descarga y cachea el bundle automáticamente sin tener que correr el pipeline localmente (ver data_manager.py). Convención de versionado: .claude/rules/releases.md.
• ✅ Publicado en PyPI (pip install colombia-open, trusted publishing vía .github/workflows/publish.yml, sin token almacenado) — verificado end-to-end el 2026-10-18 instalando desde PyPI real en un venv limpio: los 4 datasets cargan correctamente.
• ✅ Servidor MCP (desde v0.4.0, extra mcp): agentes de IA pueden listar, describir y consultar con SQL de solo lectura todo el catálogo vía colombia-open mcp — ver Servidor MCP y docs/mcp.md.
• ✅ Landing page (site/, ver docs/brand/design-system.md) deployada en davidcasr.com/colombia-open.
• Ver docs/roadmap/roadmap.md para qué sigue.

Legal

El código es MIT (LICENSE). Cada dataset conserva la licencia de su fuente original — ver docs/licenses/data_licenses.md antes de redistribuir cualquier dataset fuera de este paquete.

Contribuir

Hecho por David Castro. El flujo de trabajo está pensado para sesiones de Claude Code recurrentes — ver CLAUDE.md si vas a contribuir con un agente de IA.