Zero dependencies · TypeScript · Tree-shakeable

Table of Contents

• Table of Contents
• Why?
• Install
• Quick Start
• Available Locales
• API Reference
• Bundle Size
• Contributing
• License
• Documentation
• Contributors

Why?

Often you need lists of departments/provinces and municipalities/cities for address forms, but APIs are slow or existing libraries are heavy and contain data from the whole world.

soff-geo provides a modular solution where you import only the country data you need.

Install

npm install soff-geo

Quick Start

// Only Colombia included in bundle
import { getDepartments, getMunicipalities, searchMunicipalities } from 'soff-geo/co';

// Get all departments
const departments = getDepartments();
// [{ code: '05', name: 'Antioquia', ... }, ...]

// Get municipalities for a department
const antioquiaMunis = getDepartmentMunicipalities('05');
// [{ code: '05001', name: 'Medellín', ... }, ...]

// Search
const results = searchMunicipalities('medellin');
// [{ item: { name: 'Medellín', ... }, score: 1 }]

Available Locales

| Locale | Import | Data | | ----------- | ------------- | --------------------------- | | 🇨🇴 Colombia | soff-geo/co | Departments, Municipalities | | 🇲🇽 México | soff-geo/mx | States, Municipalities |

API Reference

Each locale exports a consistent set of functions:

getDepartments() / getStates()

Returns the list of all first-level administrative divisions.

getMunicipalities()

Returns the list of all available municipalities.

getDepartment(code) / getState(code)

Finds a department/state by its official code.

getMunicipality(code)

Finds a municipality by its official code.

getDepartmentMunicipalities(code) / getStateMunicipalities(code)

Returns all municipalities belonging to a specific department/state.

searchDepartments(query) / searchStates(query)

Search for departments/states by name or code.

searchMunicipalities(query)

Search for municipalities by name or code.

Bundle Size

| Import | Size (minified) | | ------------ | --------------- | | locales/co | ~21KB | | locales/mx | ~52KB | | Core only | ~1.2KB |

Tree-shaking ensures you only ship what you import.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

• Español

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!