@xinnovations/atlas

A modern, type-safe TypeScript library for World countries, states, and cities with zero dependencies.

Features

• 🎯 TypeScript First - Full type safety with comprehensive type definitions
• 📦 Zero Dependencies - Lightweight and fast
• 🌍 Global Data - Countries, states, and cities worldwide
• 🔍 Powerful Search - Find locations with accent-insensitive ranked matching
• ✅ Well Tested - Verified reliability

Installation

npm install @xinnovations/atlas

Quick Start

import { getStates, getCities, searchCountries } from '@xinnovations/atlas';

// Get states for a country
const states = getStates('United States');
console.log(states);

// Get cities for a state
const cities = getCities('Nigeria', 'Lagos');
console.log(cities); // ['Ikeja', 'Lekki', ...]

// Search for a country
const results = searchCountries('united');
console.log(results);

Available Functions

Core Functions

getCountries() · getCountry(name) · getStates(country) · getState(country, state) · getCities(country, state)

Search Functions

searchCountries(query) · searchStates(query) · searchCities(query)

Data Coverage

• Countries: 250
• States / provinces / territories: 4,964
• Cities / towns / populated places: 148,512

Coverage is broad, but it is not exhaustive and it should not be treated as official administrative data. If you find gaps or bad assignments, open an issue or send a PR with a source.

Data Sources

This package is assembled from public geographic datasets and curated fixes, including:

• GeoNames data exports: https://www.geonames.org/export/
• official administrative listings where available
• election and local government office directories used for spot verification

Documentation

📚 Full Documentation - Comprehensive guides and API reference (Coming Soon)

🤝 Contributing - Help improve this package

TypeScript Support

import type { Country, State } from '@xinnovations/atlas';

const country: Country | undefined = getCountry('Canada');

License

MIT © Solomon Olatunji

Made with ❤️ in Nigeria 🇳🇬 for the World 🌍