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:
Read-only static dictionaries and IP attribution resolution: All endpoints are idempotent
GETrequests and incur no business table write overhead in the project database (OceanBaseShared V2).Multilingual dynamic translation (
X-Appwrite-Locale): Callers can specify the target language for display names such ascountry,continent, andcountries[].namein response dictionaries via theX-Appwrite-Localerequest header (e.g.,zh-CN,en-US,ja-JP); if unspecified, English (en) is used by default.Integration with the graphical avatar service: the two-letter ISO 3166-1 Alpha-2 country code returned by
/v1/locale/countries(such asCN,US) can be passed directly to the avatar and graphics API/v1/avatars/flags/{code}endpoint to render the corresponding national flag icon.Notes on proxy passthrough: when the server acts as a reverse proxy calling
GET /v1/localeon behalf of end users, theipfield reflects the egress IP that initiated the HTTP request (or theX-Forwarded-Forclient's real IP forwarded by a trusted gateway).
Resources and Base Paths
Base URL:
https://appbuild-sit.oceanbase.com/v1(orhttps://<your-endpoint>/v1).Path prefix:
/locale; stateless endpoints that returnlocaleand various*Liststatic dictionary models.Core response model overview:
| Model Name | Associated Endpoint | Core Fields | Description |
|---|---|---|---|
locale | GET /locale | ip, countryCode, country, continentCode, continent, eu, currency | The current requester's geographic location and regionally localized profile |
localeCodeList | GET /locale/codes | total, localeCodes[] (code, name) | List of ISO 639-1 / BCP-47 locale codes supported by the platform |
continentList | GET /locale/continents | total, continents[] (name, code) | List of the seven continent codes and localized names |
countryList | GET /locale/countries (/eu) | total, countries[] (name, code) | List of countries/regions worldwide or EU member states |
phoneList | GET /locale/countries/phones | total, phones[] (code, countryCode, countryName) | List of international long-distance telephone dialing code mappings |
currencyList | GET /locale/currencies | total, currencies[] (symbol, name, code, decimalDigits, rounding) | List of ISO 4217 currency symbols and precision rules |
languageList | GET /locale/languages | total, 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 Header | Required | Example Value | Description |
|---|---|---|---|
X-Appwrite-Project | Yes | enterprise-ai-hub-210 | Project ID |
X-Appwrite-Key | Required for server-side calls | <APPBASE_API_KEY> | Project API Key, must have the locale.read scope |
X-Appwrite-Locale | No | zh-CN | Specifies the localization language code for returned country and continent names |
The OpenAPI spec authentication annotation is
Project + SessionorProject + Key; the required API Key Scope islocale.read.
Endpoint overview
The Locale service contains 8 read-only endpoints in total, divided into two major categories: “requester region detection” and “standard enumeration dictionaries”:
| Category | Endpoints | Returned Model | Typical Use Cases |
|---|---|---|---|
| Requester region detection | GET /v1/locale | locale | Automatically identify the visitor's timezone/country and default language when initializing an intelligent customer service session |
| Language and region codes | GET /v1/locale/codes, GET /v1/locale/languages | localeCodeList, languageList | Language switch dropdown menu in the Console or client personal center |
| Geography and telephone codes | GET /v1/locale/continents, GET /v1/locale/countries, GET /v1/locale/countries/eu, GET /v1/locale/countries/phones | continentList, countryList, phoneList | Mobile number SMS verification code login components (such as +86) and GDPR EU compliance routing checks |
| Currency and settlement rules | GET /v1/locale/currencies | currencyList | AI Gateway billing display, multi-currency decimal places and rounding formatting |
Endpoint List
| Method + Path | Scope | Idempotency | Purpose |
|---|---|---|---|
GET /locale | locale.read | Yes | Get the current requester's geographic and localization information |
GET /locale/codes | locale.read | Yes | List all supported Locale codes |
GET /locale/continents | locale.read | Yes | List all continent codes and names |
GET /locale/countries | locale.read | Yes | List all country/region codes and names |
GET /locale/countries/eu | locale.read | Yes | List current European Union (EU) member states |
GET /locale/countries/phones | locale.read | Yes | List the mapping table of country telephone dialing codes and countries |
GET /locale/currencies | locale.read | Yes | List all ISO 4217 currencies and formatting rules |
GET /locale/languages | locale.read | Yes | List all ISO 639-1 languages and native names |
Endpoint details
Multilingual Dictionary Switching and Caching Practices
Passing the localization header: all
/v1/locale/*endpoints recognize theX-Appwrite-Localerequest header. For example, whenX-Appwrite-Locale: zh-CNis passed,GET /v1/locale/countriesreturns thenameofCNas the localized Chinese name; if an unknown language code is passed, it gracefully falls back to the default English.Fallback behavior for private networks and unknown IPs: when calling
GET /v1/localewithin a private deployment or container internal network, if the source IP belongs to an RFC 1918 private network range (such as10.0.0.0/8,172.16.0.0/12,192.168.0.0/16) and no external GeoIP passthrough header is configured, the GeoIP library cannot match a public network record;countryCode,continentCode,currencyin the response will return empty strings"",euwill returnfalse, and no 4xx/5xx error will be thrown.Dictionary caching recommendation: except for
GET /v1/locale, which depends on the real-time request IP, the data returned by the remaining 7 dictionary endpoints is only updated with platform version upgrades; server-side business can cache it in-process for 24 hours by the(endpoint, locale_header)dimension.
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:
| Field | Type | Description |
|---|---|---|
ip | string | Client IP address |
countryCode | string | ISO 3166-1 two-letter country code (such as CN, US); "" when the IP is an internal unknown IP |
country | string | Country name (supports X-Appwrite-Locale localization) |
continentCode | string | Continent code: AF / AN / AS / EU / NA / OC / SA |
continent | string | Continent name (supports localization) |
eu | boolean | Whether it is an EU member state |
currency | string | ISO 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[]):
| Field | Type | Description |
|---|---|---|
symbol | string | Internationally universal currency symbol (such as $, ¥) |
name | string | Currency singular name (such as Chinese yuan) |
symbolNative | string | Local currency symbol |
decimalDigits | integer | Standard number of decimal places (e.g., CNY is 2, JPY is 0) |
rounding | number | Minimum rounding step (usually 0) |
code | string | ISO 4217 three-letter uppercase code (such as CNY, USD) |
namePlural | string | Currency 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 Code | Error Type (type) | Trigger Cause | Troubleshooting Recommendation |
|---|---|---|---|
401 Unauthorized | general_access_forbidden | Missing X-Appwrite-Project or the project ID does not exist | Check the project ID in the request headers (such as enterprise-ai-hub-210) |
401 Unauthorized | general_unauthorized_scope | The API Key has not been granted the locale.read permission | Enable locale.read in the Console API Key settings |
429 Too Many Requests | general_rate_limit_exceeded | High-frequency polling of static dictionaries triggers instance rate limiting | Dictionary lists (countries/currencies/phones/languages) should be cached in application memory rather than fetched in real time on every user request |
Lists return the
*Listmodel (total+ a specific array field);queries[]pagination filtering is not supported — the full set is returned in a single response.Static data is updated with platform versions; it is recommended that clients use the version number for local cache invalidation.
Correspondence with the Server SDK
Server SDK service.method | HTTP Method and Path | Returned Model |
|---|---|---|
Locale.get | GET /v1/locale | locale |
Locale.listCodes | GET /v1/locale/codes | localeCodeList |
Locale.listContinents | GET /v1/locale/continents | continentList |
Locale.listCountries | GET /v1/locale/countries | countryList |
Locale.listCountriesEU | GET /v1/locale/countries/eu | countryList |
Locale.listCountriesPhones | GET /v1/locale/countries/phones | phoneList |
Locale.listCurrencies | GET /v1/locale/currencies | currencyList |
Locale.listLanguages | GET /v1/locale/languages | languageList |