DEV Community

Cover image for ubigeo-fns: Librería TypeScript para UBIGEO del Perú
Franco Caballero
Franco Caballero

Posted on

ubigeo-fns: Librería TypeScript para UBIGEO del Perú

#node #javascript #typescript #opensource

🚀 Introducción

ubigeo-fns es una librería en TypeScript para trabajar de forma sencilla y eficiente con códigos UBIGEO del Perú.

Permite obtener información de:

  • Departamento
  • Provincia
  • Distrito
  • Coordenadas geográficas
  • Población y área
  • Búsqueda por nombre

Todo basado en datos oficiales del INEI.

✨ ¿Para qué sirve?

Esta librería resuelve el problema de manejar ubicaciones en Perú sin lógica repetitiva:

  • Convertir un código UBIGEO en ubicación legible
  • Validar códigos de forma estricta
  • Obtener jerarquía geográfica completa
  • Buscar ubicaciones por nombre
  • Construir formularios dependientes (departamento → provincia → distrito)

⚡ Características

  • 🔎 Búsqueda rápida O(1) con Map y Set
  • 🧠 Validación estricta de UBIGEO
  • 🌎 Datos completos (INEI + geolocalización)
  • 🔤 Búsqueda por nombre (searchByName)
  • ⚡ Optimizado para Node.js y frontend
  • 📦 Compatible con ESM y TypeScript
  • 🌳 Soporta tree-shaking

📦 Instalación 

npm install ubigeo-fns
Enter fullscreen mode Exit fullscreen mode

🧪 Uso básico 

import {
  getDepartment,
  getProvince,
  getDistrict,
  validateUbigeo,
  formatUbigeo
} from "ubigeo-fns";

const ubigeo = "150131";

getDepartment(ubigeo); // Lima
getProvince(ubigeo);   // Lima
getDistrict(ubigeo);   // San Isidro

validateUbigeo(ubigeo); // true

formatUbigeo(ubigeo); // "San Isidro, Lima, Lima"
Enter fullscreen mode Exit fullscreen mode

🔎 Búsqueda por nombre

Permite buscar ubicaciones sin conocer el código UBIGEO:

import { searchByName } from "ubigeo-fns";

searchByName("San Isidro");
Enter fullscreen mode Exit fullscreen mode

✔ soporta coincidencias parciales
✔ case-insensitive
✔ útil para autocompletados

📚 API principal 

getDepartment(ubigeo)
getProvince(ubigeo)
getDistrict(ubigeo)

getDepartments()
getProvinces(code)
getDistricts(code)

getUbigeoData(ubigeo)
parseUbigeo(ubigeo)
formatUbigeo(ubigeo)

validateUbigeo(ubigeo)
searchByName(name)

isValidDepartment(code)
isValidProvince(code)
isValidDistrict(code)
Enter fullscreen mode Exit fullscreen mode

📍 Ejemplo completo 

const data = getUbigeoData("150131");

console.log(data);

/*
{
  ubigeo: "150131",
  district: "San Isidro",
  province: "Lima",
  department: "Lima",
  population: 60367,
  area: 9.36,
  lat: -12.0989,
  lng: -77.0434
}
*/
Enter fullscreen mode Exit fullscreen mode

🧱 Tipo principal 

interface UbigeoData {
  ubigeo: string;
  district: string;
  province: string;
  department: string;
  population: number;
  area: number;
  lat: number;
  lng: number;
}
Enter fullscreen mode Exit fullscreen mode

⚙️ Rendimiento

  • Antes: búsquedas con find() → O(n)
  • Ahora: Map / Set → O(1)

📦 Casos de uso

  • Formularios con selects dependientes
  • Sistemas de facturación (Sunat)
  • Apps de delivery
  • CRMs
  • Dashboards geográficos

⚠️ Notas

  • Incluye dataset completo del INEI
  • Optimizado para Node.js y frontend moderno
  • Compatible con tree-shaking

🧠 Resumen

ubigeo-fns simplifica el trabajo con ubicaciones en Perú:

rápido, tipado, validado y listo para producción

🔗 Links

Top comments (0)