GET /v1/location/countries

Countries whose regions, sub-regions, cities and postal codes a filter accepts. These are the values a country filter accepts in the boundingLocation of a Location or Geospatial field when a region, sub-region, city or postal code is set with it. For an Address field, use GET /v1/address/countries.

Two country lists

There are two lists of countries, and which one applies depends on whether a request uses anything more specific than the country:

Endpoint	Lists	Applies when
This endpoint	Countries with regions and cities, and for some of them sub-regions and postal codes.	The boundingLocation includes a region, sub-region, city or postal code, or a Location field maps region, subRegion, city, zip or any other sub-field below the country.
GET /v1/location/world-countries	Every country with a national boundary. It contains many more countries than this endpoint.	The boundingLocation sets only country or countries, with nothing more specific, and a Location field maps only country, countryName or location.

For example, Brazil (br) is listed by GET /v1/location/world-countries but not by this endpoint:

• A Geospatial field with "boundingLocation": { "country": "br" } generates geometry anywhere in Brazil.
• A Location field that maps only country or countryName returns Brazil as a country row.
• A Location field that maps city for br, or any filter that includes br with a region, sub-region, city or postal code, is rejected, and the error lists the countries this endpoint returns.

Request

No body, no query parameters.

curl https://api.alchemy.example/v1/location/countries -H "X-Api-Key: YOUR_API_KEY"

Response

An array of { code, name, subRegion, postal, overseas }, alphabetical by name:

[
  { "code": "au", "name": "Australia", "subRegion": true, "postal": true, "overseas": true },
  { "code": "jp", "name": "Japan", "subRegion": false, "postal": false, "overseas": false }
]

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

Property	Description
code	The value a country filter accepts.
name	The country's name.
subRegion	Whether a filter or a mapping accepts the country's sub-regions.
postal	Whether a filter or a mapping accepts the country's postal codes.
overseas	Whether any of the country's regions are outside its main landmass. See Overseas territories.

Every country in the list supports regions and cities. A filter or mapping that uses a sub-region or postal code for a country where subRegion or postal is false is rejected.

When overseas is false, the overseasTerritories setting has no effect for that country. GET /v1/location/regions shows which regions are outside the main landmass.

Filtering with these values

A code from this list is used in the country property, or in an entry of the weighted countries list, in a field's boundingLocation:

{
  "type": "Location",
  "boundingLocation": {
    "countries": [{ "country": "au", "weight": 2 }, { "country": "jp" }]
  },
  "map": { "city": { "column": "city", "dataType": "VarChar" } }
}

Every entry in a regions, subRegions or cities list can also set its own country, so one field can include places in more than one country. See Location.

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