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:
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:
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[]):
| 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:
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 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 |