geo-latam

Typed Latin America administrative divisions for JavaScript and TypeScript.

V1 includes Mexico states and municipalities only. It intentionally excludes localities, colonias, ejidos, settlements, streets, and postal-level data.

The Mexico dataset is generated from INEGI's Catálogo Único de Claves Geoestadísticas:

• States: https://gaia.inegi.org.mx/wscatgeo/v2/mgee/
• Municipalities: https://gaia.inegi.org.mx/wscatgeo/v2/mgem/{state_code}

Install

bun add geo-latam

npm install geo-latam

Usage

import {
  formatLocation,
  getMunicipalities,
  getStates,
  isValidMunicipality,
} from 'geo-latam'

const states = getStates('MX')
const jalisco = states.find((state) => state.name === 'Jalisco')

if (jalisco) {
  const municipalities = getMunicipalities('MX', jalisco.code)
  console.log(municipalities)
}

console.log(isValidMunicipality('MX', '14', '039')) // true
console.log(formatLocation({ countryCode: 'MX', stateCode: '14', municipalityCode: '039' }))
// Guadalajara, Jalisco, México

API

getCountries()
getCountry(countryCode)
getStates(countryCode)
getState(countryCode, stateCode)
getMunicipalities(countryCode, stateCode)
getMunicipality(countryCode, stateCode, municipalityCode)
isSupportedCountry(countryCode)
isValidState(countryCode, stateCode)
isValidMunicipality(countryCode, stateCode, municipalityCode)
formatLocation({ countryCode, stateCode, municipalityCode })

Codes

For Mexico:

• countryCode: ISO 3166-1 alpha-2, currently MX
• stateCode: INEGI AGEE, two digits, for example 14
• municipalityCode: INEGI AGEM, three digits, for example 039

Data philosophy

Public APIs return typed objects, not positional arrays. Internally, the package may use generated compact data structures in the future if bundle size requires it, but consumers should never have to know or care about that representation.

Updating Mexico data

bun run update:mx
bun test

The runtime package has no network dependency. The update script is only for maintainers.

LatAm roadmap

The API is intentionally country-first so Argentina, Colombia, Chile, Peru, and other LatAm countries can be added later without changing the public function signatures.