City API

Exact name, typeahead, nearest, or nearby. Type, capital, district, elevation, id.

Look up a city by exact name. If several match, you get the largest by population. Optional ?country= and ?state= filters. Type, capital, district, elevation, and land area ride every record. Every response carries a stable id.

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,
  "type": "city",
  "capital_of": null,
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "elevation": 209,
  "elevation_ft": 686,
  "population": 943476,
  "area": 813.48,
  "land_area": 808.33,
  "water_area": 5.15,
  "timezone": "America/New_York",
  "id": "city_mb8mbqrkz8zb"
}

Response fields

name: City name
local_name: Local-language name (null when same as name)
type: What the place is in its own country's words (city, town, commune, ward)
capital_of: country when it is a national capital, state when it is a state or region capital, null otherwise
state: State or province code
state_name: State or province name
district: District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_name: District name
country: ISO2 country code
country_name: Country name
latitude: Latitude
longitude: Longitude
elevation: Elevation in meters at the city center
elevation_ft: Elevation in feet
population: Population
area: Total area in km² (land + water, or the official total)
land_area: Land area in km² (null when the source publishes total only)
water_area: Water area in km² (null when the source publishes total only)
timezone: Timezone identifier
distance: Kilometers from query point (coords and nearby)
distance_mi: Miles from query point (coords and nearby)
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,
      "type": "city",
      "capital_of": null,
      "state": "NC",
      "state_name": "North Carolina",
      "district": "37119",
      "district_name": "Mecklenburg",
      "country": "US",
      "country_name": "United States",
      "latitude": 35.209045,
      "longitude": -80.83099,
      "elevation": 209,
      "elevation_ft": 686,
      "population": 943476,
      "area": 813.48,
      "land_area": 808.33,
      "water_area": 5.15,
      "timezone": "America/New_York",
      "id": "city_mb8mbqrkz8zb"
    },
    {
      "name": "Charleston",
      "local_name": null,
      "type": "city",
      "capital_of": null,
      "state": "SC",
      "state_name": "South Carolina",
      "district": "45019",
      "district_name": "Charleston",
      "country": "US",
      "country_name": "United States",
      "latitude": 32.828017,
      "longitude": -79.972896,
      "elevation": 6,
      "elevation_ft": 20,
      "population": 157665,
      "area": 352.66,
      "land_area": 298.6,
      "water_area": 54.06,
      "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,
  "type": "city",
  "capital_of": null,
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "elevation": 209,
  "elevation_ft": 686,
  "population": 943476,
  "area": 813.48,
  "land_area": 808.33,
  "water_area": 5.15,
  "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)
type: What the place is in its own country's words (city, town, commune, ward)
capital_of: country when it is a national capital, state when it is a state or region capital, null otherwise
state: State or province code
state_name: State or province name
district: District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_name: District name
country: ISO2 country code
country_name: Country name
latitude: Latitude
longitude: Longitude
elevation: Elevation in meters at the city center
elevation_ft: Elevation in feet
population: Population
area: Total area in km² (land + water, or the official total)
land_area: Land area in km² (null when the source publishes total only)
water_area: Water area in km² (null when the source publishes total only)
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}

Nearby

Cities around a named place, nearest first, with miles and km. Default radius 40 km. ?unit=mi or legacy ?miles=. Radius is a query dial, never a path segment.

GET

api.parseapi.com/city/{name}/nearby

Cities around a named anchor. ?radius= ?unit=mi

curl "https://api.parseapi.com/city/denver/nearby?miles=8&limit=3" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "city": "Denver",
  "state": "CO",
  "country": "US",
  "radius": 8,
  "unit": "mi",
  "nearby": [
    {
      "name": "Glendale",
      "local_name": null,
      "type": "city",
      "capital_of": null,
      "state": "CO",
      "state_name": "Colorado",
      "district": "08005",
      "district_name": "Arapahoe",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.703052,
      "longitude": -104.936157,
      "elevation": 1631,
      "elevation_ft": 5351,
      "population": 4465,
      "area": 1.48,
      "land_area": 1.47,
      "water_area": 0.01,
      "timezone": "America/Denver",
      "distance": 8.06,
      "distance_mi": 5.01,
      "id": "city_5bjs2r33bamc"
    },
    // ... 2 more
  ]
}

Response fields

city: Anchor city name
state: Anchor state code
country: ISO2 country code
radius: Search radius used
unit: km or mi
nearby: Cities inside the radius, nearest first, each with distance and distance_mi

Questions? Email