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. Every plan includes type, county, coordinates and timezone where known, with a stable city ID. Paid plans automatically include 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.

A name lookup with no match returns 404; search and Browse return an empty list.

By nameCopy link

GET /city/{name}API Explorer ↗

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

Parameters

namestring · path · required

City name

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: geojson

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

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

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city("charlotte");
console.log(result);
Example responsePaid plan
{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "county": "37119",
  "county_name": "Mecklenburg",
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "timezone": "America/New_York",
  "capital_of": null,
  "elevation": 209,
  "elevation_ft": 686,
  "population": 943476,
  "area": 813.48,
  "land_area": 808.33,
  "water_area": 5.15,
  "id": "city_mb8mbqrkz8zb"
}

Response fields

nameLink to namestring or null
City name
name_localLink to name_localstring or null
Local-language name, null when absent or identical to name
typeLink to typestring or null
What the place is in its own country's words (city, town, commune, ward)
countyLink to countystring or null
County code the city sits in (US FIPS, FR INSEE, GB GSS)
county_nameLink to county_namestring or null
County name
stateLink to statestring or null
State or province code
state_nameLink to state_namestring or null
State or province name
countryLink to countrystring or null
ISO2 country code
country_nameLink to country_namestring or null
Country name
latitudeLink to latitudenumber or null
Latitude
longitudeLink to longitudenumber or null
Longitude
timezoneLink to timezonestring or null
Timezone identifier
distanceLink to distancenumber
Kilometers from query point (coords and nearby)
distance_miLink to distance_minumber
Miles from query point (coords and nearby)
grainLink to grainstring or null
Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
parentLink to 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
idLink to idstring or null
Stable city id (city_...). Fetch again at /city/id/{id}

Choose a cityCopy link

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 profile fields. 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 layerCopy link

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.2.0.

Native and translated namesCopy link

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 IDCopy link

GET /city/id/{id}API Explorer ↗

Retrieve the same city using its returned ID

Parameters

idstring · path · required

Stable city id from any city response

hierarchyboolean · query · optional

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

Value: true

formatstring · query · optional

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: geojson

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

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

Store the id returned by a lookup, search, nearest or nearby result. Use it here to retrieve that city without repeating a name search. Names and facts can change while the ID stays the same. Missing cities return 404. The response has the same fields and plan detail as a name lookup.

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 /city?q={query}API Explorer ↗

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

Parameters

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

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: 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

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

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. Unknown values sort last.

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

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

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

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 /city/searchAPI Explorer ↗

Explicit spelling suggestions; canonical list

Parameters

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

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

Default canonical list, or format=geojson for stored place centers.

Values: 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

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

prettyboolean · query · optional

Indent the JSON response for readability.

Value: true

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

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

Request

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

Response fields

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

Browse and filterCopy link

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 included on paid plans for that place layer. timezones accepts a comma-separated set of exact timezone identifiers. 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 /city?browse=true&country=JP&min_population=100000&sort=population&limit=50API Explorer ↗

Browse covered places, largest first

Parameters

browseboolean · query · required

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

Value: true

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: 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

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

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. Unknown values sort last.

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

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

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

Response fields

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

Sorting and pagesCopy link

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 and can depend on the catalog edition. A changed query or invalid cursor returns 400. Restart without the cursor when a page can no longer be retrieved.

NearestCopy link

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 /city?lat={lat}&lon={lon}API Explorer ↗

Nearest city by coordinates

Parameters

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

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: geojson

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

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

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

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.nearest(35.2271, -80.8431);
console.log(result);
Example responsePaid plan
{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "county": "37119",
  "county_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,
  "capital_of": null,
  "elevation": 209,
  "elevation_ft": 686,
  "population": 943476,
  "area": 813.48,
  "land_area": 808.33,
  "water_area": 5.15,
  "id": "city_mb8mbqrkz8zb"
}

Response fields

nameLink to namestring or null
City name
name_localLink to name_localstring or null
Local-language name, null when absent or identical to name
typeLink to typestring or null
What the place is in its own country's words (city, town, commune, ward)
countyLink to countystring or null
County code the city sits in (US FIPS, FR INSEE, GB GSS)
county_nameLink to county_namestring or null
County name
stateLink to statestring or null
State or province code
state_nameLink to state_namestring or null
State or province name
countryLink to countrystring or null
ISO2 country code
country_nameLink to country_namestring or null
Country name
latitudeLink to latitudenumber or null
Latitude
longitudeLink to longitudenumber or null
Longitude
timezoneLink to timezonestring or null
Timezone identifier
distanceLink to distancenumber
Kilometers from query point
distance_miLink to distance_minumber
Miles from query point
grainLink to grainstring or null
Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
parentLink to parentobject or null
Reviewed immediate parent, returned with hierarchy=true; null when unreviewed
idLink to idstring or null
Stable city id (city_...). Fetch again at /city/id/{id}

NearbyCopy link

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 /city/{name}/nearbyAPI Explorer ↗

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

Parameters

namestring · path · required

Anchor city name

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: 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

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

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. Unknown values sort last.

Length: 0 to 100 characters

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

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

Request

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);
Example responsePaid plan
{
  "city": "Denver",
  "state": "CO",
  "country": "US",
  "radius": 8,
  "unit": "mi",
  "nearby": [
    {
      "name": "Glendale",
      "name_local": null,
      "type": "city",
      "county": "08005",
      "county_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,
      "capital_of": null,
      "elevation": 1631,
      "elevation_ft": 5351,
      "population": 4465,
      "area": 1.48,
      "land_area": 1.47,
      "water_area": 0.01,
      "id": "city_5bjs2r33bamc"
    },
    {
      "name": "Four Square Mile",
      "name_local": null,
      "type": "census designated place",
      "county": "08005",
      "county_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,
      "capital_of": null,
      "elevation": 1662,
      "elevation_ft": 5453,
      "population": 22872,
      "area": 7,
      "land_area": 7,
      "water_area": 0,
      "id": "city_3y2ehrvkj73q"
    },
    {
      "name": "Derby",
      "name_local": null,
      "type": "census designated place",
      "county": "08001",
      "county_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,
      "capital_of": null,
      "elevation": 1563,
      "elevation_ft": 5128,
      "population": 8407,
      "area": 4.57,
      "land_area": 4.53,
      "water_area": 0.04,
      "id": "city_sj3r8bzde3tk"
    }
  ]
}

Response fields

cityLink to citystring or null
Anchor city name
stateLink to statestring or null
Anchor state code
countryLink to countrystring or null
ISO2 country code
radiusLink to radiusnumber
Search radius used
unitLink to unitstring
km or mi
nearbyLink to nearbyarray
Cities inside the radius in the requested order, nearest first by default, each with distance and distance_mi
next_cursorLink to 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 coordinatesCopy link

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 /city?lat=48.2082&lon=16.3738&nearby=true&radius=40&unit=km&limit=50API Explorer ↗

Cities around a coordinate origin

Parameters

nearbyboolean · query · required

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

Value: true

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

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

Use geojson for stored-center Features. Omit to retain this route’s default response.

Values: 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

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

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. Unknown values sort last.

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

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

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

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

Response fields

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

Canonical JSONCopy link

Each route keeps its default response. The explicit /city/search?q= route and relationship routes use data lists. Use format=geojson for stored-center Features.

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 namesCopy link

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 distanceCopy link

GET /city/id/{id}/childrenAPI Explorer ↗

Reviewed children; coverage remains partial

Parameters

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

limitinteger · query · optional

Maximum records per page, 1–50.

Range: 1 to 50

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

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

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

GET /city/id/{id}/ancestorsAPI Explorer ↗

Reviewed ancestors; coverage remains partial

Parameters

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

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

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

GET /city/id/{id}/siblingsAPI Explorer ↗

Reviewed siblings; coverage remains partial

Parameters

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

limitinteger · query · optional

Maximum records per page, 1–50.

Range: 1 to 50

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

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

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

GET /city/id/{id}/distance/{other}API Explorer ↗

Distance between two recorded place centers

Parameters

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.

For native City methods, see the SDK references.

CoverageCopy link

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.2.0. Frozen 1.0.0 retains its original contract.

Conditional HTTP requestsCopy link

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 datesCopy link

On a paid plan, a reviewed population count includes population_observed_on and 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.

Included dataCopy link

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

Paid plan fields

capital_ofLink to capital_ofstring or null
country when it is a national capital, state when it is a state or region capital, null otherwise
elevationLink to elevationinteger or null
Elevation in meters at the city center
elevation_ftLink to elevation_ftinteger or null
Elevation in feet
populationLink to populationinteger or null
Population
population_observed_onLink to population_observed_onstring
Exact observation date for a reviewed count at this place layer; omitted for legacy undated counts
population_basisLink to population_basisstring
Published counting basis, such as household registration or usual residence; omitted when unreviewed
areaLink to areanumber or null
Total area in km² (land + water, or the official total)
land_areaLink to land_areanumber or null
Land area in km² (null when the source publishes total only)
water_areaLink to water_areanumber or null
Water area in km² (null when the source publishes total only)

Display languageCopy link

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state, county 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. Display language is available on API 2.1.0; requests selecting frozen 1.0.0 retain their original contract. See API versions.

33 display language choices

Language tagLanguage
enEnglish
arالعربية
cacatalà
hrhrvatski
csčeština
dadansk
nlNederlands
fisuomi
frfrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
humagyar
idIndonesia
ititaliano
ja日本語
ko한국어
msMelayu
nbnorsk bokmål
plpolski
ptportuguês
roromână
ruрусский
zh-Hans简体中文
skslovenčina
esespañol
svsvenska
thไทย
zh-Hant繁體中文
trTürkçe
ukукраїнська
viTiếng Việt