🏙️ @worldkit/cities

Fast, lightweight global cities dataset for JavaScript & TypeScript.

Lookup major world cities by country code, city name, and geographical coordinates (lat/lng).

📚 Full Documentation: https://worldkit.in/docs/cities

⚡ Features

• 🌆 Major Global Cities: Filter world cities by country ISO2 code or search by city name.
• 📍 Geographical Coordinates: Latitude and longitude values for mapping applications.
• 🚀 Zero Latency: Pure JavaScript ESM module with instant lookups.
• 📦 Lazy Loading Support: Built-in loadCities() async function for code-splitting bundle optimization.

📦 Install

npm install @worldkit/cities
# or
pnpm add @worldkit/cities
# or
yarn add @worldkit/cities

💡 Usage

import { cities, city, loadCities } from "@worldkit/cities";

// 1. Get cities for a specific country by ISO2 code
const usCities = cities("US");
console.log(usCities[0]);
/*
{
  id: 101,
  name: "New York",
  country: "US",
  state: "NY",
  lat: 40.7128,
  lng: -74.0060
}
*/

// 2. Lookup a city by name (case-insensitive)
const tokyo = city("Tokyo");
console.log(tokyo?.lat, tokyo?.lng); // 35.6762, 139.6503

// 3. Get all cities across all countries
const allCities = cities();

// 4. Async lazy loading for high-performance code splitting
const data = await loadCities();

📖 API Reference

cities(countryIso2?: string): City[]

Returns an array of major cities. If countryIso2 is provided (e.g. "US"), filters cities by country.

city(name: string): City | undefined

Look up city information by name (case-insensitive).

loadCities(): Promise<City[]>

Async helper function for dynamic imports and code splitting.

📐 TypeScript Support

Includes 100% strict TypeScript definitions:

import type { City } from "@worldkit/cities";

🔗 Related Packages

Explore the rest of the WorldKit ecosystem:

• @worldkit/core - Unified global data facade.
• @worldkit/countries - 250+ country dataset.
• @worldkit/states - 4,000+ states and provinces.
• @worldkit/search - Fast fuzzy search across cities.
• @worldkit/react - React <CitySelect /> component.

📜 License

MIT © WorldKit