@innovayse/geo-atlas
v2.2.0
Published
Offline countries, states and cities with multilingual support (EN/RU/HY + 15 languages).
Maintainers
Readme
@innovayse/geo-atlas
Offline countries, states and cities database with complete multilingual support. Zero API calls — all data is bundled locally.
Features
- 250 countries with ISO2/ISO3 codes, flags, phone codes, phone format placeholders, capitals, coordinates
- 147,000+ cities across all countries with coordinates
- Complete multilingual city names: English, Russian (ru), Armenian (hy) + 15 more languages
- Country translations: all 250 countries translated to Russian and Armenian
- Native script support for each city and country
- Phone format placeholders for all 250 countries (e.g.
+374 9X XXX XXXfor Armenia) - Dual ESM + CJS build — works in browsers, Node.js, Nuxt 3, Vite
- TypeScript — full type declarations included
- Zero runtime dependencies — fully offline, no API calls
Installation
npm install @innovayse/geo-atlasUsage
Get all countries
import { CountriesAtlas } from '@innovayse/geo-atlas'
const countries = CountriesAtlas.getCountries()
// [{ iso2: 'AM', name: 'Armenia', native: 'Հայաստան', emoji: '🇦🇲', phone: 374, ... }]Find a country by ISO2
const armenia = CountriesAtlas.find('AM')
// { iso2: 'AM', name: 'Armenia', translations: { hy: 'Հայաստան', ru: 'Армения' }, ... }Lightweight entry — country list without the city dataset (/lite)
CountriesAtlas bundles the per-country state/city dataset (~171 MB across ~250
code-split chunks) because of its getStates* methods. If you only need the
country list (names, translations, phone codes, currencies, timezones) —
which is the common case on server-rendered pages — import from /lite. It loads
only the small atlas.json and never references the per-country dataset, so
bundlers don't have to process (or run out of memory on) the 171 MB:
import CountriesData from '@innovayse/geo-atlas/lite'
const countries = CountriesData.getCountries()
const armenia = CountriesData.find('AM')
const dialCode = CountriesData.callingCode('AM')CountriesData exposes every country-level method — getCountries, find,
findByIso3, getTimezones, timezone, getCallingCodes, callingCode,
getCurrencies, currency. CountriesAtlas extends it and adds getStates,
getStatesAsync and state.
Cities on demand (/cities)
When you actually need cities (typically a client-side interaction), load them
through the dedicated /cities entry. Import it dynamically so the 171 MB
dataset stays out of any server bundle:
// e.g. inside onMounted / a click handler — browser only
const { getStatesForCountry } = await import('@innovayse/geo-atlas/cities')
const states = await getStatesForCountry('AM')
const cities = states.flatMap(s => s.cities ?? [])Get states/regions — sync (Node.js / CJS)
const states = CountriesAtlas.getStates('AM')
// [{ name: 'Yerevan', cities: [...] }, ...]Get states/regions — async (Browser / ESM)
getStatesAsync uses dynamic import() and works in all environments including browsers:
const states = await CountriesAtlas.getStatesAsync('AM')
// [{ name: 'Yerevan', cities: [...] }, ...]Get cities
const cities = states[0].cities
// [{ name: 'Yerevan', native: 'Երևան', translations: { ru: 'Ереван', hy: 'Երևան' }, ... }]City Translation Fields
Each city includes:
| Field | Description | Example |
|-------|-------------|---------|
| name | English name | "Yerevan" |
| native | Native script | "Երևան" |
| translations.ru | Russian | "Ереван" |
| translations.hy | Armenian | "Երևան" |
| translations.fr | French | "Erevan" |
| translations.de | German | "Eriwan" |
| translations.zh | Chinese | "埃里温" |
| translations.ar | Arabic | "يريفان" |
Supported translation keys: ru, hy, uk, ar, zh, es, fr, de, it, pt, pl, tr, ja, ko, nl
Country Fields
type Country = {
iso2: string // 'AM'
iso3: string // 'ARM'
name: string // 'Armenia'
native: string // 'Հայաստան'
emoji: string // '🇦🇲'
capital: string // 'Yerevan'
phone: number // 374
phone_format: string // '+374 9X XXX XXX'
latitude: string // '40.0'
longitude: string // '45.0'
translations: {
hy: string // 'Հայաստան'
ru: string // 'Армения'
// + 15 more languages
}
currency: string // 'AMD'
timezones: Timezone[]
}Phone format placeholder
phone_format contains the full international format with X for variable digits:
const am = CountriesAtlas.callingCode('AM')
// {
// name: 'Armenia',
// phone: 374,
// iso2: 'AM',
// phone_code: '+374',
// phone_format: '+374 9X XXX XXX',
// flag: 'flag flag-am'
// }
// Use as input placeholder:
// <input :placeholder="callingCode.phone_format" />| Country | phone_format |
|---------|---------------|
| Armenia (AM) | +374 9X XXX XXX |
| Russia (RU) | +7 9XX XXX XXXX |
| USA (US) | +1 XXX XXX XXXX |
| Germany (DE) | +49 XXXX XXXXXXX |
| France (FR) | +33 X XX XX XX XX |
| UK (GB) | +44 XXXX XXXXXX |
Nuxt 3 / Vite / SSR Setup
The per-country dataset (~171 MB) is only reachable through the city/state
methods. On an SSR build, importing the full CountriesAtlas drags that dataset
into the server bundle, where rollup can run out of memory (SIGKILL / OOM).
Avoid it by splitting your imports by need:
// composables/useCountries.ts
// Server-safe: country list only — never bundles the 171 MB dataset.
import CountriesData from '@innovayse/geo-atlas/lite'
const countries = CountriesData.getCountries()
const armenia = CountriesData.find('AM')
// Cities: load on demand, browser side, via a dynamic import so the dataset
// stays out of the server bundle entirely.
async function loadCities(iso2: string) {
const { getStatesForCountry } = await import('@innovayse/geo-atlas/cities')
const states = await getStatesForCountry(iso2)
return states.flatMap(s => s.cities ?? [])
}Keep server-rendered paths (useAsyncData, SSR templates) on /lite, and reach
for /cities only where the user actually opens a city selector. With this split
you no longer need any optimizeDeps.exclude / nitro.externals workaround for
the package.
Multilingual Country/City Names
type GeoLocale = 'en' | 'ru' | 'hy'
/** Get localized country name with fallback chain */
function getCountryName(country: Country, locale: GeoLocale): string {
if (locale === 'en') return country.name
return country.translations?.[locale] ?? country.native ?? country.name
}
/** Get localized city name with fallback chain */
function getCityName(city: City, locale: GeoLocale): string {
if (locale === 'en') return city.name
return city.translations?.[locale] ?? city.native ?? city.name
}Validation
import { ValidatorAtlas } from '@innovayse/geo-atlas'
ValidatorAtlas.isValidCountry('AM') // true
ValidatorAtlas.isValidCountry('XX') // false
ValidatorAtlas.isValidState('AM', 'Yerevan') // trueLicense
MIT © Innovayse
