Get Details for an Autocomplete Suggestion
Get detailed information about an autocomplete suggestion
Overview
Woosmap Localities details endpoint provides details of 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 which is different from an autocomplete request. 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 purposes of security and quota management. 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
fields
You can use this parameter to limit the fields returned in the response (by default, all fields are returned).
This parameter accepts one value: geometry. 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.
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 be 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.
Response
To retrieve detailed data, including geometry and address_components, a Details request must be performed passing in
the public_id of the selected address.
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
geometry
The location of the result, in latitude and longitude. Accuracy is also provided when appropriate (mostly for addresses).
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 | administrative_area_level_2 | postal_codes | postal_town | locality | iata_code | route | street_number | premise | organisation | post_box | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| address | • | • | • | • | • | • | • | • | • | • | • | ||
| locality | • | • | • | • | • | • | |||||||
| 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].
Example of a UK postal code details (with addresses)
{
"result": {
"formatted_address": "SW1A 0AA, City of London",
"types": [
"postal_code"
],
"public_id": "QaCU+fBtigK65ztSrqHqUoUDwZw=",
"name": "SW1A 0AA",
"geometry": {
"location": {
"lat": 51.49984,
"lng": -0.124663
}
},
"address_components": [
{
"types": [
"country",
"administrative_area_level_0"
],
"long_name": "United Kingdom",
"short_name": "GB"
},
{
"types": [
"administrative_area_level_1"
],
"long_name": "City of London",
"short_name": "City of London"
}
],
"addresses": {
"pagination": {
"page": 1,
"page_count": 1,
"addresses_per_page": 20,
"address_count": 5
},
"list": [
{
"description": "Postmasters Redirection Service, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
"public_id": "DuxKg3/i5t1AuSt1qvwaiSgd+gI="
},
{
"description": "The Speakers House, 1 Parliament Square, London, SW1A 0AA",
"public_id": "J9y6c0VHd8L5djgVKAmUZir1D74="
},
{
"description": "Speakers Housekeepers Apartment, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
"public_id": "K13iP+XIfYK2h+6NFqVVX2q0NQ8="
},
{
"description": "House Of Commons, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
"public_id": "MVZWBfGZQnAQn9JtE9CJZjgeB4Q="
},
{
"description": "Lord Chancellors Residence, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
"public_id": "i5WqCPd+qTTnZtiXnKzV8KoIpT8="
}
]
}
}
}
Example of an address details
{
"result": {
"formatted_address": "House Of Commons, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
"types": [
"address"
],
"public_id": "MVZWBfGZQnAQn9JtE9CJZjgeB4Q=",
"geometry": {
"location": {
"lat": 51.49984,
"lng": -0.1246375
},
"accuracy": "ROOFTOP"
},
"address_components": [
{
"types": [
"country",
"administrative_area_level_0"
],
"long_name": "United Kingdom",
"short_name": "GB"
},
{
"types": [
"administrative_area_level_1"
],
"long_name": "City of London",
"short_name": "City of London"
},
{
"types": [
"premise"
],
"long_name": "House Of Commons Palace Of Westminster",
"short_name": "House Of Commons Palace Of Westminster"
},
{
"types": [
"locality"
],
"long_name": "London",
"short_name": "London"
},
{
"types": [
"postal_codes"
],
"long_name": "SW1A 0AA",
"short_name": "SW1A 0AA"
},
{
"types": [
"organisation"
],
"long_name": "House Of Commons",
"short_name": "House Of Commons"
},
{
"types": [
"route"
],
"long_name": "Parliament Square",
"short_name": "Parliament Square"
}
]
}
}
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)