Docs
Contents

Locale API

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/codes" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/continents" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries/eu" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries/phones" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/currencies" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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:

curl "https://appbuild-sit.oceanbase.com/v1/locale/languages" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

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