Autocomplete API
Warning
The API described in this page and, by consequence, this documentation, are in beta and may be subject to changes.
This page documents the public API used to create the autocomplete object. For the authorization mechanism refer to Public APIs Authorization.
General overview
There is a single API to call for obtaining the data needed to fetch the autocomplete predictions. The API needs to be called in POST, the URL is
https://{api-url}.retailtune.com/geocode
and the HTTP request must have a body with the following form:
{
"text": <string>,
"type": "autocomplete",
"lat": <optional string>,
"lon": <optional string>,
"countries": <optional array of string>,
"layers": <optional array of string>,
"lang": <optional string>
}
When making the actual HTTP request, {api-url} in the URL can either be "test.api.retailtune.com" for the development environment or "api.retailtune.com" for the production environment. The production environment is advised for its stability.
Request body - mandatory fields
The only two fileds of the body object that are mandatory are "text" and "type". The former is a string parameter that
embodies the user search, the latter is also a string parameter that, for the autocomplete integration's sake, must have the
literal "autocomplete" string value.
Any request that fails to adhere to these requirements will be rejected.
Request body - optional fields
"lang" field is a string representing the language of the predictions in the API response.
The following fields are used to filter the predictions in the API response:
"lat" and "lon" fields are used to focus the search for predictions around the given latitude and longitude coordinates
pair, expressed as two strings. This is useful when you know in advance that your user only wants results around a specific point of interest.
When used, they must be provided both or not at all.
"countries" is an array of strings which form is defined by the ISO 3166-1 Alpha-2 standard. Its purspose is to isolate the search for predictions only inside specific countries, represented by their country codes.
"layers" is an array of strings used to filter the predictions in the API response by category. Providing more than one layer filter the API results in a disjunctive way, including in the response all the predictions that match at least one of the given layers. Below the list of the available layers:
| Layer | Description |
|---|---|
| address | Addresses represent any place with a physical address (housenumber + street) assigned by a governing body |
| county | Counties generally represent the second highest level of subdivision within a country. Note that this term has different mening in different cultures |
| country | Countries represents sovereign or autonomous states. Countries always have an unique ISO 3166-1 code |
| dependency | A dependency is a territory of a larger entity generally not considered to be autonomous. For example, Puerto Rico is a dependency of the United States, whereas Greenland is an independent Country (and part of the empire of Denmark) |
| locality | Locality records refer to any populated place and is the most common way to represent cities across the world |
| region | Regions are generally the highest level of subdivision within a country. These include states in the United States of America and Australia, provinces in Canada and China, departments in France, etc. |
| street | Streets include any named public or private areas used for travel. This includes highways & roads for vehicles plus some named pathways for bicycle or pedestrian traffic |
| venue | represents any place with a name, either official or unofficial. Venues include all point of interest such as restaurants, stores, buildings, transit stops and natural parks |
API Response - request unsuccessful
The API response will be a JSON object with a status field set to "error" and a brief explanatory message
API Response - request successful
The API response will be a JSON object with a status field set to "ok" and a list of Predictions:
{
"item": <string>,
"country": <string>,
"address": <string>,
"city": <string>,
"provinceCode": <string>,
"description": <string>,
"lon": <string>,
"layer": <string>,
"country_code": <string>,
"province": <string>,
"post_code": <string>,
"id": <string>,
"lat": <string>
}
Here the "id" field is an internal identifier, "item" is a text describing the prediction, "lat" and "lon" are the coordinates that identify the object position in space, while "layer" is the prediction category. "country" is the name of the country, "countr_code" is the code of the country, "province" is the name of the province, "provinceCode" is the code of the province, "city" is the city, "address" is the address and "post_code" is the zipcode.
Request examples
A POST HTTP request to "https://api.retailtune.com/geocode" with the following body:
{
"type":"autocomplete",
"text":"Par",
"lang":"en",
"countries": ["it", "fr"],
"layers": ["locality"]
}
will try to fetch all the predictions for the user search "Par" in english language that matches the layer=locality and country=IT,FR.
The API response is the following:
{
"items": [
{
"country": "France",
"country_code": "FR",
"item": "Paris, Ile-de-France, France",
"address": "Paris",
"description": "Paris, France",
"lon": "2.3483915",
"id": "71525",
"lat": "48.8534951",
"layer": "locality"
},
{
"country": "Italy",
"country_code": "IT",
"item": "Parma, Parma, Emilia-Romagna, Italy",
"address": "Parma",
"province": "Parma",
"provinceCode": "PR",
"description": "Parma, Parma, Italy",
"lon": "10.3280833",
"id": "43452",
"lat": "44.8013678",
"layer": "locality"
},
{
"country": "Italy",
"country_code": "IT",
"item": "Parre, Bergamo, Lombardy, 24020, Italy",
"address": "Parre",
"province": "Bergamo",
"provinceCode": "BG",
"post_code": "24020",
"description": "Parre, Bergamo, Italy",
"lon": "9.890855",
"id": "46390",
"lat": "45.874587",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Parly, Yonne, Bourgogne-Franche-Comté, 89240, France",
"address": "Parly",
"province": "Yonne",
"provinceCode": "Yonne",
"post_code": "89240",
"description": "Parly, Yonne, France",
"lon": "3.3472",
"id": "1804088",
"lat": "47.765",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Paron, Yonne, Bourgogne-Franche-Comté, 89100, France",
"address": "Paron",
"province": "Yonne",
"provinceCode": "Yonne",
"post_code": "89100",
"description": "Paron, Yonne, France",
"lon": "3.2470551",
"id": "945544",
"lat": "48.1785718",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Parux, Meurthe-et-Moselle, Grand Est, 54480, France",
"address": "Parux",
"province": "Meurthe-et-Moselle",
"provinceCode": "Meurthe-et-Moselle",
"post_code": "54480",
"description": "Parux, Meurthe-et-Moselle, France",
"lon": "6.9221",
"id": "2845807",
"lat": "48.5392",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Paroy, Seine-et-Marne, Ile-de-France, 77520, France",
"address": "Paroy",
"province": "Seine-et-Marne",
"provinceCode": "Seine-et-Marne",
"post_code": "77520",
"description": "Paroy, Seine-et-Marne, France",
"lon": "3.1993644",
"id": "1400884",
"lat": "48.4793547",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Parcé, Ille-et-Vilaine, Brittany, 35210, France",
"address": "Parcé",
"province": "Ille-et-Vilaine",
"provinceCode": "Ille-et-Vilaine",
"post_code": "35210",
"description": "Parcé, Ille-et-Vilaine, France",
"lon": "-1.2008152",
"id": "142952",
"lat": "48.2728516",
"layer": "locality"
},
{
"country": "Italy",
"country_code": "IT",
"item": "Parella, Torino, Piedmont, Italy",
"address": "Parella",
"province": "Torino",
"provinceCode": "TO",
"description": "Parella, Torino, Italy",
"lon": "7.793217",
"id": "44959",
"lat": "45.430657",
"layer": "locality"
},
{
"country": "Italy",
"country_code": "IT",
"item": "Paroldo, Cuneo, Piedmont, 12070, Italy",
"address": "Paroldo",
"province": "Cuneo",
"provinceCode": "CN",
"post_code": "12070",
"description": "Paroldo, Cuneo, Italy",
"lon": "8.072442",
"id": "43146",
"lat": "44.432036",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Pargnan, Aisne, Upper France, 02160, France",
"address": "Pargnan",
"province": "Aisne",
"provinceCode": "Aisne",
"post_code": "02160",
"description": "Pargnan, Aisne, France",
"lon": "3.6914712",
"id": "447167",
"lat": "49.4003214",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Paroy, Doubs, Bourgogne-Franche-Comté, 25440, France",
"address": "Paroy",
"province": "Doubs",
"provinceCode": "Doubs",
"post_code": "25440",
"description": "Paroy, Doubs, France",
"lon": "5.8808084",
"id": "453059",
"lat": "47.043809",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Parnes, Oise, Upper France, 60240, France",
"address": "Parnes",
"province": "Oise",
"provinceCode": "Oise",
"post_code": "60240",
"description": "Parnes, Oise, France",
"lon": "1.7390101",
"id": "487287",
"lat": "49.2036278",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Pargny, Somme, Upper France, 80190, France",
"address": "Pargny",
"province": "Somme",
"provinceCode": "Somme",
"post_code": "80190",
"description": "Pargny, Somme, France",
"lon": "2.9517092",
"id": "3359869",
"lat": "49.814451",
"layer": "locality"
},
{
"country": "France",
"country_code": "FR",
"item": "Le Parcq, Pas-de-Calais, Upper France, 62770, France",
"address": "Le Parcq",
"province": "Pas-de-Calais",
"provinceCode": "Pas-de-Calais",
"post_code": "62770",
"description": "Le Parcq, Pas-de-Calais, France",
"lon": "2.1006927",
"id": "2917379",
"lat": "50.3787852",
"layer": "locality"
}
],
"status": "ok"
}
A POST HTTP request to "https://api.retailtune.com/geocode" with the following body:
{
"type":"autocomplete",
"text":"viale Mentana 43 Parma",
"layers": ["address", "street", "locality"]
}
will try to fetch all the predictions for the user search "viale Mentana 43 Parma" in the broswer language that matches the layer=address,street,locality.
The API response is the following:
{
"items": [
{
"country": "Italy",
"item": "Viale Mentana, Parma Centro, Parma, Parma, Emilia-Romagna, 43121, Italy",
"address": "Viale Mentana",
"city": "Parma",
"provinceCode": "PR",
"description": "Viale Mentana, Parma, Parma, Italy",
"lon": "10.3324435",
"layer": "street",
"country_code": "IT",
"province": "Parma",
"post_code": "43121",
"id": "1187342699",
"lat": "44.8070759"
},
{
"country": "Italy",
"item": "Viale Mentana, Viale Mentana, Parma Centro, Parma, Parma, Emilia-Romagna, 43121, Italy",
"address": "Viale Mentana",
"city": "Parma",
"provinceCode": "PR",
"description": "Viale Mentana, Parma, Parma, Italy",
"lon": "10.3332826",
"layer": "street",
"country_code": "IT",
"province": "Parma",
"post_code": "43121",
"id": "7194284658",
"lat": "44.8068886"
},
{
"country": "Italy",
"item": "Viale Mentana Barriera Garibaldi, Viale Mentana, Parma Centro, Parma, Parma, Emilia-Romagna, 43121, Italy",
"address": "Viale Mentana Barriera Garibaldi",
"city": "Parma",
"provinceCode": "PR",
"description": "Viale Mentana Barriera Garibaldi, Parma, Parma, Italy",
"lon": "10.3305134",
"layer": "street",
"country_code": "IT",
"province": "Parma",
"post_code": "43121",
"id": "459451902",
"lat": "44.8074668"
}
],
"status": "ok"
}