censoargentino

Cliente Python para consultar el Censo Nacional de Población, Hogares y Viviendas 2022 de Argentina (INDEC).

Usa DuckDB para hacer consultas directas sobre archivos Parquet remotos, descargando solo los datos que necesitás sin bajar el dataset completo (~137 MB).

Instalación

pip install censoargentino

Instalación con soporte MCP

Para usar el paquete como servidor MCP (compatible con Claude Desktop, Cursor, Cline y otros):

pip install "censoargentino[mcp]"

Configuración en cualquier cliente MCP:

{
  "mcpServers": {
    "censoargentino": {
      "command": "python",
      "args": ["-m", "censoargentino.mcp_server"]
    }
  }
}

Ver MCP.md para documentación completa del servidor.

Uso rápido

import censoargentino as censo

# Tabla resumida con N y % — una sola línea
censo.tabla("PERSONA_P02")
#           categoria         N     %
# Mujer / Femenino     23607906  51.8
# Varón / Masculino    22010881  48.2

# Filtrado por provincia
censo.tabla("HOGAR_NBI_TOT", provincia="Chaco")

# Filtrado por departamento — por nombre o código INDEC
censo.tabla("HOGAR_NBI_TOT", provincia="Buenos Aires", departamento="Lanús")
censo.tabla("HOGAR_NBI_TOT", provincia="Buenos Aires", departamento="490")  # equivalente

# Comparación entre provincias
censo.comparar("HOGAR_NBI_TOT")
#               Con NBI  Sin NBI    Total
# Formosa          26.0     74.0   173500
# Chaco            24.9     75.1   393500
# ...

# Datos crudos (formato largo por radio censal)
df = censo.query(variables="PERSONA_P02", provincia="Córdoba")

¿De dónde vienen los datos?

Los datos corresponden a la 1ª entrega definitiva del CPV 2022 (publicada por INDEC en diciembre de 2024).

Pipeline de procesamiento:

INDEC (base REDATAM .rxdb)
        ↓
  redatamx (R)  →  extracción de variables
        ↓
  formato largo Parquet  →  censo-2022-largo.parquet
  metadatos Parquet      →  censo-2022-metadatos.parquet
  radios censales        →  radios-2022.parquet  (fuente: CONICET)
        ↓
  Hugging Face Datasets  →  pedroorden/censoargentino
        ↓
  censoargentino (este paquete)  →  consultas eficientes vía DuckDB

Cobertura: Vivienda · Hogar · Persona — desagregación hasta radio censal.

La 2ª entrega (localidades y aglomerados) está prometida por INDEC sin fecha confirmada.

Estructura del resultado

query() devuelve formato largo pre-agregado: cada fila es una combinación de (radio censal × categoría × conteo).

id_geo     | codigo_variable | valor_categoria | etiqueta_categoria   | conteo | etiqueta_provincia | ...
460070101  | PERSONA_P02     | 1               | Mujer / Femenino     |    252 | La Rioja           | ...
460070101  | PERSONA_P02     | 2               | Varón / Masculino    |    231 | La Rioja           | ...

tabla() y comparar() hacen la agregación por vos.

Referencia de la API

Descubrimiento

Análisis

Datos crudos

Configuración

Variables principales

Explorá el catálogo completo con censo.variables().

Ejemplos de análisis

import censoargentino as censo

# NBI por provincia — tabla comparativa
censo.comparar("HOGAR_NBI_TOT")

# Nivel educativo en departamentos de Tucumán
censo.comparar("PERSONA_MNI", nivel="departamento", provincia="Tucumán")

# Distribución de sexo en CABA
censo.tabla("PERSONA_P02", provincia="02")

# Departamento por nombre
censo.tabla("VIVIENDA_TIPOVIVG", provincia="Buenos Aires", departamento="Lanús")

# Datos crudos + agregación manual
df = censo.query(variables="PERSONA_MNI", provincia="Santa Fe")
censo.agregar(df, por="departamento")

Créditos

La extracción de los datos desde la base REDATAM del INDEC fue realizada con R por Nissim Lebovits en el proyecto ciut-redatam, usando redatamx. censoargentino construye sobre esa base para ofrecer acceso desde Python.

Fuentes y documentación

• Dataset en Hugging Face
• Base REDATAM — INDEC
• Definiciones de variables (PDF)
• redatamx — herramienta de procesamiento
• Portal REDATAM online