GET /v1/address/subregions

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

Like GET /v1/address/regions, this lists only the sub-regions that have addresses. A sub-region that is not in the response has no addresses, and a filter for it matches nothing.

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 sub-regions for. See GET /v1/address/regions for the codes.

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

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

Response

An array of { name, addresses }, ordered by name. name is the value a subRegion filter accepts, with no suffix such as "County".

[
  { "name": "Cochise", "addresses": 40000 },
  { "name": "Maricopa", "addresses": 2300000 }
]

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

The number of addresses varies widely between sub-regions, in proportion to population. To generate an even number of rows from each sub-region, use a weighted subRegions filter.

Filtering with these values

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

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "region": "az",
    "subRegions": [
      { "subRegion": "Maricopa", "weight": 2 },
      { "subRegion": "Pima" }
    ]
  },
  "map": { "addressLine1": { "column": "address_1", "dataType": "VarChar" } }
}

A sub-region filter cannot be combined with a city filter. To filter by a city, find it with GET /v1/address/cities and filter by the city alone.

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."
}

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