argentina 0.1.1

Herramientas Python para datos públicos argentinos: provincias, departamentos, ciudades, geografía (IGN), economía (INDEC/BCRA), códigos postales, identificadores, EPH y más.

argentina

Herramientas para trabajar con datos de Argentina en Python.

Provincias

Acceso a las 24 provincias argentinas como constantes públicas, dataclasses frozen y lookup flexible.

import argentina as arg

arg.provincias.BUENOS_AIRES
arg.provincias.CORDOBA
arg.provincias.CABA

arg.provincias.lookup("PBA")
arg.provincias.lookup("Córdoba")
arg.provincias.lookup("14")
arg.provincias.lookup("AR-X")

arg.provincias.lookup("PBA").codigo_indec
arg.provincias.lookup("CABA").capital

Cada Provincia expone nombre, codigo_indec, iso_id, region y capital. lookup acepta nombre (con o sin tildes), código INDEC, ID ISO 3166-2 o alias comunes (PBA, CABA, bs as, TDF, etc.) y es case-insensitive. arg.provincias.listar() devuelve las 24 provincias.

Departamentos

API simple para departamentos argentinos.

import argentina as arg

arg.departamentos.lookup("06441")

arg.departamentos.lookup("Rosario")

arg.departamentos.por_provincia("Buenos Aires")

lookup acepta el código de departamento o un nombre único dentro del set embebido. Nombres ambiguos entre provincias (por ejemplo "Capital") devuelven None: para esos casos hay que usar el código ("14014") o un alias específico.

por_provincia acepta el nombre de la provincia (con o sin tildes) o su código INDEC, y devuelve una tupla de Departamento.

Por ahora el set incluye un subconjunto representativo de departamentos (no todos los del país) — la idea es validar la API antes de expandir.

Geo

El subpaquete arg.geo concentra herramientas geoespaciales.

Shapes

Geometrías oficiales de provincias y departamentos servidas por el Instituto Geográfico Nacional (IGN) vía WFS GeoServer. Ver fuente: Capas SIG del IGN.

API recomendada:

import argentina as arg

gdf = arg.geo.shapes.provincias()       # 24 polígonos del IGN
gdf = arg.geo.shapes.departamentos()    # 529 polígonos del IGN

Las columnas que devuelve son las del IGN: gid, entidad/objeto, fna (nombre completo), gna, nam (nombre corto), in1 (código INDEC), fdc, sag y geometry (CRS EPSG:4326 / WGS 84).

Instalación del extra geoespacial:

pip install "argentina[geo]"

También se puede pasar una URL alternativa con url=... (por ejemplo si tenés una capa propia en otro servidor). Los archivos descargados se cachean en ~/.cache/argentina/shapes/<nombre>/ — la primera llamada baja el ZIP del IGN (~45 MB provincias, ~57 MB departamentos), las siguientes son instantáneas. Pasá overwrite=True para forzar redescarga. Acepta archivos .gpkg, .geojson o .shp dentro del ZIP (prefiere .gpkg).

El paquete base no depende de geopandas ni requests para usar este módulo: todo se importa de forma diferida adentro de las funciones. Si llamás a geo.shapes.* sin haber instalado el extra [geo], vas a ver un ImportError con la instrucción de instalación.

Compatibilidad

El módulo anterior arg.shapes sigue funcionando como wrapper:

arg.shapes.provincias(url="...")  # equivalente a arg.geo.shapes.provincias

Es solo por compatibilidad — la API nueva es arg.geo.shapes.

Economía

El módulo argentina.economia da acceso a 493 series económicas oficiales de Argentina (INDEC, BCRA y SSPM), descargables desde la API de Series de Tiempo de datos.gob.ar.

Es un módulo opcional: requiere instalar pandas y requests, que no vienen con el paquete base.

Instalación:

pip install "argentina[economia]"

Después se importa explícitamente:

import argentina.economia as economia
# o
from argentina import economia

(No está en from argentina import * ni se carga al hacer import argentina, para mantener el paquete base liviano y sin pandas/requests.)

Incluye la familia completa del IPC base dic 2016 (núcleo, regulados, estacionales, bienes, servicios y 12 capítulos × 7 regiones), EMAE, IPI, ISAC, oferta y demanda globales, salarios, empleo, hidrocarburos y más.

Ejemplo básico:

from argentina.economia import ipc_nacional

df = ipc_nacional(start_date="2020-01-01")
print(df.head())

Acceder a cualquier serie del catálogo por alias:

from argentina.economia import serie

df = serie("emae_desestacionalizada", start_date="2020-01-01")

O directamente por ID:

from argentina.economia import obtener_serie

df = obtener_serie("148.3_INIVELNAL_DICI_M_26")

Explorar el catálogo

from argentina.economia import SERIES

print(len(SERIES))                       # 493
print(list(SERIES.keys())[:10])          # aliases disponibles
print(SERIES["ipc_nacional"])            # metadata de una serie

Cada entrada del catálogo trae id, descripcion, fuente, frecuencia, tema y dataset.

Buscar series por palabra clave

buscar filtra el catálogo local (sin red) por una palabra que aparezca en el alias, descripción o dataset:

from argentina.economia import buscar

buscar("salario").head()
buscar("petroleo")

Devuelve un DataFrame con alias, id, frecuencia, tema y descripcion.

Para ver la lista completa con descripciones, ver SERIES_DISPONIBLES.md.

Clean

Funciones básicas de limpieza de texto y columnas.

import argentina as arg

arg.clean.quitar_tildes("Córdoba")
arg.clean.normalizar_texto("  Código   de Provincia ")
arg.clean.snake_case("Código de Provincia")

Personas

Funciones básicas para limpiar, validar y normalizar identificadores y nombres argentinos.

import argentina as arg

arg.personas.limpiar_dni("12.345.678")
arg.personas.validar_dni("12.345.678")

arg.personas.limpiar_cuit("20-12345678-3")
arg.personas.extraer_dni_de_cuit("20-12345678-3")

arg.personas.normalizar_nombre(" María   Laura ")
arg.personas.primer_nombre("María Laura")
arg.personas.apellido_principal("Pérez Gómez")

Validación y formato de CUIT/CUIL

arg.personas.calcular_digito_cuit("2012345678")
arg.personas.validar_cuit("20-12345678-6")
arg.personas.validar_cuit("20-12345678-3")
arg.personas.validar_cuit("20-12345678-3", digito=False)

arg.personas.tipo_cuit("20-12345678-6")
arg.personas.formatear_dni("12345678")
arg.personas.formatear_cuit("20123456786")

validar_cuit valida dígito verificador por default usando el algoritmo oficial (multiplicadores 5 4 3 2 7 6 5 4 3 2, mod 11, con los wrap-around 10→9 y 11→0). Si solo querés chequear el largo (11 dígitos) sin validar dígito, pasá digito=False. tipo_cuit clasifica por prefijo en "persona_fisica" (20/23/24/27) o "persona_juridica" (30/33/34). formatear_dni/formatear_cuit devuelven los strings canónicos 12.345.678 y XX-XXXXXXXX-X.

Sigue todo sintáctico — no consulta AFIP, no usa pandas ni APIs externas.

Postal

Funciones para validar y parsear códigos postales argentinos.

import argentina as arg

arg.postal.validar_cp4("1425")
arg.postal.validar_cpa("C1425ABC")
arg.postal.extraer_cp4("C1425ABC")
arg.postal.provincia_por_cpa("X5000AAA")
arg.postal.validar_cpa_provincia("X5000AAA", "Córdoba")

Soporta los dos formatos vigentes:

• CP4 — código postal tradicional de 4 dígitos (ej. "1425").
• CPA — Código Postal Argentino de 8 caracteres: letra de provincia + 4 dígitos + 3 letras (ej. "C1425ABC").

tipo_codigo_postal discrimina entre los dos, extraer_cp4 te devuelve los 4 dígitos a partir de cualquiera de los dos formatos, y provincia_por_cpa usa la letra inicial para identificar la jurisdicción. validar_cpa_provincia chequea consistencia contra arg.provincias (acepta nombres con tildes, ISO, código INDEC, etc.).

Todo es sintáctico — no valida que el código existe físicamente. Para georreferenciación postal (mapear CPs a polígonos, validar contra un municipio real) están los placeholders en arg.geo.postal.

Educación

Funciones básicas para identificadores y categorías educativas argentinas.

import argentina as arg

arg.educacion.limpiar_cue("0201234-00")
arg.educacion.validar_cue("020123400")

arg.educacion.extraer_jurisdiccion_cue(
    "020123400"
)

arg.educacion.normalizar_sector("público")
arg.educacion.normalizar_ambito("urbano")
arg.educacion.normalizar_nivel("secundario")

Basemaps

Fondos cartográficos argentinos para Folium.

Instalación:

pip install "argentina[maps]"

import argentina as arg
import folium

m = folium.Map(location=[-34.6037, -58.3816], zoom_start=4, tiles=None)

arg.geo.basemaps.add_argenmap(m)
arg.geo.basemaps.add_creditos_argentina(m)
arg.geo.basemaps.add_layer_control(m)

m.save("mapa.html")

add_argenmap agrega como fondo el servicio Argenmap del IGN (tiles TMS oficiales). Usar tiles argentinos ayuda a que la toponimia preserve el nombre oficial de las Islas Malvinas (los proveedores extranjeros suelen rotularlas como "Falkland Islands"; las etiquetas viven dentro del raster y no se pueden reescribir desde el cliente).

add_creditos_argentina agrega un overlay HTML fijo con la attribution. add_layer_control agrega el control de capas de Folium para alternar entre fondos.

folium es opcional — instalar con el extra [maps]. Si llamás a basemaps.* sin tenerlo instalado vas a ver un ImportError con la instrucción.

Salud

Funciones básicas para normalizar variables frecuentes en datos administrativos de salud.

import argentina as arg

arg.salud.normalizar_sexo("femenino")
arg.salud.normalizar_sexo("varón")

arg.salud.normalizar_tipo_documento("dni")
arg.salud.limpiar_matricula("M.P. 12345")

arg.salud.grupo_etario(3)
arg.salud.edad_en_anios("2015-05-10", "2026-05-12")

normalizar_sexo mapea variantes (femenino/mujer/f, masculino/varón/hombre/m, no binario/otro/x) a F/M/X. grupo_etario clasifica edades en franjas estándar (0, 1-4, 5-9, 10-14, …, 55-64, 65+). edad_en_anios toma fechas como string ISO o date y respeta si ya cumplió años en la fecha de referencia.

Solo stdlib — sin curvas OMS, sin z-scores, sin pandas.

Elecciones

Limpieza y normalización de variables electorales argentinas.

import argentina as arg

arg.elecciones.limpiar_mesa("Mesa 01234")
arg.elecciones.limpiar_circuito(" 12-A ")

arg.elecciones.normalizar_categoria("Presidente")
arg.elecciones.normalizar_tipo_eleccion("PASO")

arg.elecciones.validar_anio_eleccion(2023)

arg.elecciones (core) corre con stdlib pura — sin internet, sin pandas.

Para wrappers sobre APIs electorales (resultados, escrutinios) está el submódulo opcional arg.elecciones.api, que importa requests/pandas de forma diferida:

import argentina as arg

print(arg.elecciones.api.disponible())
# {'requests': True, 'pandas': True}

datos = arg.elecciones.api.obtener_json(
    "https://URL_OFICIAL/resultados.json"
)

Instalación del extra:

pip install "argentina[elecciones]"

Importar argentina.elecciones no requiere internet ni el extra — sólo lo necesitás si llamás a las funciones de api. No hace scraping de padrón ni consulta datos personales.

Fechas

Funciones para parsear y normalizar fechas frecuentes en datos administrativos argentinos.

import argentina as arg

arg.fechas.parsear_fecha("31/12/2024")
arg.fechas.fecha_iso("31/12/2024")
arg.fechas.es_fecha_valida("31/12/2024")

arg.fechas.edad_en_anios(
    "10/05/2015",
    "12/05/2026",
)

arg.fechas.anio_lectivo("15/02/2024")
arg.fechas.cohorte_nacimiento("10/05/2015")
arg.fechas.mes_anio("31/12/2024")

parsear_fecha acepta los formatos más frecuentes en bases argentinas: dd/mm/yyyy, dd-mm-yyyy, yyyy-mm-dd, yyyy/mm/dd, y las variantes con año de 2 dígitos. También acepta date/datetime directamente y los devuelve sin re-parsear. fecha_iso reformatea cualquier formato soportado a YYYY-MM-DD.

anio_lectivo toma el calendario escolar argentino (arranca en marzo): enero y febrero quedan asignados al ciclo del año anterior. El mes de inicio es configurable con mes_inicio=. cohorte_nacimiento devuelve solo el año, y mes_anio lo reformatea a YYYY-MM para usar como clave de agregación mensual.

Solo stdlib — sin pandas, sin feriados, sin calendarios oficiales.

Feriados

Consulta de feriados argentinos desde una API pública (argentinadatos.com). Datos dinámicos, sin hardcodear nada y sin scraping.

Instalación:

pip install "argentina[feriados]"

import argentina as arg

arg.feriados.obtener(2026)
arg.feriados.es_feriado("2026-05-25")
arg.feriados.detalle("2026-05-25")
arg.feriados.proximo("2026-05-01")

obtener(anio) baja la lista completa de feriados del año y la cachea con lru_cache (32 años en memoria). Las funciones derivadas — es_feriado, detalle, proximo — reutilizan ese cache, así que después de la primera llamada por año no vuelven a pegar a la red.

proximo(desde=...) busca en el año en curso y, si no encuentra, salta al siguiente — útil para "qué feriado viene a partir de hoy" cerca de fin de año.

requests es opcional — instalar con el extra [feriados]. Importar argentina o argentina.feriados no requiere red ni el extra; las llamadas a la API son diferidas dentro de las funciones.

Teléfonos

Funciones básicas para limpiar y normalizar teléfonos argentinos.

import argentina as arg

arg.telefonos.limpiar("[phone]")
arg.telefonos.validar("[phone]")

arg.telefonos.extraer_caracteristica("[phone]")

arg.telefonos.es_celular("[phone]")

arg.telefonos.normalizar_e164("[phone]")

Maneja los formatos más frecuentes (+54, 54, 0, 9, 15, paréntesis, guiones, espacios) y los reduce a un número nacional de 10 dígitos. validar acepta el número si tiene exactamente 10 dígitos después de quitar prefijos. extraer_caracteristica devuelve "11" para AMBA y los 3 dígitos iniciales para el resto (heurística simple). es_celular reconoce los marcadores clásicos 9 (internacional) y 15 (local). normalizar_e164 produce el formato canónico +549... para celulares y +54... para fijos — si pasás celular=True/False forzás el resultado.

Todo es sintáctico — no consulta operadores ni valida que la línea exista.

Direcciones

Funciones básicas para normalizar y parsear direcciones argentinas.

import argentina as arg

direccion = "Av. Santa Fe 3253 Piso 2 Depto B"

arg.direcciones.normalizar(direccion)
arg.direcciones.extraer_calle(direccion)
arg.direcciones.extraer_altura(direccion)
arg.direcciones.extraer_piso(direccion)
arg.direcciones.extraer_departamento(direccion)
arg.direcciones.parsear(direccion)

normalizar baja a minúsculas, saca tildes y puntuación, colapsa espacios y unifica abreviaturas frecuentes (avenida/avda/av. → av, departamento/dpto/dto → depto, pje → pasaje, etc.). El resto de las funciones operan sobre la dirección normalizada:

• extraer_altura — primer número de hasta 5 dígitos.
• extraer_calle — todo lo que está antes de la altura.
• extraer_piso — busca piso N o p N, también PB.
• extraer_departamento — busca depto X, unidad X o uf X.
• tiene_altura — bool.
• parsear — un dict con todos los campos en una sola llamada.

Solo stdlib — sin geocoding, sin APIs externas, sin pandas. Para georreferenciación queda pendiente un módulo arg.geo.direcciones aparte.

Geo: direcciones

Georreferenciación de direcciones argentinas usando Georef.

Instalación:

pip install "argentina[georef]"

import argentina as arg

resultado = arg.geo.direcciones.georreferenciar(
    direccion="Av. Santa Fe 3253",
    provincia="CABA",
)
# {'nomenclatura': 'AV SANTA FE 3253, Comuna 14, ...',
#  'ubicacion': {'lat': -34.588..., 'lon': -58.410...},
#  'provincia': {'nombre': 'Ciudad Autónoma de Buenos Aires', ...}, ...}

lat, lon = arg.geo.direcciones.coordenadas(
    direccion="Av. Santa Fe 3253",
    provincia="CABA",
)

georreferenciar (alias: normalizar_georef) acepta filtros opcionales por provincia, departamento, localidad y max_resultados. Devuelve el primer resultado de la API como dict, o None si no hay match. coordenadas extrae directamente la tupla (lat, lon) del primer resultado.

argentina.direcciones (sin geo) hace parseo local sin red. La capa con red, normalización oficial y coordenadas reales es argentina.geo.direcciones, que importa requests de forma diferida — instalar el extra [georef].

Bancos

Funciones para identificadores bancarios argentinos.

import argentina as arg

arg.bancos.limpiar_cbu(
    "0170 0001 4000 0001 2345 67"
)

arg.bancos.validar_cbu(
    "2850590940090418135201"
)

arg.bancos.formatear_cbu(
    "2850590940090418135201"
)

arg.bancos.banco_por_cbu(
    "0170099120000067797370"
)

arg.bancos.validar_alias(
    "MI.ALIAS.CBU"
)

validar_cbu chequea los dos dígitos verificadores reales (algoritmo oficial: bloques [0:7]+dv y [8:21]+dv, pesos 7 1 3 9 7 1 3 y 3 9 7 1 3 9 7 1 3 9 7 1 3, (10 - suma % 10) % 10). codigo_banco_cbu extrae los primeros 3 dígitos y banco_por_cbu los resuelve contra arg.bancos.BANCOS (tabla mínima embebida — extensible).

validar_alias aplica las reglas básicas (6–20 chars, letras/números/./-, mayúsculas). limpiar_alias normaliza espacios y mayúsculas. validar_cvu hace por ahora el chequeo mínimo (22 dígitos) — los CVU de billeteras virtuales comparten el largo del CBU pero conviven con esquemas distintos por proveedor.

Solo stdlib — no consulta bancos online ni promete validación bancaria real.

Ciudades

Set curado de las principales ciudades del país (todas las capitales provinciales

• grandes aglomerados urbanos como Rosario, Mar del Plata, Bahía Blanca, etc.), con datos del Censo Nacional 2022 (INDEC).

import argentina as arg

arg.ciudades.lookup("Rosario")
arg.ciudades.lookup("CABA")          # alias
arg.ciudades.lookup("mardel")        # alias
arg.ciudades.lookup("tucuman")       # alias para San Miguel de Tucumán

arg.ciudades.top(5)                  # 5 más pobladas
arg.ciudades.por_provincia("Buenos Aires")
arg.ciudades.listar()                # todas
for c in arg.ciudades:               # iterable
    print(c.nombre, c.poblacion_2022)

Cada Ciudad trae nombre, provincia_codigo, provincia_nombre, poblacion_2022, lat y lon. La población corresponde al municipio/partido/ comuna (no al aglomerado urbano completo).

Población provincial: argentina.provincias.Provincia también tiene poblacion_2022 y capital_lat/capital_lon ahora — útil para ranking nacional, mapas con marcadores, etc.

top5 = sorted(arg.provincias, key=lambda p: p.poblacion_2022, reverse=True)[:5]
for p in top5:
    print(f"{p.nombre}: {p.poblacion_2022:,}".replace(",", "."))

Datos: Censo Nacional de Población, Hogares y Viviendas 2022 (INDEC).

Data

argentina.data está pensado para datasets públicos argentinos de mayor tamaño (microdatos EPH, Censo, etc.) que no tiene sentido empaquetar y que conviene descargar o consultar bajo demanda.

Instalación:

pip install "argentina[data]"

Esto suma pandas, requests, pyarrow y duckdb. Ninguno se importa al hacer import argentina — todo es diferido.

EPH (microdatos)

Descarga los microdatos trimestrales oficiales de la Encuesta Permanente de Hogares (INDEC) y los devuelve como pandas.DataFrame. La primera llamada baja el ZIP del INDEC (~3-5 MB), lo cachea en ~/.cache/argentina/eph/T<N>_<año>/ y lee el txt. Las siguientes son cache hits (sin red).

import argentina as arg

# Personas (encuesta individual)
ind = arg.data.eph(anio=2024, periodo="trimestral", numero=1, tipo="individual")
# Hogares
hog = arg.data.eph(anio=2024, periodo="trimestral", numero=1, tipo="hogar")

Soporta:

• periodo (aliases: "T", "trim", "trimestre", "trimestral"). La semestral (pre-2003) queda como NotImplementedError.
• numero: 1-4.
• tipo: "individual" / "personas" o "hogar" / "hogares".
• cache_dir: directorio alternativo de cache.

Las columnas son las del INDEC tal cual (CODUSU, CH04 sexo, CH06 edad, PONDERA ponderador, P21 ingreso, ESTADO ocupación, REGION, etc.).

Censo 2022

Arquitectura DuckDB + Parquet remoto: arg.data.censo(...) arma una query SELECT ... FROM read_parquet('https://...') y trae solo las filas/columnas pedidas (no descarga el dataset entero).

df = arg.data.censo(
    anio=2022,
    tabla="personas",
    provincia="Córdoba",       # cualquier identificador de arg.provincias.lookup
    departamento="14014",       # opcional
    limite=10000,
)

Estado: el INDEC todavía no publica microdatos del Censo 2022 como parquets oficiales accesibles vía HTTPS. CENSO_PARQUETS_2022 viene vacío por default. Para usarlo, configurá la URL (mirror propio o, cuando aparezca, oficial):

import argentina.data.censo as c
c.CENSO_PARQUETS_2022["personas"] = "https://mi-mirror/personas.parquet"

# o pasarla directamente
arg.data.censo(anio=2022, url="https://mi-mirror/personas.parquet", limite=100)

Si llamás arg.data.eph(...) o arg.data.censo(...) sin haber instalado el extra [data], vas a ver un ImportError con la instrucción de instalación.