Skip to main content
The API can return a place name in the language your user expects. You do not need to download and maintain a large translation file in your app. Use locale when you need one display name. Use include_translations=true only when you need every available translation.
Available on Professional and Business plans. Compare plans to add localized names to your API key.

​
Get one localized name

Add locale to a country, state, city, region, subregion, fuzzy search, autocomplete, or nearby search request.
Each result keeps its normal English name and stable id. The API adds:
​
string
The best name for the requested language.
​
string
The language that supplied the value, or native/en when the API used a fallback.

​
Fallback order

When a translation is missing, the API checks these names in order:
  1. The exact locale, such as pt-BR
  2. The base language, such as pt
  3. The place’s native name
  4. The English name
The API never replaces name or id, so your stored references remain stable.

​
Get every translation

Add include_translations=true when your app needs the complete stored value.
The translations field is a JSON string. Parse it before reading a language value:
Translations are hidden by default because returning every language for every row makes large responses much bigger.
If you also use fields, list the fields you want. For example, fields=name,translations asks for the English name and the raw translations value.

​
Search using translated names

Fuzzy Search and Autocomplete can find a place from a stored translation when the query has at least 3 characters. For example, the Japanese query ムンバイ can find Mumbai.
Autocomplete reports matched_field: "translation" for a translation-only match. A fuzzy-search translation match can have a low match_score because that score still compares the query with the English and native names. locale controls the name returned for display. It does not limit search to one language; translated search checks all stored translations. Nearby Search also accepts locale and include_translations, but it finds places from coordinates rather than translated text.

​
Validation and plan behavior

  • Use a locale such as fr, hi, pt-BR, or zh-CN. Invalid values return 400.
  • include_translations accepts only true or false. Other values return 400.
  • On regular geography routes, a lower plan still receives the normal response, without localized_name, matched_locale, or translations.
  • Fuzzy search, autocomplete, and nearby search have their own plan requirements and may return 403 before running the search.

​
Start using localized names

Choose Professional or Business when you are ready to serve translated place names without hosting the translation data yourself.

Compare API plans

See the request limits and features included with each plan.

Autocomplete

Build a search box with ready-to-display localized labels.