GET /v1/location/subregions

Sub-regions within a region. A sub-region is the division below a region, such as a county in one country and a local authority in another. These are the values a subRegion filter accepts in the boundingLocation of a Location or Geospatial field. For an Address field, use GET /v1/address/subregions, which lists only the sub-regions 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. A request without it returns 400.
region	Yes	none	The region to list sub-regions for. See GET /v1/location/regions for the codes. A request without it returns 400.

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

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

Response

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

[
  { "name": "Alameda", "outlineCharacters": 88000 },
  { "name": "Alpine", "outlineCharacters": 41000 },
  { "name": "Amador", "outlineCharacters": 47000 }
]

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

outlineCharacters is the estimated size, in characters, of the sub-region'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 widely between sub-regions. Check it before mapping location, and see Boundaries.

A country whose subRegion property is false in GET /v1/location/countries has no sub-regions, and a request for one of its regions returns 400, not an empty list.

Filtering with these values

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

{
  "type": "Location",
  "boundingLocation": {
    "country": "us",
    "region": "ca",
    "subRegions": [{ "subRegion": "Orange" }, { "subRegion": "Placer" }]
  },
  "map": { "city": { "column": "city", "dataType": "VarChar" } }
}

Every row is from a place in one of the sub-regions in the filter. A name that is not in this list matches nothing and the request fails, so use the names from this response rather than typing them.

A subRegions entry can set its own country and region. A country and region set with the list apply to every entry that does not set its own. See Location.

Errors

400 with a ProblemDetails body for a missing or unsupported country, a country with no sub-regions, 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.