Location Translations

Locations services has the capability of storing location(s) data in multiple translations and searching for location(s) data in a specific translations.

Location Services has the convention of default translations and explicitly provided translations.

Default Translations

Location data that should be considered as default translation must be provided as part of the actual location and it is not required to be explicitly provided with the translations.

This translation data will be returned on search queries whenever no translation exists in the requested language.

Storing Translations

Translations for a location can be provided (in the translations field) during create or update operation as part of location data.

Translations field:

Name Mandatory Type Length Example
translations false map<string,translation>(*1) (*2) -
  1. Key for the map must be ISO 639-1 two-letter code in lowercase
  2. Each location can have at maximum 10 translations


Location Data
Name Mandatory Type Length Example
storeName true string 128 Haywards Heath
supplementaryName false string 128 Provider Store #10
description false string 512 Nice Store
Location Address Data

Location address translation data can be provided either in structured address or unstructured address data format. Providing both will cause the request to be rejected.

Additionally location address translation data must have the same structure as the address data provided as part of the location. Any request violating this will be rejected.

Unstructured Address Data
Name Mandatory Type Length Example
address true string 256 4 Palmerston House; Commercial Square
city true string 64 London
Structured Address Data
Name Mandatory Type Length Example
structuredAddress.street true string 256 Commercial Square
structuredAddress.buildingName false string 64 Palmerston House
structuredAddress.houseNumber false string 64 4
structuredAddress.city true string 64 London
structuredAddress.district false string 64 Greater London
structuredAddress.province false string 64 Hogwarts

Example Request Body

This is an example location object which has data in French and Flemish. French is the default translation as it is provided in the location, but not in the translations.

  "storeId": "TST001",
  "structuredAddress": {
    "street": "BOULEVARD DU JUBILÉ",
    "houseNumber": "202",
    "postCode": "1080",
    "countryCode": "BEL"
  "translations": {
    "nl": {
      "storeName": "DAGBL L ESCAUT MOLENBEEK",
      "structuredAddress": {
        "street": "JUBELFEESTLAAN",
        "houseNumber": "202",
        "city": "SINT-JANS-MOLENBEEK"
  "latitude": 50.852452,
  "longitude": 4.330518,
  "telephoneNumber": "+321908237494",
  "email": "mkstore@askjeeves.com",
  "tags": ["a", "b", "c" ],
  "locationProvider": {
    "id": "f65e6dea-1d3c-4734-8306-095da0955f48"

Reading Translations

Location services API's are supporting either retrival of location(s) with all translations data or location data in a spefic translation.

Search/Retrieve Location Data With All Translations

The following table details the calls that return all translations:

Endpoint Parameters Description Reference
/locations/{id} - Retrieve location Reading Location Data
/locations location_provider_id&countrycode Retrieve locations for providers Generic search
/locations consolidator_id&countrycode Retrieve locations for consolidator Generic search
/locationProviders/{providerId}/locations - Retrieve locations for providers -

Search/Retrieve Location Data In A Specific Translation

In order to retrieve/search location(s) in a specific translation the parameter language=<ISO 639-1 two-letter code> must be provided in the request.

The translation in which the location(s) data is returned depends on whether language parameter is passed and also on whether a translation in the requested language exists. The following table summarises possible scenarios.

language parameter provided Translation in specified language exists Translation
Yes Yes In provided language

The following table details the calls that return location(s) in requested language:

Endpoint Description Reference
/locations Generic location search Generic search

results matching ""

    No results matching ""