GET /v1/address/cities

Cities within a region that have addresses, and the number of addresses in each. These are the values a city filter accepts in an Address field's boundingLocation.

A filter for a city with no addresses matches nothing, even when the city exists and is in the region in the filter. This endpoint lists the cities that have addresses.

GET /v1/location/cities lists every city in a region, including cities with no addresses.

Request

Query parameter	Required	Default	Description
`country`	Yes	none	The country the region is in. See GET /v1/address/countries for the codes.
`region`	Yes	none	The region to list cities for. See GET /v1/address/regions for the codes.
`subRegion`	No	none	Limits the list to the cities in one sub-region. See GET /v1/address/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/address/cities?country=us&region=az" -H "X-Api-Key: YOUR_API_KEY"

Limited to one sub-region:

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

Response

An array of { name, addresses }, ordered by name. name is the value a city filter accepts.

[
  { "name": "Mesa", "addresses": 290000 },
  { "name": "Phoenix", "addresses": 720000 }
]

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

The number of addresses varies widely between cities, in proportion to population. To generate an even number of rows from each city, use a weighted cities filter.

A city that spans more than one sub-region is listed once, with the addresses in every sub-region added together. This is the same set of addresses a city filter returns. With subRegion set, the count includes only the addresses in that sub-region.

Not every address is in a city. An address outside any city still has a sub-region and a region, so the counts in this response add up to less than the region's total.

Filtering with these values

A name from this list is used in the city property, or in an entry of the weighted cities list. Names must match exactly, including accents. See Name matching.

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "region": "az",
    "cities": [
      { "city": "Phoenix", "weight": 3 },
      { "city": "Flagstaff" }
    ]
  },
  "map": { "addressLine1": { "column": "address_1", "dataType": "VarChar" } }
}

A city filter cannot be combined with a sub-region filter. Use subRegion on this endpoint to find the city, then filter by the city.

Errors

400 with a ProblemDetails body for a missing or unsupported country, or a missing region:

{
  "type": "urn:alchemy:error:invalid-reference-query",
  "title": "Invalid request.",
  "status": 400,
  "detail": "region is required."
}

A subRegion that is not recognized is not an error. The response is an empty array.

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

Table of Contents

GET /v1/address/cities

Request

Response

Filtering with these values

Errors