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. Pass ambiguity=errorto require a unique exact match. A name with several eligible matches returns HTTP 409 with bounded City choices.

Coverage is curated per country from retained source references. See the City coverage list for covered countries and territories. Place layers, available fields and observation dates vary by source. A name lookup with no match returns 404; search and Browse return an empty list.

By name

GET

api.parseapi.com/city/{name}

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

Explore

Parameters 13

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

aliasesboolean · query · optional

Also match reviewed official name forms. Applies to name lookup and search, without spelling correction.

Value: true

ambiguitystring · query · optional

Require a unique eligible exact name match; otherwise return HTTP 409 ambiguous_city with up to two safe City candidates.

Values: error

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: resource, geojson

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, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Include reviewed official romanized name_romanized and romanization_language. Missing or conflicting forms remain null; no ASCII-folding substitute. Available reviewed forms currently cover 20 Japanese whole-city aliases.

Value: true

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",
  "district": "37119",
  "district_name": "Mecklenburg",
  "state": "NC",
  "state_name": "North Carolina",
  "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,
    "area": 813.48,
    "land_area": 808.33,
    "water_area": 5.15
  }
}

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)
districtstring or null: District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_namestring or null: District name
statestring or null: State or province code
state_namestring or null: State or province 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)
grainstring or null: Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
parentobject or null: Reviewed immediate parent with its City id, name, name_local, country, state, type and grain; returned with hierarchy=true, null when unreviewed
idstring or null: Stable city id (city_...). Fetch again at /city/id/{id}

Choose a city

Use ambiguity=error on exact name lookup or named nearby when choosing the wrong place would matter. HTTP 409 ambiguous_city includes up to two safe candidates with City identity, country and state fields. It does not include paid Deep. Let the user choose an ID, or narrow the country, state, type or grain and try again.

State filters take codes such as ZH or CH-ZH; find codes with /country/CH/states. State names return 400. A country prefix must agree with the country filter.

Choose a place layer

A whole municipality and one of its wards are separate places with separate IDs. type filters the recorded type, such as city or ward. grain filters a reviewed geographic layer: municipality, subdivision, locality or metropolitan_area.

For example, /city/Sakai?country=JP&state=27&grain=municipality&ambiguity=error asks for the whole municipality. hierarchy=true adds its reviewed grain and immediate parent, using the same City IDs. The parent is null when no relationship has been reviewed; null does not prove that the place is independent.

Reviewed relationships currently cover selected municipalities, subdivisions and localities in Austria, Japan and Taiwan. A name lookup tries exact reviewed names first, then primary, native and ASCII names. Use country and state to narrow a shared name; distinct reviewed matches return 409. Reviewed names also work in autocomplete and spelling search. aliases=true remains supported. Names are not guessed. These options apply to current API 2.0.0.

Native and translated names

Use lang=de for Vienna’s reviewed native name, Wien; lang=ja for 1,912 covered Japanese names; or lang=zh-Hant for 377 covered Traditional Chinese names in Taiwan. Approved translations take precedence. Other records and unsupported locales keep their source names. The stable ID and name_local stay unchanged.

By stable ID

GET

api.parseapi.com/city/id/{id}

Retrieve the same city using its returned ID

Explore

Parameters 7

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: resource, geojson

idstring · path · required

Stable city id from any city response

langstring · query · optional

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

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. Exact primary, ASCII and native-name matches rank before prefixes. Country, state, type and grain can narrow the candidates; hierarchy=true adds the reviewed parent to each result. Existing /city?q=... calls use prefix matching.

GET

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

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

Explore

Parameters 26

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

aliasesboolean · query · optional

Also match reviewed official name forms. Applies to name lookup and search, without spelling correction.

Value: true

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: list, geojson

countriesstring · query · optional

Comma-separated ISO2 country set; at most 50 distinct codes. Collection results must belong to this set.

Length: 2 to 149 characters

exclude_countriesstring · query · optional

Comma-separated ISO2 countries excluded from collection results.

Length: 2 to 149 characters

timezonesstring · query · optional

Comma-separated exact IANA timezone set.

Length: 1 to 5049 characters

min_elevationnumber · query · optional

Inclusive minimum known elevation, in meters. Unknown values do not match.

max_elevationnumber · query · optional

Inclusive maximum known elevation, in meters; must be at least the minimum.

min_populationinteger · query · optional

Inclusive minimum known population at the returned place layer. Unknown counts do not match.

Range: 0 to 9007199254740991

max_populationinteger · query · optional

Inclusive maximum known population. Must be at least min_population when both are supplied.

Range: 0 to 9007199254740991

timezonestring · query · optional

Exact timezone identifier, such as Europe/Vienna. Applies to collection results.

Length: 1 to 100 characters

bboxstring · query · optional

Place-center bounds west,south,east,north in degrees. West greater than east crosses the dateline. This does not test municipal boundary intersection.

pageboolean · query · optional

Include next_cursor on prefix search or named nearby. Browse and coordinate nearby always include it.

Value: true

cursorstring · query · optional

Opaque next_cursor from the previous response. Keep the original query options, including limit, unchanged. Invalid or changed cursors return 400; restart without a cursor. Verified revision-reader pages bind to their immutable edition; restart after an edition change. Legacy-reader pages follow the current catalog.

Length: 1 to 700 characters

orderstring · query · optional

Sort direction. Name and distance default to asc; population defaults to desc, with unknown counts last. Relevance supports asc only.

Values: asc, desc

sortstring · query · optional

Up to three keys: name, population, country, elevation; relevance for search and distance for nearby. Prefix a key with - for descending or + for ascending. Signed multi-key sorts cannot also use order. Unknown values sort last.

Length: 0 to 100 characters

qstring · query · required

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

countrystring · query · optional

Two-letter country code to narrow name search or coordinate matches.

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 results per collection page. Nearest-city lookup returns one city.

Default: 10

Range: 1 to 50

langstring · query · optional

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

For explicit spelling controls, use /city/search. match=exact selects full names, match=prefix selects prefixes, and match=fuzzy suggests spellings within max_distance=1 or 2. This route returns a canonical list with match evidence. Review a suggestion before saving its ID. Numeric, map, timezone and sort filters belong to ordinary prefix search and Browse; unsupported spelling-search controls return 400.

GET

api.parseapi.com/city/search

Explicit spelling suggestions; canonical list

Explore

Parameters 19

qstring · query · required

City name query, at least two characters.

Length: 2 to 500 characters

countrystring · query · optional

ISO2 country scope.

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 results, 1–50.

Range: 1 to 50

deepboolean · query · optional

Optional paid detail on each City.

Value: true

matchstring · query · optional

Search name matching. Fuzzy is explicit and returns suggestion evidence; no implicit spelling correction in exact lookup.

Default: prefix

Values: exact, prefix, fuzzy

max_distanceinteger · query · optional

Maximum edit distance for explicit fuzzy matching.

Values: 1, 2

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

aliasesboolean · query · optional

Also match reviewed official name forms. Applies to name lookup and search, without spelling correction.

Value: true

formatstring · query · optional

Canonical list by default, or a GeoJSON collection of stored place centers.

Values: list, geojson

countriesstring · query · optional

Comma-separated ISO2 country set; at most 50 distinct codes. Collection results must belong to this set.

Length: 2 to 149 characters

exclude_countriesstring · query · optional

Comma-separated ISO2 countries excluded from collection results.

Length: 2 to 149 characters

cursorstring · query · optional

Length: 1 to 700 characters

prettyboolean · query · optional

Indent the JSON response for readability.

Value: true

langstring · query · optional

Length: 2 to 64 characters

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.search("char", { country: "US", limit: 10, deep: true });
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",
      "district": "37119",
      "district_name": "Mecklenburg",
      "state": "NC",
      "state_name": "North Carolina",
      "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,
        "area": 813.48,
        "land_area": 808.33,
        "water_area": 5.15
      }
    },
    {
      "name": "Charleston",
      "name_local": null,
      "type": "city",
      "district": "45019",
      "district_name": "Charleston",
      "state": "SC",
      "state_name": "South Carolina",
      "country": "US",
      "country_name": "United States",
      "latitude": 32.828017,
      "longitude": -79.972896,
      "timezone": "America/New_York",
      "id": "city_ngm2jafnwk7y",
      "deep": {
        "capital_of": null,
        "elevation": 6,
        "elevation_ft": 20,
        "population": 157665,
        "area": 352.66,
        "land_area": 298.6,
        "water_area": 54.06
      }
    },
    {
      "name": "Charleston",
      "name_local": null,
      "type": "city",
      "district": "54039",
      "district_name": "Kanawha",
      "state": "WV",
      "state_name": "West Virginia",
      "country": "US",
      "country_name": "United States",
      "latitude": 38.348692,
      "longitude": -81.632324,
      "timezone": "America/New_York",
      "id": "city_ecyfxktgzfke",
      "deep": {
        "capital_of": "state",
        "elevation": 184,
        "elevation_ft": 604,
        "population": 46482,
        "area": 84.27,
        "land_area": 81.32,
        "water_area": 2.95
      }
    },
    {
      "name": "Charlottesville",
      "name_local": null,
      "type": "city",
      "district": "51540",
      "district_name": "Charlottesville",
      "state": "VA",
      "state_name": "Virginia",
      "country": "US",
      "country_name": "United States",
      "latitude": 38.037658,
      "longitude": -78.485381,
      "timezone": "America/New_York",
      "id": "city_xdtvmzjrjpz2",
      "deep": {
        "capital_of": null,
        "elevation": 141,
        "elevation_ft": 463,
        "population": 44767,
        "area": 26.59,
        "land_area": 26.54,
        "water_area": 0.05
      }
    },
    {
      "name": "Charleston",
      "name_local": null,
      "type": "township",
      "district": null,
      "district_name": null,
      "state": "IL",
      "state_name": "Illinois",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.48103,
      "longitude": -88.187297,
      "timezone": "America/Chicago",
      "id": "city_7ztmgpcf5sf9",
      "deep": {
        "capital_of": null,
        "elevation": null,
        "elevation_ft": null,
        "population": 19485,
        "area": 98.09,
        "land_area": 96.25,
        "water_area": 1.84
      }
    },
    {
      "name": "Charleston",
      "name_local": null,
      "type": "city",
      "district": "17029",
      "district_name": "Coles",
      "state": "IL",
      "state_name": "Illinois",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.48483,
      "longitude": -88.177609,
      "timezone": "America/Chicago",
      "id": "city_jn9z8wjbqumr",
      "deep": {
        "capital_of": null,
        "elevation": 215,
        "elevation_ft": 705,
        "population": 17361,
        "area": 25.36,
        "land_area": 23.51,
        "water_area": 1.85
      }
    },
    {
      "name": "Charlestown",
      "name_local": null,
      "type": "township",
      "district": null,
      "district_name": null,
      "state": "IN",
      "state_name": "Indiana",
      "country": "US",
      "country_name": "United States",
      "latitude": 38.463706,
      "longitude": -85.651947,
      "timezone": "America/Kentucky/Louisville",
      "id": "city_d4sj7qgmrq5s",
      "deep": {
        "capital_of": null,
        "elevation": null,
        "elevation_ft": null,
        "population": 16748,
        "area": 168.66,
        "land_area": 167.17,
        "water_area": 1.49
      }
    },
    {
      "name": "Charlton",
      "name_local": null,
      "type": "town",
      "district": null,
      "district_name": null,
      "state": "MA",
      "state_name": "Massachusetts",
      "country": "US",
      "country_name": "United States",
      "latitude": 42.133935,
      "longitude": -71.968025,
      "timezone": "America/New_York",
      "id": "city_3jf5abc998s3",
      "deep": {
        "capital_of": null,
        "elevation": null,
        "elevation_ft": null,
        "population": 13685,
        "area": 113.43,
        "land_area": 109.25,
        "water_area": 4.18
      }
    },
    {
      "name": "Charter Oak",
      "name_local": null,
      "type": "census designated place",
      "district": "06037",
      "district_name": "Los Angeles",
      "state": "CA",
      "state_name": "California",
      "country": "US",
      "country_name": "United States",
      "latitude": 34.102492,
      "longitude": -117.856282,
      "timezone": "America/Los_Angeles",
      "id": "city_b3fdv7qdgds7",
      "deep": {
        "capital_of": null,
        "elevation": 219,
        "elevation_ft": 719,
        "population": 9739,
        "area": 2.4,
        "land_area": 2.4,
        "water_area": 0
      }
    },
    {
      "name": "Chartiers",
      "name_local": null,
      "type": "township",
      "district": null,
      "district_name": null,
      "state": "PA",
      "state_name": "Pennsylvania",
      "country": "US",
      "country_name": "United States",
      "latitude": 40.250445,
      "longitude": -80.249466,
      "timezone": "America/New_York",
      "id": "city_cmfcsfm8ku9r",
      "deep": {
        "capital_of": null,
        "elevation": null,
        "elevation_ft": null,
        "population": 9302,
        "area": 63.75,
        "land_area": 63.75,
        "water_area": 0
      }
    }
  ]
}

Response fields

qstring: Search query
countrystring or null: ISO2 country filter (when passed)
statestring or null: State filter (when passed)
typestring or null: Recorded place type filter (when passed)
grainstring or null: Reviewed geographic layer filter (when passed)
aliasesboolean: Whether reviewed alias matching was requested (when passed)
citiesarray: Matching city records (same shape as lookup)
next_cursorstring or null: Opaque cursor for the next page, null at the end; included with page=true or cursor

Browse and filter

Use browse=true to list covered places without a name prefix. Add a country to build a country picker, or combine type and grain to select a place layer. Each page contains up to 50 cities.

min_population and max_population set inclusive population bounds. Unknown counts do not match a population range. The count used for filtering and ordering is the same count returned by paid Deep for that place layer. timezone matches one exact timezone identifier; timezones accepts a comma-separated set. countries=JP,AT includes several countries and exclude_countries=US removes countries. min_elevation and max_elevation are inclusive meter bounds; unknown elevations do not match.

bbox=west,south,east,north limits place centers to a map area. West greater than east crosses the dateline, for example 170,-50,-170,-30. This checks the stored center, rather than municipal boundaries.

GET

api.parseapi.com/city?browse=true&country=JP&min_population=100000&sort=population&limit=50

Browse covered places, largest first

Explore

Parameters 25

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: list, geojson

countriesstring · query · optional

Comma-separated ISO2 country set; at most 50 distinct codes. Collection results must belong to this set.

Length: 2 to 149 characters

exclude_countriesstring · query · optional

Comma-separated ISO2 countries excluded from collection results.

Length: 2 to 149 characters

timezonesstring · query · optional

Comma-separated exact IANA timezone set.

Length: 1 to 5049 characters

min_elevationnumber · query · optional

Inclusive minimum known elevation, in meters. Unknown values do not match.

max_elevationnumber · query · optional

Inclusive maximum known elevation, in meters; must be at least the minimum.

min_populationinteger · query · optional

Inclusive minimum known population at the returned place layer. Unknown counts do not match.

Range: 0 to 9007199254740991

max_populationinteger · query · optional

Inclusive maximum known population. Must be at least min_population when both are supplied.

Range: 0 to 9007199254740991

timezonestring · query · optional

Exact timezone identifier, such as Europe/Vienna. Applies to collection results.

Length: 1 to 100 characters

bboxstring · query · optional

Place-center bounds west,south,east,north in degrees. West greater than east crosses the dateline. This does not test municipal boundary intersection.

pageboolean · query · optional

Include next_cursor on prefix search or named nearby. Browse and coordinate nearby always include it.

Value: true

cursorstring · query · optional

Length: 1 to 700 characters

orderstring · query · optional

Sort direction. Name and distance default to asc; population defaults to desc, with unknown counts last. Relevance supports asc only.

Values: asc, desc

browseboolean · query · required

List covered cities without a name prefix, optionally narrowed by country or other collection filters.

Value: true

sortstring · query · optional

Length: 0 to 100 characters

countrystring · query · optional

Two-letter country code to narrow name search or coordinate matches.

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 results per collection page. Nearest-city lookup returns one city.

Default: 10

Range: 1 to 50

langstring · query · optional

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

Response fields

countrystring or null: ISO2 country filter (when passed)
statestring or null: State filter (when passed)
typestring or null: Recorded place type filter (when passed)
grainstring or null: Reviewed geographic layer filter (when passed)
citiesarray: City records on this page (same shape as lookup)
next_cursorstring or null: Opaque cursor for the next page, null at the end

Stable ids

Save the selected id and fetch it through /city/id/{id}. Names and facts can change while that identity stays the same. Missing cities return 404.

Sorting and pages

Browse supports name, country, population and elevation sorting. Search adds relevance, its default; nearby adds distance, its default. Combine up to three keys, for example sort=country,-population,name. A minus sign selects descending order and a plus sign selects ascending order. With a single unsigned key, order=asc or order=desc still works. Population defaults to descending order; other keys default to ascending order, and unknown values sort last. Relevance supports ascending order only. Name sorting uses the stored primary name; display language changes labels without reordering results.

Browse and coordinate nearby always include next_cursor. Add page=true to search or named nearby to include it. A null cursor means the end of the list. Copy the cursor into the next request and keep the other options, including limit, unchanged.

Cursors are opaque. A changed query or invalid cursor returns 400; restart without the cursor. With the verified immutable reader active, pages bind to the served edition and an edition change requires a new first page. Legacy-reader pages follow the current catalog. These controls apply to collections on API 2.0.0.

Nearest

Nearest recorded place center within 2,000 km, with miles and km. Country, state, type and grain narrow the eligible places. A nearby center does not establish that the coordinate lies inside the municipality; use Point for administrative boundaries.

GET

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

Nearest city by coordinates

Explore

Parameters 13

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

aliasesboolean · query · optional

Also match reviewed official name forms. Applies to name lookup and search, without spelling correction.

Value: true

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: resource, geojson

latnumber · query · required

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

Range: -90 to 90

lonnumber · query · required

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 or coordinate matches.

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}$

langstring · query · optional

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.nearest(35.2271, -80.8431, { 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",
  "district": "37119",
  "district_name": "Mecklenburg",
  "state": "NC",
  "state_name": "North Carolina",
  "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",
  "deep": {
    "capital_of": null,
    "elevation": 209,
    "elevation_ft": 686,
    "population": 943476,
    "area": 813.48,
    "land_area": 808.33,
    "water_area": 5.15
  }
}

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)
districtstring or null: District code the city sits in (US FIPS, FR INSEE, GB GSS)
district_namestring or null: District name
statestring or null: State or province code
state_namestring or null: State or province 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
grainstring or null: Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
parentobject or null: Reviewed immediate parent, returned with hierarchy=true; null when unreviewed
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, or 25 mi with unit=mi. ?unit=mi or legacy ?miles=. Radius is a query dial, never a path segment. Country and state select the anchor; type and grain select both the anchor and its nearby results.

GET

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

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

Explore

Parameters 29

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

aliasesboolean · query · optional

Also match reviewed official name forms. Applies to name lookup and search, without spelling correction.

Value: true

ambiguitystring · query · optional

Require a unique eligible exact name match; otherwise return HTTP 409 ambiguous_city with up to two safe City candidates.

Values: error

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: list, geojson

countriesstring · query · optional

Comma-separated ISO2 country set; at most 50 distinct codes. Collection results must belong to this set.

Length: 2 to 149 characters

exclude_countriesstring · query · optional

Comma-separated ISO2 countries excluded from collection results.

Length: 2 to 149 characters

timezonesstring · query · optional

Comma-separated exact IANA timezone set.

Length: 1 to 5049 characters

min_elevationnumber · query · optional

Inclusive minimum known elevation, in meters. Unknown values do not match.

max_elevationnumber · query · optional

Inclusive maximum known elevation, in meters; must be at least the minimum.

min_populationinteger · query · optional

Inclusive minimum known population at the returned place layer. Unknown counts do not match.

Range: 0 to 9007199254740991

max_populationinteger · query · optional

Inclusive maximum known population. Must be at least min_population when both are supplied.

Range: 0 to 9007199254740991

timezonestring · query · optional

Exact timezone identifier, such as Europe/Vienna. Applies to collection results.

Length: 1 to 100 characters

bboxstring · query · optional

Place-center bounds west,south,east,north in degrees. West greater than east crosses the dateline. This does not test municipal boundary intersection.

pageboolean · query · optional

Include next_cursor on prefix search or named nearby. Browse and coordinate nearby always include it.

Value: true

cursorstring · query · optional

Length: 1 to 700 characters

orderstring · query · optional

Sort direction. Name and distance default to asc; population defaults to desc, with unknown counts last. Relevance supports asc only.

Values: asc, desc

sortstring · query · optional

Length: 0 to 100 characters

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

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

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, deep: true });
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",
      "district": "08005",
      "district_name": "Arapahoe",
      "state": "CO",
      "state_name": "Colorado",
      "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",
      "deep": {
        "capital_of": null,
        "elevation": 1631,
        "elevation_ft": 5351,
        "population": 4465,
        "area": 1.48,
        "land_area": 1.47,
        "water_area": 0.01
      }
    },
    {
      "name": "Four Square Mile",
      "name_local": null,
      "type": "census designated place",
      "district": "08005",
      "district_name": "Arapahoe",
      "state": "CO",
      "state_name": "Colorado",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.680723,
      "longitude": -104.887924,
      "timezone": "America/Denver",
      "distance": 9.04,
      "distance_mi": 5.62,
      "id": "city_3y2ehrvkj73q",
      "deep": {
        "capital_of": null,
        "elevation": 1662,
        "elevation_ft": 5453,
        "population": 22872,
        "area": 7,
        "land_area": 7,
        "water_area": 0
      }
    },
    {
      "name": "Derby",
      "name_local": null,
      "type": "census designated place",
      "district": "08001",
      "district_name": "Adams",
      "state": "CO",
      "state_name": "Colorado",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.840791,
      "longitude": -104.916254,
      "timezone": "America/Denver",
      "distance": 9.28,
      "distance_mi": 5.76,
      "id": "city_sj3r8bzde3tk",
      "deep": {
        "capital_of": null,
        "elevation": 1563,
        "elevation_ft": 5128,
        "population": 8407,
        "area": 4.57,
        "land_area": 4.53,
        "water_area": 0.04
      }
    }
  ]
}

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 in the requested order, nearest first by default, each with distance and distance_mi
next_cursorstring or null: Opaque cursor for the next page, null at the end; included with page=true or cursor

Population, timezone and map-area filters apply to the nearby results. They do not disqualify the named anchor. Add page=true to continue through results beyond the first page.

Nearby coordinates

Pass a coordinate origin with nearby=true for a radius collection. Country, state, type, grain and the collection filters narrow the results. The default radius is 40 km, or 25 mi with unit=mi; the maximum is 800 km or 500 mi. The response includes the origin, radius, units, distances and a cursor. Omitting nearby=true keeps the single nearest-city lookup above.

GET

api.parseapi.com/city?lat=48.2082&lon=16.3738&nearby=true&radius=40&unit=km&limit=50

Cities around a coordinate origin

Explore

Parameters 29

typestring · query · optional

Filter the recorded place type, such as city or ward.

Length: 1 to 60 characters

grainstring · query · optional

Filter a reviewed geographic layer. Unreviewed records do not match.

Values: municipality, subdivision, locality, metropolitan_area

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

formatstring · query · optional

resource for one City, list for a collection, or geojson for stored-center Features. Omit to retain the classic envelope.

Values: list, geojson

countriesstring · query · optional

Comma-separated ISO2 country set; at most 50 distinct codes. Collection results must belong to this set.

Length: 2 to 149 characters

exclude_countriesstring · query · optional

Comma-separated ISO2 countries excluded from collection results.

Length: 2 to 149 characters

timezonesstring · query · optional

Comma-separated exact IANA timezone set.

Length: 1 to 5049 characters

min_elevationnumber · query · optional

Inclusive minimum known elevation, in meters. Unknown values do not match.

max_elevationnumber · query · optional

Inclusive maximum known elevation, in meters; must be at least the minimum.

min_populationinteger · query · optional

Inclusive minimum known population at the returned place layer. Unknown counts do not match.

Range: 0 to 9007199254740991

max_populationinteger · query · optional

Inclusive maximum known population. Must be at least min_population when both are supplied.

Range: 0 to 9007199254740991

timezonestring · query · optional

Exact timezone identifier, such as Europe/Vienna. Applies to collection results.

Length: 1 to 100 characters

bboxstring · query · optional

Place-center bounds west,south,east,north in degrees. West greater than east crosses the dateline. This does not test municipal boundary intersection.

pageboolean · query · optional

Include next_cursor on prefix search or named nearby. Browse and coordinate nearby always include it.

Value: true

cursorstring · query · optional

Length: 1 to 700 characters

orderstring · query · optional

Sort direction. Name and distance default to asc; population defaults to desc, with unknown counts last. Relevance supports asc only.

Values: asc, desc

nearbyboolean · query · required

Return a radius collection around lat and lon. Omit for the original single nearest-city response.

Value: true

sortstring · query · optional

Length: 0 to 100 characters

radiusnumber · query · optional

Coordinate nearby radius, default 40 km or 25 mi, max 800 km or 500 mi.

Range: no minimum to 800

unitstring · query · optional

Coordinate nearby radius unit.

Default: km

Values: km, mi

latnumber · query · required

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

Range: -90 to 90

lonnumber · query · required

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 or coordinate matches.

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 results per collection page. Nearest-city lookup returns one city.

Default: 10

Range: 1 to 50

langstring · query · optional

Length: 2 to 64 characters

deepboolean · query · optional

Population, its known observation date and basis, area, elevation and capital status. Included on paid plans.

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

Response fields

latitudenumber or null: Query origin latitude
longitudenumber or null: Query origin longitude
radiusnumber: Search radius used
unitstring: km or mi
nearbyarray: Cities on this page, each with distance and distance_mi from the origin
next_cursorstring or null: Opaque cursor for the next page, null at the end

Canonical JSON

Use format=resource for a single lookup and format=list for browse, search or nearby. Resources add object: "city". Lists contain object: "list", data and next_cursor, with query context in ordinary fields. The original default search cities and nearby nearby envelopes remain available.

HTTP format=geojson returns a Feature or FeatureCollection. Points use [longitude, latitude]; unknown coordinates produce geometry: null. These are stored place centers. A FeatureCollection retains paging context. Use HTTP directly for GeoJSON until a client exposes a typed GeoJSON operation.

Romanized names

With romanized=true, reviewed romanized names use name_romanized and romanization_language. Retained reviewed forms currently cover 20 Japanese whole-city aliases (ja-Latn). They preserve an admitted official name form, without substituting ASCII folding; lang chooses display text independently. Missing or conflicting forms stay null.

Relationships and distance

GET

api.parseapi.com/city/id/{id}/children

Reviewed children; coverage remains partial

Explore

Parameters 8

idstring · path · required

Stable returned City ID.

Pattern: ^city_[a-z0-9]{12}$

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

deepboolean · query · optional

Optional paid detail on each related City.

Value: true

limitinteger · query · optional

Maximum records per page, 1–50.

Range: 1 to 50

cursorstring · query · optional

Length: 1 to 700 characters

langstring · query · optional

Length: 2 to 64 characters

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

GET

api.parseapi.com/city/id/{id}/ancestors

Reviewed ancestors; coverage remains partial

Explore

Parameters 6

idstring · path · required

Stable returned City ID.

Pattern: ^city_[a-z0-9]{12}$

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

deepboolean · query · optional

Optional paid detail on each related City.

Value: true

langstring · query · optional

Length: 2 to 64 characters

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

GET

api.parseapi.com/city/id/{id}/siblings

Reviewed siblings; coverage remains partial

Explore

Parameters 8

idstring · path · required

Stable returned City ID.

Pattern: ^city_[a-z0-9]{12}$

hierarchyboolean · query · optional

Include the reviewed grain and immediate parent on each City. Unknown relationships are null.

Value: true

deepboolean · query · optional

Optional paid detail on each related City.

Value: true

limitinteger · query · optional

Maximum records per page, 1–50.

Range: 1 to 50

cursorstring · query · optional

Length: 1 to 700 characters

langstring · query · optional

Length: 2 to 64 characters

If-None-Matchstring · header · optional

Validate a cached canonical response or relationship list. Matching validators return 304 without a body; ordinary request billing and rate limits still apply.

romanizedboolean · query · optional

Value: true

GET

api.parseapi.com/city/id/{id}/distance/{other}

Distance between two recorded place centers

Explore

Parameters 2

idstring · path · required

Stable returned City ID.

Pattern: ^city_[a-z0-9]{12}$

otherstring · path · required

Destination City ID.

Pattern: ^city_[a-z0-9]{12}$

Use /city/id/{id}/children, /ancestors or /siblings for reviewed relationships. They return canonical lists with city_id, relationship and coverage: "partial". Empty results do not establish that no geographic relationship exists. Children and siblings accept limit and cursor; ancestors do not.

/city/id/{from}/distance/{to} returns object: "city_distance", the two IDs, distance in kilometers, distance_mi and method: "great_circle". Zero is known zero; null means a center is unavailable. This is center-to-center distance, with no road routing or boundary-containment inference.

Native City methods: JavaScript · Python · Go · Ruby · PHP · Rust · Swift · Kotlin. These examples use HTTP; each SDK reference shows its native signatures.

Coverage

See the City coverage list for supported countries and territories. Available place types, fields and population dates vary by source; listed coverage does not imply every place or field is complete.

These additions apply to current API 2.0.0. Frozen 1.0.0 retains its original contract.

Conditional HTTP requests

Canonical responses and relationships include an ETag with Cache-Control: private, no-cache. Send the cached validator in If-None-Match; an unchanged representation can return 304 without a body. Ordinary request billing and rate limits still apply. Keep the cached body for 304 and use HTTP directly for conditional requests; these client methods return ordinary JSON responses.

Population dates

On a paid plan, a reviewed deep.population count includes deep.population_observed_on and deep.population_basis, distinguishing a household-registration count from usual residents. New observations match the place layer: a ward count stays on its ward and a municipality total stays on the municipality. Download and refresh dates are never substituted for observation dates.

Deep

?deep=true Population, its known observation date and basis, 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("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",
  "district": "08031",
  "district_name": "Denver",
  "state": "CO",
  "state_name": "Colorado",
  "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,
    "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_observed_onstring: Exact observation date for a reviewed count at this place layer; omitted for legacy undated counts
deep.population_basisstring: Published counting basis, such as household registration or usual residence; omitted when unreviewed
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.

33 display language choices

Language tag	Language
en	English
ar	العربية
ca	català
hr	hrvatski
cs	čeština
da	dansk
nl	Nederlands
fi	suomi
fr	français
de	Deutsch
el	Ελληνικά
he	עברית
hi	हिन्दी
hu	magyar
id	Indonesia
it	italiano
ja	日本語
ko	한국어
ms	Melayu
nb	norsk bokmål
pl	polski
pt	português
ro	română
ru	русский
zh-Hans	简体中文
sk	slovenčina
es	español
sv	svenska
th	ไทย
zh-Hant	繁體中文
tr	Türkçe
uk	українська
vi	Tiếng Việt

Build with City

Add city autocomplete to an existing field

All tutorials →

Questions? Email

City API

By name#

Choose a city#

Choose a place layer#

Native and translated names#

By stable ID#

Search#

Browse and filter#

Stable ids#

Sorting and pages#

Nearest#

Nearby#

Nearby coordinates#

Canonical JSON#

Romanized names#

Relationships and distance#

Coverage#

Conditional HTTP requests#

Population dates#

Deep#

Display language#

Build with City

By name

Choose a city

Choose a place layer

Native and translated names

By stable ID

Search

Browse and filter

Stable ids

Sorting and pages

Nearest

Nearby

Nearby coordinates

Canonical JSON

Romanized names

Relationships and distance

Coverage

Conditional HTTP requests

Population dates

Deep

Display language