GET /v1/location/regions

Regions within a country. A region is the first division below the country, such as a state in one country and a prefecture in another. These are the values a region filter accepts in the boundingLocation of a Location or Geospatial field. For an Address field, use GET /v1/address/regions, which lists only the regions that have addresses.

Request

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

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

Response

An array of { code, name, outlineCharacters, overseas }, ordered by code. code is the value a region filter accepts.

[
  { "code": "AK", "name": "Alaska", "outlineCharacters": 780000, "overseas": false },
  { "code": "AL", "name": "Alabama", "outlineCharacters": 200000, "overseas": false },
  { "code": "CA", "name": "California", "outlineCharacters": 490000, "overseas": false }
]

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

outlineCharacters is the estimated size, in characters, of the 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 regions, so the regions in a filter affect the size of the output more than the row count does. Check it before mapping location, and see Boundaries.

The length and format of a region code depend on the country. Some codes are two letters, some are longer, and some are numeric. Use code from this response rather than assuming a fixed length or a letter code.

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. localName is absent for other countries. Japan's region codes are numeric, so name and localName identify each region:

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

[
  { "code": "01", "name": "Hokkaido", "outlineCharacters": 900000, "overseas": false, "localName": "北海道" },
  { "code": "02", "name": "Aomori", "outlineCharacters": 300000, "overseas": false, "localName": "青森県" }
]

To generate rows with the localName spelling rather than the romanized name, set japaneseScript on the field. See Location.

The list includes every region of the country, including territories and federal districts.

overseas is true for a region outside the country's main landmass. A request that does not set overseasTerritories returns no rows from such a region unless the region is in the filter. See Overseas territories.

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 a field's boundingLocation. Names must match exactly, including accents. See Matching place names.

{
  "type": "Location",
  "boundingLocation": {
    "country": "us",
    "regions": [{ "region": "ca", "weight": 2 }, { "region": "ny" }]
  },
  "map": { "city": { "column": "city", "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. See Location.

Errors

400 with a ProblemDetails body for a missing or unsupported country. See GET /v1/location/countries for the supported countries:

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

Table of Contents

GET /v1/location/regions

Request

Response

Filtering with these values

Errors