City API

Exact name, typeahead, nearest, or nearby cities.

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=

Explore

Parameters 5

namestring · path · required: City name
countrystring · query · optional: ISO country code to disambiguate
statestring · query · optional: State code (bare or ISO-3166-2)
langstring · query · optional: Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.
deepboolean · query · optional: Population, area, elevation and capital status. Included on paid plans.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city("charlotte");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "timezone": "America/New_York",
  "id": "city_mb8mbqrkz8zb"
}

Response fields

name: City name
name_local: Local-language name, null when absent or identical to name
type: What the place is in its own country's words (city, town, commune, ward)
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
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)

Explore

Parameters 8

qstring · query · optional

City name prefix, at least two characters. Required for search; use lat and lon instead for the nearest city.

latnumber · query · optional

Latitude. Pass with lon for the nearest city, or use q for name search.

Range: -90 to 90

lonnumber · query · optional

Longitude. Required with lat; use q instead for name search.

Range: -180 to 180

countrystring · query · optional

Two-letter country code to narrow name-search results.

statestring · query · optional

State code or name to narrow name-search results.

limitinteger · query · optional

Maximum number of prefix-search results. Nearest-city lookup returns one city.

Default: 10

Range: 1 to 50

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Population, area, elevation and capital status. Included on paid plans.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.search("char", { country: "US", limit: 10 });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "q": "char",
  "country": "US",
  "cities": [
    {
      "name": "Charlotte",
      "name_local": null,
      "type": "city",
      "state": "NC",
      "state_name": "North Carolina",
      "district": "37119",
      "district_name": "Mecklenburg",
      "country": "US",
      "country_name": "United States",
      "latitude": 35.209045,
      "longitude": -80.83099,
      "timezone": "America/New_York",
      "id": "city_mb8mbqrkz8zb"
    },
    {
      "name": "Charleston",
      "name_local": null,
      "type": "city",
      "state": "SC",
      "state_name": "South Carolina",
      "district": "45019",
      "district_name": "Charleston",
      "country": "US",
      "country_name": "United States",
      "latitude": 32.828017,
      "longitude": -79.972896,
      "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

Explore

Parameters 8

qstring · query · optional

City name prefix, at least two characters. Required for search; use lat and lon instead for the nearest city.

latnumber · query · optional

Latitude. Pass with lon for the nearest city, or use q for name search.

Range: -90 to 90

lonnumber · query · optional

Longitude. Required with lat; use q instead for name search.

Range: -180 to 180

countrystring · query · optional

Two-letter country code to narrow name-search results.

statestring · query · optional

State code or name to narrow name-search results.

limitinteger · query · optional

Maximum number of prefix-search results. Nearest-city lookup returns one city.

Default: 10

Range: 1 to 50

langstring · query · optional

deepboolean · query · optional

Population, area, elevation and capital status. Included on paid plans.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.nearest(35.2271, -80.8431);
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "timezone": "America/New_York",
  "distance": 0.4,
  "distance_mi": 0.25,
  "id": "city_mb8mbqrkz8zb"
}

Response fields

name: City name
name_local: Local-language name, null when absent or identical to name
type: What the place is in its own country's words (city, town, commune, ward)
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
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

Explore

Parameters 8

namestring · path · required

Anchor city name

countrystring · query · optional

ISO country code to disambiguate the anchor

statestring · query · optional

State code to disambiguate the anchor

radiusnumber · query · optional

Search radius (default 40 km, max 800 km / 500 mi)

unitstring · query · optional

Radius unit, km (default) or mi

Values: km, mi

limitinteger · query · optional

Max results, default 10, max 50

langstring · query · optional

deepboolean · query · optional

Population, area, elevation and capital status. Included on paid plans.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.nearby("denver", { radius: 8, unit: "mi", limit: 3 });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "city": "Denver",
  "state": "CO",
  "country": "US",
  "radius": 8,
  "unit": "mi",
  "nearby": [
    {
      "name": "Glendale",
      "name_local": null,
      "type": "city",
      "state": "CO",
      "state_name": "Colorado",
      "district": "08005",
      "district_name": "Arapahoe",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.703052,
      "longitude": -104.936157,
      "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

Deep

?deep=true Population, area, elevation and capital status. Included on paid plans.

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city("charlotte", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "timezone": "America/New_York",
  "id": "city_mb8mbqrkz8zb",
  "deep": {
    "capital_of": null,
    "elevation": 209,
    "elevation_ft": 686,
    "population": 943476,
    "population_period": null,
    "area": 813.48,
    "land_area": 808.33,
    "water_area": 5.15
  }
}

Deep fields

deep.capital_of: country when it is a national capital, state when it is a state or region capital, null otherwise
deep.elevation: Elevation in meters at the city center
deep.elevation_ft: Elevation in feet
deep.population: Population
deep.population_period: Observation year or multi-year period for this population estimate (YYYY or YYYY-YYYY). Null when the record has no verified period or population. Never the import date.
deep.area: Total area in km² (land + water, or the official total)
deep.land_area: Land area in km² (null when the source publishes total only)
deep.water_area: Water area in km² (null when the source publishes total only)

Display language

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state, district or city names when available. A language choice does not imply worldwide translated city coverage.

Omitting lang preserves the original response. Codes, IDs, numeric facts and native-name fields stay unchanged. Missing translations keep their existing source value; unknown values stay null. A preserved name_local may equal the translated name.

Send a chosen browser preference explicitly, for example { lang: navigator.language } in your JavaScript SDK options. The API does not read Accept-Language automatically. Unsupported regions fall back to their supported base language; unsupported languages or scripts use English. Empty, invalid or repeated tags return 400.

Content-Language identifies languages used in translated display fields and known English fallbacks. This option follows the current API contract. Requests selecting frozen 1.0.0 retain that contract. Select API 2.0.0 to use display language.

41 display language choices

Language tag	Language
en	American English
zh-Hans	简体中文
fr	français (France)
de	Deutsch
it	italiano
ja	日本語
ko	한국어
es	español de España
ar	العربية
bg	български
ca	català
hr	hrvatski
cs	čeština
da	dansk
nl	Nederlands
fi	suomi
el	Ελληνικά
he	עברית
hi	हिन्दी
hu	magyar
id	Indonesia
kk	қазақ тілі
ms	Melayu
nb	norsk bokmål
pl	polski
pt	português (Brasil)
ro	română
ru	русский
sk	slovenčina
sv	svenska
th	ไทย
tr	Türkçe
uk	українська
vi	Tiếng Việt
zh-Hant	繁體中文
en-AU	Australian English
en-GB	British English
fr-CA	français canadien
es-419	español latinoamericano
pt-PT	português europeu
zh-Hant-HK	繁體中文（中國香港特別行政區）

Build with City

Add city autocomplete to an existing field

All tutorials →

Questions? Email

City API

By name#

Search#

Nearest#

Nearby#

Deep#

Display language#

Build with City

By name

Search

Nearest

Nearby

Deep

Display language