Skip to main content
GET
Cities catalog for a country

Authorizations

Authorization
string
header
required

Session JWT (from register/login) or API key (pk_...). X-API-Key: <token> is accepted as an alternative header.

Query Parameters

country
string
required

ISO 3166-1 alpha-2 country code (e.g. US).

Pattern: ^[A-Z]{2}$

Response

Cities of the country grouped by subdivision (empty lists when the country has no coverage).

country
string

ISO 3166-1 alpha-2 country code echoed back.

states
object

Cities per ISO 3166-2 subdivision code (<CC>-<code>).

country_cities
string[]

Cities whose region could not be mapped to a subdivision.

meta
object

Coverage counts (state_count, city_count).

Last modified on August 22, 2026