City API

Exact name, typeahead, or nearest to a point. Every response carries a stable id.

Look up a city by exact name. If several match, you get the largest by population. Optional ?country= and ?state= filters.

Coverage is curated per country from official national gazetteers: the US, Canada, Mexico, Brazil, Puerto Rico, the UK, Ireland, France, Spain, Belgium, the Netherlands, Germany, Austria, Switzerland, Liechtenstein, Italy, Portugal, Denmark, Sweden, Norway, Finland, Poland, Czechia, Japan, Taiwan, Australia, and New Zealand. A country outside the list returns an empty result.

By name

GET

api.parseapi.com/city/{name}

Exact city name. Optional ?country= and ?state=

curl "https://api.parseapi.com/city/charlotte" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "name": "Charlotte",
  "local_name": null,
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "latitude": 35.2271,
  "longitude": -80.8431,
  "population": 874579,
  "timezone": "America/New_York",
  "id": "city_mb8mbqrkz8zb"
}

Response fields

name: City name
local_name: Local-language name (null when same as name)
state: State or province code
state_name: State or province name
country: ISO2 country code
latitude: Latitude
longitude: Longitude
population: Population
timezone: Timezone identifier
distance: Kilometers from query point (coords only)
distance_mi: Miles from query point (coords only)
id: Stable city id (city_...). Fetch again at /city/id/{id}

Search

Prefix search for city pickers and typeahead. ?limit= caps results, default 10, max 50.

GET

api.parseapi.com/city?q={query}

Typeahead prefix search. ?limit= (default 10, max 50)

curl "https://api.parseapi.com/city?q=char&country=US&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "q": "char",
  "country": "US",
  "cities": [
    {
      "name": "Charlotte",
      "local_name": null,
      "state": "NC",
      "state_name": "North Carolina",
      "country": "US",
      "latitude": 35.2271,
      "longitude": -80.8431,
      "population": 874579,
      "timezone": "America/New_York",
      "id": "city_mb8mbqrkz8zb"
    },
    {
      "name": "Charleston",
      "local_name": null,
      "state": "SC",
      "state_name": "South Carolina",
      "country": "US",
      "latitude": 32.7765,
      "longitude": -79.9311,
      "population": 150227,
      "timezone": "America/New_York",
      "id": "city_ngm2jafnwk7y"
    },
    // ... 8 more
  ]
}

Response fields

q: Search query
country: ISO2 country filter (when passed)
cities: Matching city records (same shape as lookup)

Nearest

Closest city to a lat/lon, with miles and km. Good for enriching a point with a place name.

GET

api.parseapi.com/city?lat={lat}&lon={lon}

Nearest city by coordinates

curl "https://api.parseapi.com/city?lat=35.2271&lon=-80.8431" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "name": "Charlotte",
  "local_name": null,
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "latitude": 35.2271,
  "longitude": -80.8431,
  "population": 874579,
  "timezone": "America/New_York",
  "distance": 0.4,
  "distance_mi": 0.25,
  "id": "city_mb8mbqrkz8zb"
}

Response fields

name: City name
local_name: Local-language name (null when same as name)
state: State or province code
state_name: State or province name
country: ISO2 country code
latitude: Latitude
longitude: Longitude
population: Population
timezone: Timezone identifier
distance: Kilometers from query point
distance_mi: Miles from query point
id: Stable city id (city_...). Fetch again at /city/id/{id}

Questions? Email