Search by task, endpoint, field, or error.

← Docs

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. Core includes type, district, coordinates and timezone where known, with a stable city ID. Paid ?deep=true adds capital status, elevation, population and area where available.

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 such as FL or US-FL. Get codes from /country/{country}/states. State names return 400. A country prefix must match the country filter.

Length: 1 to 6 characters

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,3}$

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.

Length: 2 to 64 characters

deepboolean · query · optional

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

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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

namestring or null
City name
name_localstring or null
Local-language name, null when absent or identical to name
typestring or null
What the place is in its own country's words (city, town, commune, ward)
statestring or null
State or province code
state_namestring or null
State or province name
districtstring or null
District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_namestring or null
District name
countrystring or null
ISO2 country code
country_namestring or null
Country name
latitudenumber or null
Latitude
longitudenumber or null
Longitude
timezonestring or null
Timezone identifier
distancenumber
Kilometers from query point (coords and nearby)
distance_minumber
Miles from query point (coords and nearby)
idstring or null
Stable city id (city_...). Fetch again at /city/id/{id}

By stable ID

GET
api.parseapi.com/city/id/{id}
Retrieve the same city using its returned ID
Explore
Parameters 3
idstring · path · required

Stable city id from any city response

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.

Length: 2 to 64 characters

deepboolean · query · optional

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

Store the id returned by a lookup, search, nearest or nearby result. Use it here to retrieve that city without repeating a name search. The response uses the same city fields as By name above, including optional paid Deep.

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.

Length: 2 to no maximum characters

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.

Pattern: ^[a-zA-Z]{2}$

statestring · query · optional

State code such as FL or US-FL. Get codes from /country/{country}/states. State names return 400. A country prefix must match the country filter.

Length: 1 to 6 characters

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,3}$

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.

Length: 2 to 64 characters

deepboolean · query · optional

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

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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 (excerpt)

This example shows selected fields or shortened lists. Run the request for the full 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"
    }
  ]
}

Response fields

qstring
Search query
countrystring or null
ISO2 country filter (when passed)
citiesarray
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.

Length: 2 to no maximum characters

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.

Pattern: ^[a-zA-Z]{2}$

statestring · query · optional

State code such as FL or US-FL. Get codes from /country/{country}/states. State names return 400. A country prefix must match the country filter.

Length: 1 to 6 characters

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,3}$

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.

Length: 2 to 64 characters

deepboolean · query · optional

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

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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

namestring or null
City name
name_localstring or null
Local-language name, null when absent or identical to name
typestring or null
What the place is in its own country's words (city, town, commune, ward)
statestring or null
State or province code
state_namestring or null
State or province name
districtstring or null
District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_namestring or null
District name
countrystring or null
ISO2 country code
country_namestring or null
Country name
latitudenumber or null
Latitude
longitudenumber or null
Longitude
timezonestring or null
Timezone identifier
distancenumber
Kilometers from query point
distance_minumber
Miles from query point
idstring or null
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 such as FL or US-FL. Get codes from /country/{country}/states. State names return 400. A country prefix must match the country filter.

Length: 1 to 6 characters

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,3}$

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

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.

Length: 2 to 64 characters

deepboolean · query · optional

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

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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 (excerpt)

This example shows selected fields or shortened lists. Run the request for the full 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"
    }
  ]
}

Response fields

citystring or null
Anchor city name
statestring or null
Anchor state code
countrystring or null
ISO2 country code
radiusnumber
Search radius used
unitstring
km or mi
nearbyarray
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.

Run this Deep example with a paid-plan key. Deep is included in the pooled request, with no separate lookup charge.

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

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

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

Example response
{
  "name": "Denver",
  "name_local": null,
  "type": "city",
  "state": "CO",
  "state_name": "Colorado",
  "district": "08031",
  "district_name": "Denver",
  "country": "US",
  "country_name": "United States",
  "latitude": 39.76185,
  "longitude": -104.881105,
  "timezone": "America/Denver",
  "id": "city_ccvrzq54e65m",
  "deep": {
    "capital_of": "state",
    "elevation": 1612,
    "elevation_ft": 5289,
    "population": 729019,
    "population_period": null,
    "area": 400.74,
    "land_area": 396.46,
    "water_area": 4.28
  }
}

Deep fields

deep.capital_ofstring or null
country when it is a national capital, state when it is a state or region capital, null otherwise
deep.elevationinteger or null
Elevation in meters at the city center
deep.elevation_ftinteger or null
Elevation in feet
deep.populationinteger or null
Population
deep.population_periodstring or null
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.areanumber or null
Total area in km² (land + water, or the official total)
deep.land_areanumber or null
Land area in km² (null when the source publishes total only)
deep.water_areanumber or null
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 tagLanguage
enAmerican English
zh-Hans简体中文
frfrançais (France)
deDeutsch
ititaliano
ja日本語
ko한국어
esespañol de España
arالعربية
bgбългарски
cacatalà
hrhrvatski
csčeština
dadansk
nlNederlands
fisuomi
elΕλληνικά
heעברית
hiहिन्दी
humagyar
idIndonesia
kkқазақ тілі
msMelayu
nbnorsk bokmål
plpolski
ptportuguês (Brasil)
roromână
ruрусский
skslovenčina
svsvenska
thไทย
trTürkçe
ukукраїнська
viTiếng Việt
zh-Hant繁體中文
en-AUAustralian English
en-GBBritish English
fr-CAfrançais canadien
es-419español latinoamericano
pt-PTportuguês europeu
zh-Hant-HK繁體中文（中國香港特別行政區）

Build with City

All tutorials →

Questions? Email