The latest articles on Forem by Franco Caballero (@hansgianfranco). https://forem.com/hansgianfranco https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F1673199%2F74910adf-c779-4725-b8c0-32be2f477355.jpg https://forem.com/hansgianfranco en Franco Caballero Tue, 14 Apr 2026 04:50:38 +0000 https://forem.com/hansgianfranco/ubigeo-fns-libreria-typescript-para-ubigeo-del-peru-3mbe https://forem.com/hansgianfranco/ubigeo-fns-libreria-typescript-para-ubigeo-del-peru-3mbe <h2> 🚀 Introducción </h2> <p><strong>ubigeo-fns</strong> es una librería en <strong>TypeScript</strong> para trabajar de forma sencilla y eficiente con códigos <strong>UBIGEO del Perú</strong>.</p> <p>Permite obtener información de:</p> <ul> <li>Departamento</li> <li>Provincia</li> <li>Distrito</li> <li>Coordenadas geográficas</li> <li>Población y área</li> <li>Búsqueda por nombre</li> </ul> <p>Todo basado en datos oficiales del <strong>INEI</strong>.</p> <h2> ✨ ¿Para qué sirve? </h2> <p>Esta librería resuelve el problema de manejar ubicaciones en Perú sin lógica repetitiva:</p> <ul> <li>Convertir un código UBIGEO en ubicación legible</li> <li>Validar códigos de forma estricta</li> <li>Obtener jerarquía geográfica completa</li> <li>Buscar ubicaciones por nombre</li> <li>Construir formularios dependientes (departamento → provincia → distrito)</li> </ul> <h2> ⚡ Características </h2> <ul> <li>🔎 Búsqueda rápida O(1) con Map y Set</li> <li>🧠 Validación estricta de UBIGEO</li> <li>🌎 Datos completos (INEI + geolocalización)</li> <li>🔤 Búsqueda por nombre (<code>searchByName</code>)</li> <li>⚡ Optimizado para Node.js y frontend</li> <li>📦 Compatible con ESM y TypeScript</li> <li>🌳 Soporta tree-shaking</li> </ul> <h2> 📦 Instalación </h2> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>npm <span class="nb">install </span>ubigeo-fns </code></pre> </div> <h2> 🧪 Uso básico </h2> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">getDepartment</span><span class="p">,</span> <span class="nx">getProvince</span><span class="p">,</span> <span class="nx">getDistrict</span><span class="p">,</span> <span class="nx">validateUbigeo</span><span class="p">,</span> <span class="nx">formatUbigeo</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">"</span><span class="s2">ubigeo-fns</span><span class="dl">"</span><span class="p">;</span> <span class="kd">const</span> <span class="nx">ubigeo</span> <span class="o">=</span> <span class="dl">"</span><span class="s2">150131</span><span class="dl">"</span><span class="p">;</span> <span class="nf">getDepartment</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">);</span> <span class="c1">// Lima</span> <span class="nf">getProvince</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">);</span> <span class="c1">// Lima</span> <span class="nf">getDistrict</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">);</span> <span class="c1">// San Isidro</span> <span class="nf">validateUbigeo</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">);</span> <span class="c1">// true</span> <span class="nf">formatUbigeo</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">);</span> <span class="c1">// "San Isidro, Lima, Lima"</span> </code></pre> </div> <h2> 🔎 Búsqueda por nombre </h2> <p>Permite buscar ubicaciones sin conocer el código UBIGEO:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="k">import</span> <span class="p">{</span> <span class="nx">searchByName</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">"</span><span class="s2">ubigeo-fns</span><span class="dl">"</span><span class="p">;</span> <span class="nf">searchByName</span><span class="p">(</span><span class="dl">"</span><span class="s2">San Isidro</span><span class="dl">"</span><span class="p">);</span> </code></pre> </div> <p>✔ soporta coincidencias parciales<br> ✔ case-insensitive<br> ✔ útil para autocompletados</p> <h2> 📚 API principal </h2> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="nf">getDepartment</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">getProvince</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">getDistrict</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">getDepartments</span><span class="p">()</span> <span class="nf">getProvinces</span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> <span class="nf">getDistricts</span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> <span class="nf">getUbigeoData</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">parseUbigeo</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">formatUbigeo</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">validateUbigeo</span><span class="p">(</span><span class="nx">ubigeo</span><span class="p">)</span> <span class="nf">searchByName</span><span class="p">(</span><span class="nx">name</span><span class="p">)</span> <span class="nf">isValidDepartment</span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> <span class="nf">isValidProvince</span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> <span class="nf">isValidDistrict</span><span class="p">(</span><span class="nx">code</span><span class="p">)</span> </code></pre> </div> <h2> 📍 Ejemplo completo </h2> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="kd">const</span> <span class="nx">data</span> <span class="o">=</span> <span class="nf">getUbigeoData</span><span class="p">(</span><span class="dl">"</span><span class="s2">150131</span><span class="dl">"</span><span class="p">);</span> <span class="nx">console</span><span class="p">.</span><span class="nf">log</span><span class="p">(</span><span class="nx">data</span><span class="p">);</span> <span class="cm">/* { ubigeo: "150131", district: "San Isidro", province: "Lima", department: "Lima", population: 60367, area: 9.36, lat: -12.0989, lng: -77.0434 } */</span> </code></pre> </div> <h2> 🧱 Tipo principal </h2> <div class="highlight js-code-highlight"> <pre class="highlight typescript"><code><span class="kr">interface</span> <span class="nx">UbigeoData</span> <span class="p">{</span> <span class="nl">ubigeo</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">district</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">province</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">department</span><span class="p">:</span> <span class="kr">string</span><span class="p">;</span> <span class="nl">population</span><span class="p">:</span> <span class="kr">number</span><span class="p">;</span> <span class="nl">area</span><span class="p">:</span> <span class="kr">number</span><span class="p">;</span> <span class="nl">lat</span><span class="p">:</span> <span class="kr">number</span><span class="p">;</span> <span class="nl">lng</span><span class="p">:</span> <span class="kr">number</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <h2> ⚙️ Rendimiento </h2> <ul> <li>Antes: búsquedas con <code>find()</code> → O(n)</li> <li>Ahora: Map / Set → O(1)</li> </ul> <h2> 📦 Casos de uso </h2> <ul> <li>Formularios con selects dependientes</li> <li>Sistemas de facturación (Sunat)</li> <li>Apps de delivery</li> <li>CRMs</li> <li>Dashboards geográficos</li> </ul> <h2> ⚠️ Notas </h2> <ul> <li>Incluye dataset completo del INEI</li> <li>Optimizado para Node.js y frontend moderno</li> <li>Compatible con tree-shaking</li> </ul> <h2> 🧠 Resumen </h2> <p><strong>ubigeo-fns</strong> simplifica el trabajo con ubicaciones en Perú:</p> <blockquote> <p>rápido, tipado, validado y listo para producción</p> </blockquote> <h2> 🔗 Links </h2> <ul> <li>📦 npm: <a href="https://www.npmjs.com/package/ubigeo-fns" rel="noopener noreferrer">https://www.npmjs.com/package/ubigeo-fns</a> </li> <li>💻 GitHub: <a href="https://github.com/hansgianfranco/ubigeo-fns" rel="noopener noreferrer">https://github.com/hansgianfranco/ubigeo-fns</a> </li> </ul> typescript node javascript opensource