Locale
The Locale operations are for developers who need country, currency or language data in an integration or a storefront. They answer two questions: where is the caller, based on its IP address, and what are the reference lists for countries, continents, currencies, languages, phone codes and locale codes. All eight operations are GET requests with no parameters.
Before you call
Every call needs one of the two credentials the gateway accepts: an API key in X-Revenexx-Api-Key, or a Bearer token. An API key must carry the locale scope (or *); without it the call fails with 403. Send your tenant in X-Revenexx-Tenant on every call; without it the call fails with 400. See Authentication and API keys for how to get and send a credential.
Operations
| Operation | Path | Returns |
|---|---|---|
| Get user locale | GET /v1/locale | The caller's country, continent, IP address, suggested currency and EU flag. |
| List locale codes | GET /v1/locale/codes | All locale codes, ISO 639-1. |
| List continents | GET /v1/locale/continents | All continents. |
| List countries | GET /v1/locale/countries | All countries. |
| List EU countries | GET /v1/locale/countries/eu | The countries that are currently members of the EU. |
| List countries phone codes | GET /v1/locale/countries/phones | The phone code of each country. |
| List currencies | GET /v1/locale/currencies | All currencies, with symbol, name, plural name and decimal digits. |
| List languages | GET /v1/locale/languages | All languages, ISO 639-1, with the English and the native name. |
Get the caller's locale
curl https://api.revenexx.com/v1/locale \
-H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
-H "X-Revenexx-Tenant: acme"
The location comes from the IP address the request arrives from. Called from your backend, that is your server's address, not your buyer's. Location data comes from DB-IP. The response has these fields, all of them always present. If the IP address cannot be located, countryCode and continentCode are --, eu is false and currency holds no code; the same is true of currency for a country with no mapped currency.
| Field | Type | Meaning |
|---|---|---|
ip | string | The caller's IP address. |
countryCode | string | The country code, ISO 3166-1 two-character format. |
country | string | The country name. |
continentCode | string | The continent code: AF, AN, AS, EU, NA, OC or SA. |
continent | string | The continent name. |
eu | boolean | true if the country is currently a member of the European Union. |
currency | string | The suggested currency, ISO 4217 three-character format. |
Reference lists
Each list returns a total, the number of entries, and one array of entries. All entry fields are always present.
| Operation | Array field |
|---|---|
| List locale codes | localeCodes |
| List continents | continents |
| List countries | countries |
| List EU countries | countries |
| List countries phone codes | phones |
| List currencies | currencies |
| List languages | languages |
| Entry | Field | Type | Meaning |
|---|---|---|---|
| Locale code | code | string | Locale code, ISO 639-1. |
| Locale code | name | string | Locale name. |
| Continent | code | string | Two-letter continent code. |
| Continent | name | string | Continent name. |
| Country | code | string | Two-character ISO 3166-1 alpha code. |
| Country | name | string | Country name. |
| Phone | code | string | Phone code. |
| Phone | countryCode | string | Two-character ISO 3166-1 alpha code of the country. |
| Phone | countryName | string | Country name. |
| Currency | code | string | Currency code, ISO 4217 three-character format. |
| Currency | name | string | Currency name. |
| Currency | namePlural | string | Plural name of the currency. |
| Currency | symbol | string | Currency symbol. |
| Currency | symbolNative | string | Native currency symbol. |
| Currency | decimalDigits | integer | Number of decimal digits. |
| Currency | rounding | number | Currency digit rounding. |
| Language | code | string | Two-character ISO 639-1 code. |
| Language | name | string | Language name in English. |
| Language | nativeName | string | Language name in the language itself. |
Localised names
The country and continent names in the caller's locale can come back in another supported language. The continents, countries, EU countries, phone codes and currencies lists say the same of their names. This page does not yet document how to ask for a language (as of 2026-10), so treat the names as display text and key your data on the codes.
Errors
| Status | When |
|---|---|
400 | The X-Revenexx-Tenant header is missing. |
401 | The credential is missing or invalid. |
403 | The caller is authenticated but not permitted, for example an API key without the locale scope. |
429 | The tenant's rate limit was exceeded. |
502 | The service behind the route could not be reached or did not answer in time. |
For the error body and what to do for each status, see Errors.