GET /v1/location/world-countries

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

This list contains more countries than GET /v1/location/countries. A filter that includes a region, sub-region, city or postal code requires a country from that shorter list.

Request

No body, no query parameters.

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

Response

An array of { code, name, outlineCharacters }, alphabetical by name. code is the two-letter code a country filter accepts, and name is the country's name in English.

[
  { "code": "af", "name": "Afghanistan", "outlineCharacters": 60000 },
  { "code": "al", "name": "Albania", "outlineCharacters": 15000 },
  { "code": "dz", "name": "Algeria", "outlineCharacters": 40000 }
]

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

outlineCharacters is the estimated size, in characters, of the country'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 places. Check it before mapping location, and see Boundaries.

Filtering with these values

A code from this list is used in the country property, with no city, region, sub-region or postal code:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "fr" },
  "map": { "value": { "column": "origin", "dataType": "Geometry" } }
}

The weighted countries list accepts one code per entry, and can be combined with the more specific levels:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "countries": [{ "country": "br", "weight": 2 }, { "country": "ar" }]
  },
  "map": { "value": { "column": "origin", "dataType": "Geometry" } }
}

A country includes all of its territory, including overseas territory, so a country with land on more than one continent produces places on each of them.

See Geospatial and Location for how a country is combined with the more specific levels.

Which list to use

Filtering by	List to use
country alone	This endpoint.
region, subRegion, city or postal code	GET /v1/location/countries, which also lists the levels each country supports.

A city, region, sub-region or postal code entry with a country outside the shorter list is rejected, and the error lists the countries it accepts. A country set alone is not validated when the request is received, so a code that does not exist causes the request to fail during generation, with an error stating that nothing matched.

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