GET /v1/address/regions

Regions within a country that have addresses, and the number of addresses in each. A region is the first division below the country, such as a state. These are the values a region filter accepts in an Address field's boundingLocation.

Use this endpoint before filtering addresses by place. A country listed by GET /v1/address/countries does not necessarily have addresses in every region. Every region in this response has addresses. A region that is not in this response has no addresses, and a filter for it matches nothing.

Request

Query parameter	Required	Default	Description
country	Yes	none	The country to list regions for. See GET /v1/address/countries for the codes. A request without it returns 400.

curl "https://api.alchemy.example/v1/address/regions?country=us" -H "X-Api-Key: YOUR_API_KEY"

Response

An array of { code, name, addresses }, ordered by code. code is the value a region filter accepts, name is the region's full name, and addresses is the number of addresses in the region.

[
  { "code": "AZ", "name": "Arizona", "addresses": 3700000 },
  { "code": "CA", "name": "California", "addresses": 15000000 }
]

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

addresses is also the maximum number of distinct addresses a request filtered to that region can return.

The length and format of a region code depend on the country, so use code from this response rather than assuming a fixed length.

Filtering with these values

A code from this list is used in the region property, or in an entry of the weighted regions list, in an Address field's boundingLocation. Names must match exactly, including accents. See Name matching.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "region": "az" },
  "map": { "addressLine1": { "column": "address_1", "dataType": "VarChar" } }
}

A region set with a subRegion or city limits that sub-region or city to the region, which selects the right place when the same name is used in more than one region.

Errors

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

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

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