Docs
Contents

Locale API

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.

Provides localization static dictionaries and geolocation resolution services for global business and enterprise multilingual workspaces: supports resolving country, continent, EU membership, and suggested currency based on the client's request IP, and provides ISO-standard dictionaries of countries, continents, phone area codes, currencies, and languages.

Service and resource boundaries

The Locale API is a stateless internationalization (i18n) and regional metadata foundational service built into the Agentbase platform; its service boundary and core features are as follows:

Resources and Base Paths

Model NameAssociated EndpointCore FieldsDescription
localeGET /localeip, countryCode, country, continentCode, continent, eu, currencyThe current requester's geographic location and regionally localized profile
localeCodeListGET /locale/codestotal, localeCodes[] (code, name)List of ISO 639-1 / BCP-47 locale codes supported by the platform
continentListGET /locale/continentstotal, continents[] (name, code)List of the seven continent codes and localized names
countryListGET /locale/countries (/eu)total, countries[] (name, code)List of countries/regions worldwide or EU member states
phoneListGET /locale/countries/phonestotal, phones[] (code, countryCode, countryName)List of international long-distance telephone dialing code mappings
currencyListGET /locale/currenciestotal, currencies[] (symbol, name, code, decimalDigits, rounding)List of ISO 4217 currency symbols and precision rules
languageListGET /locale/languagestotal, languages[] (name, code, nativeName)List of language English names and native self-designated names

Authentication and Permissions

See general conventions for authentication and request header conventions.

Request HeaderRequiredExample ValueDescription
X-Appwrite-ProjectYesenterprise-ai-hub-210Project ID
X-Appwrite-KeyRequired for server-side calls<APPBASE_API_KEY>Project API Key, must have the locale.read scope
X-Appwrite-LocaleNozh-CNSpecifies the localization language code for returned country and continent names

Endpoint overview

The Locale service contains 8 read-only endpoints in total, divided into two major categories: “requester region detection” and “standard enumeration dictionaries”:

CategoryEndpointsReturned ModelTypical Use Cases
Requester region detectionGET /v1/localelocaleAutomatically identify the visitor's timezone/country and default language when initializing an intelligent customer service session
Language and region codesGET /v1/locale/codes, GET /v1/locale/languageslocaleCodeList, languageListLanguage switch dropdown menu in the Console or client personal center
Geography and telephone codesGET /v1/locale/continents, GET /v1/locale/countries, GET /v1/locale/countries/eu, GET /v1/locale/countries/phonescontinentList, countryList, phoneListMobile number SMS verification code login components (such as +86) and GDPR EU compliance routing checks
Currency and settlement rulesGET /v1/locale/currenciescurrencyListAI Gateway billing display, multi-currency decimal places and rounding formatting

Endpoint List

Method + PathScopeIdempotencyPurpose
GET /localelocale.readYesGet the current requester's geographic and localization information
GET /locale/codeslocale.readYesList all supported Locale codes
GET /locale/continentslocale.readYesList all continent codes and names
GET /locale/countrieslocale.readYesList all country/region codes and names
GET /locale/countries/eulocale.readYesList current European Union (EU) member states
GET /locale/countries/phoneslocale.readYesList the mapping table of country telephone dialing codes and countries
GET /locale/currencieslocale.readYesList all ISO 4217 currencies and formatting rules
GET /locale/languageslocale.readYesList all ISO 639-1 languages and native names

Endpoint details

Multilingual Dictionary Switching and Caching Practices

Requests and Responses

Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), examples (copyable curl), and response examples.

Locale

GET /v1/locale

Resolve the current user's geographic and localization information by request IP: country, continent, EU membership, and suggested currency; combined with the X-Appwrite-Locale request header, language names can be returned in the corresponding language.

Input: no path/query/body parameters (optional request header X-Appwrite-Locale).

Output: returns the 200 OK + locale model:

FieldTypeDescription
ipstringClient IP address
countryCodestringISO 3166-1 two-letter country code (such as CN, US); "" when the IP is an internal unknown IP
countrystringCountry name (supports X-Appwrite-Locale localization)
continentCodestringContinent code: AF / AN / AS / EU / NA / OC / SA
continentstringContinent name (supports localization)
eubooleanWhether it is an EU member state
currencystringISO 4217 three-letter currency code (such as CNY, USD)

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @- \
  -H "X-Appwrite-Locale: zh-CN"
)

Response example:

{
  "ip": "192.0.2.10",
  "countryCode": "CN",
  "country": "China",
  "continentCode": "AS",
  "continent": "Asia",
  "eu": false,
  "currency": "CNY"
}

GET /v1/locale/codes

List all locale codes (ISO 639-1 / BCP-47) for frontend language dropdowns or as a reference for X-Appwrite-Locale values.

Input: no path/query/body parameters.

Output: returns localeCodeList (total + localeCodes[]; elements contain code and name).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/codes" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "localeCodes": [
    {
      "code": "en-us",
      "name": "US"
    },
    {
      "code": "zh-cn",
      "name": "China"
    }
  ]
}

GET /v1/locale/continents

List all continents (two-letter code + name; names support localization).

Input: no path/query/body parameters.

Output: returns continentList (total + continents[]; elements contain name and code).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/continents" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "continents": [
    {
      "name": "Europe",
      "code": "EU"
    },
    {
      "name": "Asia",
      "code": "AS"
    }
  ]
}

GET /v1/locale/countries

List all countries (ISO 3166-1 two-letter code + name; names support localization).

Input: no path/query/body parameters.

Output: returns countryList (total + countries[]; elements contain name and code).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "countries": [
    {
      "name": "United States",
      "code": "US"
    },
    {
      "name": "China",
      "code": "CN"
    }
  ]
}

GET /v1/locale/countries/eu

List current EU member states (same structure as /locale/countries).

Input: no path/query/body parameters.

Output: returns countryList (total + countries[]; elements contain name and code).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries/eu" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "countries": [
    {
      "name": "Germany",
      "code": "DE"
    },
    {
      "name": "France",
      "code": "FR"
    }
  ]
}

GET /v1/locale/countries/phones

List country telephone dialing codes: mapped to country codes, used for mobile number input components and Messaging SMS number prefix validation.

Input: no path/query/body parameters.

Output: returns phoneList (total + phones[]; elements contain code (such as +1, +86), countryCode, and countryName).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries/phones" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "phones": [
    {
      "code": "+1",
      "countryCode": "US",
      "countryName": "United States"
    },
    {
      "code": "+86",
      "countryCode": "CN",
      "countryName": "China"
    }
  ]
}

GET /v1/locale/currencies

List all currencies: symbols, names, plurals, decimal places, and rounding rules, for amount formatting.

Input: no path/query/body parameters.

Output: returns currencyList (total + currencies[]):

FieldTypeDescription
symbolstringInternationally universal currency symbol (such as $, ¥)
namestringCurrency singular name (such as Chinese yuan)
symbolNativestringLocal currency symbol
decimalDigitsintegerStandard number of decimal places (e.g., CNY is 2, JPY is 0)
roundingnumberMinimum rounding step (usually 0)
codestringISO 4217 three-letter uppercase code (such as CNY, USD)
namePluralstringCurrency plural name

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/currencies" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "currencies": [
    {
      "symbol": "$",
      "name": "US dollar",
      "symbolNative": "$",
      "decimalDigits": 2,
      "rounding": 0,
      "code": "USD",
      "namePlural": "US dollars"
    },
    {
      "symbol": "¥",
      "name": "Chinese yuan",
      "symbolNative": "¥",
      "decimalDigits": 2,
      "rounding": 0,
      "code": "CNY",
      "namePlural": "Chinese yuan"
    }
  ]
}

GET /v1/locale/languages

List all languages (ISO 639-1): two-letter codes, English names, and native language names.

Input: no path/query/body parameters.

Output: returns languageList (total + languages[]; elements contain name, code, and nativeName).

Call example:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/languages" \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Response example:

{
  "total": 2,
  "languages": [
    {
      "name": "Italian",
      "code": "it",
      "nativeName": "Italiano"
    },
    {
      "name": "Chinese",
      "code": "zh",
      "nativeName": "中文"
    }
  ]
}

Errors and boundaries

HTTP Status CodeError Type (type)Trigger CauseTroubleshooting Recommendation
401 Unauthorizedgeneral_access_forbiddenMissing X-Appwrite-Project or the project ID does not existCheck the project ID in the request headers (such as enterprise-ai-hub-210)
401 Unauthorizedgeneral_unauthorized_scopeThe API Key has not been granted the locale.read permissionEnable locale.read in the Console API Key settings
429 Too Many Requestsgeneral_rate_limit_exceededHigh-frequency polling of static dictionaries triggers instance rate limitingDictionary lists (countries/currencies/phones/languages) should be cached in application memory rather than fetched in real time on every user request

Correspondence with the Server SDK

Server SDK service.methodHTTP Method and PathReturned Model
Locale.getGET /v1/localelocale
Locale.listCodesGET /v1/locale/codeslocaleCodeList
Locale.listContinentsGET /v1/locale/continentscontinentList
Locale.listCountriesGET /v1/locale/countriescountryList
Locale.listCountriesEUGET /v1/locale/countries/eucountryList
Locale.listCountriesPhonesGET /v1/locale/countries/phonesphoneList
Locale.listCurrenciesGET /v1/locale/currenciescurrencyList
Locale.listLanguagesGET /v1/locale/languageslanguageList