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
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city("charlotte");
console.log(result);{
"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.
SearchCopy link
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:
10Range: 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:
prefixValues:
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
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);{
"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:
10Range: 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
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city.nearest(35.2271, -80.8431);
console.log(result);{
"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
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);{
"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:
kmValues:
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:
10Range: 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
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 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 |