Cities

← Back to docs

The cities array contains ~270 major world cities, including every national capital. Each city has coordinates (lat/lon), country code, and population where available.

Live capital finder

Import

import {
  cities,
  getCitiesByCountry,
  getCapitalCity,
  getCitiesByPopulation,
  searchCities,
} from "arevdata";
import type { City } from "arevdata";

Data shape

interface City {
  name: string;        // "Tokyo"
  country: string;     // ISO 3166-1 alpha-2, e.g. "JP"
  state?: string;      // State/region name (optional), e.g. "Tokyo"
  population?: number; // Approximate city population (optional)
  lat: number;         // Latitude  (−90 to 90)
  lon: number;         // Longitude (−180 to 180)
  capital?: boolean;   // true if this is the national capital
}

Examples

All cities

import { cities } from "arevdata";

console.log(cities.length); // ~270

// All national capitals
const capitals = cities.filter(c => c.capital);
console.log(capitals.length); // ~185

Capital city of a country

import { getCapitalCity } from "arevdata";

getCapitalCity("GB");
// { name: "London", country: "GB", lat: 51.5074, lon: -0.1278, capital: true, population: 9648110 }

getCapitalCity("JP");
// { name: "Tokyo", country: "JP", lat: 35.6762, lon: 139.6503, capital: true, population: 13960000 }

getCapitalCity("ZZ"); // undefined

Cities in a country

import { getCitiesByCountry } from "arevdata";

const usCities = getCitiesByCountry("US");
usCities.map(c => c.name);
// ["New York City", "Los Angeles", "Chicago", "Houston", "Phoenix",
//  "Philadelphia", "San Antonio", "San Diego", "Dallas", "Washington D.C.", ...]

Top cities by population

import { getCitiesByPopulation } from "arevdata";

// Top 10 most populous cities
const top10 = getCitiesByPopulation(10);
top10.map(c => `${c.name} (${c.country})`);
// ["Chongqing (CN)", "Tokyo (JP)", "Delhi (IN)", "Shanghai (CN)", ...]

// All cities sorted by population
const all = getCitiesByPopulation();

Search cities by name

import { searchCities } from "arevdata";

searchCities("new");
// [{ name: "New York City", ... }, { name: "New Delhi", ... }, ...]

searchCities("london");
// [{ name: "London", country: "GB", ... }]

// Case-insensitive
searchCities("BERLIN"); // same as searchCities("berlin")

Build a city autocomplete

import { searchCities, getCountryByCode } from "arevdata";

function cityAutocomplete(input: string) {
  return searchCities(input).map((city) => {
    const country = getCountryByCode(city.country);
    return {
      label: `${city.name}, ${country?.name ?? city.country}`,
      value: { lat: city.lat, lon: city.lon, code: city.country },
    };
  });
}

cityAutocomplete("par");
// [{ label: "Paris, France", value: { lat: 48.8566, lon: 2.3522, code: "FR" } }]

Calculate distance from capital to capital

import { getCapitalCity } from "arevdata";
import { haversineDistance } from "arevdata";

const amsterdam = getCapitalCity("NL")!;
const berlin = getCapitalCity("DE")!;

const km = haversineDistance(amsterdam.lat, amsterdam.lon, berlin.lat, berlin.lon);
// ~577 km

Coverage

Cities were chosen to cover:

All national capitals (~185 cities)
The largest metropolitan areas on each continent
Major cultural, economic, and tourist destinations

Cities from every continent are represented including remote capitals like Nuku’alofa (Tonga), Funafuti (Tuvalu), and Majuro (Marshall Islands).

Countries — country field uses alpha-2 codes from countries
Geography — haversineDistance() works with the lat/lon fields
States — state field aligns with entries in states