GET /v1/location/cities

Cities within a region. These are the values a city filter accepts in the boundingLocation of a Location or Geospatial field. For an Address field, use GET /v1/address/cities, which lists only the cities that have addresses.

Request

Query parameter	Required	Default	Description
country	Yes	none	The country the region is in. See GET /v1/location/countries for the codes.
region	Yes	none	The region to list cities for. See GET /v1/location/regions for the codes.
subRegion	No	none	Limits the list to the cities in one sub-region. See GET /v1/location/subregions for the names.

country and region are required, because the same city name is used in more than one region.

curl "https://api.alchemy.example/v1/location/cities?country=us&region=ca" -H "X-Api-Key: YOUR_API_KEY"

curl "https://api.alchemy.example/v1/location/cities?country=us&region=ca&subRegion=Orange" -H "X-Api-Key: YOUR_API_KEY"

Response

An array of { name, officialName, outlineCharacters }, ordered by name. name is the value a city filter accepts, and officialName is the full official name that the cityName sub-field returns.

[
  { "name": "Aliso Viejo", "officialName": "Aliso Viejo city", "outlineCharacters": 17000 },
  { "name": "Anaheim", "officialName": "Anaheim city", "outlineCharacters": 61000 },
  { "name": "Brea", "officialName": "Brea city", "outlineCharacters": 25000 }
]

The entries above are an example. Call the endpoint for the current list and values.

outlineCharacters is the estimated size, in characters, of the city's boundary when the location sub-field is mapped. It determines how many rows fit within the data limit of a request. The size varies more between cities than at any other level, because the list includes both large cities and small unincorporated places. Check it before mapping location, and see Boundaries.

For a country whose places have names in more than one script, each entry also has localName, the name in the country's own script. Japanese cities have both names:

[
  { "name": "Abashiri", "officialName": "Abashiri-shi", "outlineCharacters": 260000, "localName": "網走" }
]

Filtering with these values

A name from this list is used in the city property, or in an entry of the weighted cities list, in a field's boundingLocation. Names must match exactly, including accents. See Matching place names.

Errors

400 with a ProblemDetails body:

Status	When
400	country or region is missing, or country is not in GET /v1/location/countries.
400	subRegion is set for a country with no sub-regions.

Requires an API key (see Authentication) but is not billed.