Versioned location data for 250 countries and territories, 4,963 administrative areas, 147,739 places, and 922 Türkiye districts.

Overview

Country State City is a versioned world location database, available as an npm package, a hosted REST and GraphQL API, and an MCP server. It provides:

250 countries and territories with ISO-based codes and one documented user-assigned Kosovo code
4,963 imported subdivision records with explicit administrative classification
147,739 populated-place records with centre coordinates
922 explicitly modelled Türkiye districts

Country codes are ISO 3166-1 based. The XK/Kosovo record uses a documented user-assigned code from ISO's reserved user-assigned range; inspect codeStatus and codeAuthority instead of assuming every row is officially assigned. Data is available in JSON, CSV, XML, and YAML formats.

Choose an integration

If you need	Use	Start here
Typed, offline data inside a Node.js or browser application	npm package	Installation
HTTP access from any language or service	Hosted REST API	REST reference
Selectable fields and nested read queries	Hosted GraphQL API	GraphQL
Location tools inside an MCP-compatible AI client	MCP server	MCP server

The npm package and MCP server run locally. The hosted API requires an API key for data and GraphQL routes.

Quick Start

Install the package

npm install @tansuasici/country-state-city

Import and use

import { CountryStateCity } from '@tansuasici/country-state-city';

// Get all countries
const countries = CountryStateCity.getAllCountries();

// Get states by country
const states = CountryStateCity.getStatesByCountryId(225); // Türkiye

// Get cities by state
const cities = CountryStateCity.getCitiesByStateId(2170); // Istanbul

Choose your format

// JSON (default)
const json = CountryStateCity.getAllCountries();

// CSV
const csv = CountryStateCity.getAllCountries('csv');

// XML
const xml = CountryStateCity.getAllCountries('xml');

// YAML
const yaml = CountryStateCity.getAllCountries('yaml');

Platform Support

The Node.js build reads data from the filesystem using fs and path. It supports both CommonJS and ESM:

// CommonJS
const { CountryStateCity } = require('@tansuasici/country-state-city');

// ESM
import { CountryStateCity } from '@tansuasici/country-state-city';

Key Features

Feature	Description
Multiple Formats	JSON, CSV, XML, YAML output
ISO Standards	ISO 3166-1 assigned codes plus an explicit user-assigned XK exception
Full TypeScript	Complete type definitions included
Bundler-ready	Browser data remains in separately cacheable package assets
MCP Integration	Works with Claude Desktop and AI assistants
Dual Build	Separate Node.js and Browser entry points

Introduction