Get Details for an Autocomplete Suggestion
Get detailed information about an autocomplete suggestion
- Overview
- Required Parameters
- Optional Parameters
- Localities Details example
- Responses
- Usage limits
- Samples
Overview
Woosmap Localities details endpoint provides details for an autocomplete suggestion (using the
suggestion’s public_id).
A Woosmap Localities details request is an HTTP URL of the following form:
https://api.woosmap.com/localities/details?key={PUBLIC_API_KEY}&public_id={LOCALITES_PUBLIC_ID}
Autocomplete and details on address and postal_code may be subject to specific product activation. Please see coverage page for more details.
The Details endpoint of Localities API is subject to a specific pricing. Request costs vary according to the data you request details for. Visit our pricing page or get in touch with your Customer Care contact to learn how to estimate you license accordingly.
Required Parameters
Certain parameters are required to initiate a Details request. As is standard in URLs, all parameters are separated
using the ampersand(&) character. Few parameters are mandatory like the public_id which must be present in addition to
a Woosmap API key.
https://api.woosmap.com/localities/details?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&key={PUBLIC_API_KEY}
public_id
The identifier of the autocomplete suggestion. (public_id can be retrieved in
the Autocomplete response).
key
Your project’s API key. This key identifies your Woosmap Project for security and quota management purposes. Public keys are designed to be used client side, where every request contain a referer. Alternatively, you can use the parameter private_key for server side requests.
Reminder: To use the Localities API, your Public API key (parameter key) has to be authorized for the domains and/or IPs (referer) where you make the call. More on securing API keys here.
You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.
private_key
Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server side, no referer checking associated with those keys.
You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.
Optional Parameters
language
The language code, indicating in which language the results should be returned, if possible. If no language parameter is supplied, first Accept-Language of the browser will be used. If neither the provided language or the Accept-Language are known, the Localities service uses the international default language (English). Depending on requested language, only parts of the address components might be translated.
fields
You can use this parameter to limit the fields returned in the response. This parameter can be any combination of geometry, address_components or shape (defaults to geometry|address_components).
If set, it will limit the content of responses to the specified fields.
For example, fields=geometry will limit the response to the geometry part and you won’t get the address_components, which can help with cost optimization in certain countries.
fields=shape will include the shape for most provided types except addresses: country, admin_level, postal_code and locality.
cc_format
To specify the country code format returned in the response. Default is alpha2.
Available cc_format values are alpha2 or alpha3.
page
In a few cases, a postal code details may contain addresses (UK postal codes). The address list is paginated.
In that case, you can navigate in the address list thanks to the page and addresses_per_page parameters.
Notice: as all the addresses are now automatically returned in the response, the page parameter is deprecated and has been turned off on December 31, 2021.
addresses_per_page
In a few cases, a postal code details may contain addresses (UK postal codes). The address list is paginated.
In that case, you can navigate in the address list thanks to the addresses_per_page and page parameters.
Notice: as all the addresses are now automatically returned in the response, the addresses_per_page parameter is deprecated and has been turned off on December 31, 2021.
Localities Details example
The following example requests the details of a locality by specifying the required public_id:
https://api.woosmap.com/localities/details
?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D
&key=YOUR_PUBLIC_API_KEY
curl -L -X GET 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
var requestOptions = {
method: 'GET',
redirect: 'follow'
};
fetch("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
var axios = require('axios');
var config = {
method: 'get',
url: 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY',
headers: {
'Referer': 'http://localhost'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
import requests
url = "https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY"
payload={}
headers = {
'Referer': 'http://localhost'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY")
.method("GET", body)
.addHeader("Referer", "http://localhost")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "net/http"
url = URI("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"
response = https.request(request)
puts response.read_body
Responses
To retrieve detailed data, including geometry and address_components, a Details request must be performed passing in
the public_id of the selected address.
Localities Details API endpoint provides a JSON response containing one root element, result which contains the serialized address result.
A result contains the following fields:
public_id
The public_id of the result (return by
the Autocomplete response)
formatted_address
Contains the text description of the proposal to be used as suggestion in a drop-down list if needed.
types
Contains the type of the result. See the list of existing types
administrative_area_label
This field is only available for admin_level suggestions. It provides the local english name of the administration level (“department” for France or “federal_state” for Germany).
geometry
The location of the result, in latitude and longitude, as well as its viewport when applicable and its shape when requested.
Accuracy is also provided when appropriate (mostly for addresses).
When provided, accuracy values can be ROOFTOP, POSTAl_CODE or DISTRICT. If POSTAl_CODE or DISTRICT accuracy are provided, be aware that location accuarcy may not be suitable for some use cases.
address_components
Detailed fields of the result (long and short). Available fields depend on the returned type.
Corresponding types/fields table:
| name | administrative_area_level_0 | administrative_area_level_1 | state | administrative_area_level_2 | county | postal_codes | postal_town | locality | district | iata_code | route | street_number | premise | organisation | post_box | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| address | • | • | • | • | • | • | • | • | • | • | • | • | • | • | ||
| locality | • | • | • | • | • | IT and FR only | • | |||||||||
| postal_code | • | • | • | • | • | |||||||||||
| admin_level | • | • | • | |||||||||||||
| country | • | |||||||||||||||
| airport | • | • | • | |||||||||||||
| train_station | • | • | • | • | • | |||||||||||
| metro_station | • | • | • | • | • | |||||||||||
| shopping | • | • | • | • | • | |||||||||||
| museum | • | • | • | • | • | |||||||||||
| tourist_attraction | • | • | • | • | • | |||||||||||
| amusement_park | • | • | • | • | • | |||||||||||
| art_gallery | • | • | • | • | • | |||||||||||
| zoo | • | • | • | • | • |
addresses
This field is only available for UK postal codes that bear addresses.
It contains an array of addresses, with their description and public_id.
The address details can be retrieved passing the public_id to the /details endpoint.
The address list is paginated and you can find the following structure in the response to know where you are in the list.
"pagination": {
"page": 1,
"page_count": 1,
"addresses_per_page": 19,
"address_count": 19
},
The pagination part of the response is deprecated as all the addresses are now automatically returned in the response. It will be turned off at some point. From now on, the pagination will systematically return page=1, pages_count=1, addresses_per_page=[total addresses count] and address_count=[total addresses count].
status
This optional field is only specified for UK not yet built addresses.
Only one value yet, not_yet_built for addresses referenced as not yet built addresses by Royal Mail.
Example of a UK postal code details (with addresses)
{
"result":
{
"public_id": "QaCU+fBtigK65ztSrqHqUoUDwZw=",
"types": ["postal_code"],
"formatted_address": "SW1A 0AA, City of London",
"geometry": { "location": { "lat": 51.49984, "lng": -0.124663 } },
"name": "SW1A 0AA",
"address_components":
[
{
"short_name": "GB",
"long_name": "United Kingdom",
"types": ["country", "administrative_area_level_0"],
},
{
"short_name": "City of London",
"long_name": "City of London",
"types": ["administrative_area_level_1"],
},
],
"addresses":
{
"pagination":
{
"page": 1,
"page_count": 1,
"addresses_per_page": 1,
"address_count": 1,
},
"list":
[
{
"public_id": "TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ==",
"description": "House Of Commons, Houses Of Parliament, London, SW1A 0AA",
},
],
},
},
}
Example of an address details
{
"result":
{
"public_id": "TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ==",
"types": ["address"],
"formatted_address": "House Of Commons, Houses Of Parliament, London, SW1A 0AA",
"geometry":
{
"location": { "lat": 51.4998415, "lng": -0.1246375 },
"accuracy": "ROOFTOP",
},
"address_components":
[
{
"short_name": "GB",
"long_name": "United Kingdom",
"types": ["country", "administrative_area_level_0"],
},
{
"short_name": "City of London",
"long_name": "City of London",
"types": ["administrative_area_level_1"],
},
{
"short_name": "City of London",
"long_name": "City of London",
"types": ["county"],
},
{
"short_name": "London SW",
"long_name": "London SW",
"types": ["district"],
},
{
"short_name": "London",
"long_name": "London",
"types": ["locality"],
},
{
"short_name": "SW1A 0AA",
"long_name": "SW1A 0AA",
"types": ["postal_codes"],
},
{
"short_name": "Houses Of Parliament",
"long_name": "Houses Of Parliament",
"types": ["premise"],
},
{
"short_name": "House Of Commons",
"long_name": "House Of Commons",
"types": ["organisation"],
},
],
},
}
Usage limits
The following usage limits are in place for the Localities API on the autocomplete and details endpoint combined:
- Maximum of 50 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
