Get Details for an Autocomplete Suggestion
How to build your Localities API Details requests
- Introduction
- Required Parameters
- Optional Parameters
- Address Details Response
- Postal Code Details Response
- Samples
Introduction
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.
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}
On the specific territory of United Kingdom, Localities autocomplete request can return the additional
attribute has_addresses for a postal code, which indicates if a postal code bears addresses. When has_addresses
is true, it is possible to display a list of the available addresses by requesting details with the
Localities public_id. To get the details of an address you will need to request again /details endpoint passing in
the dedicated address public_id.
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 contains a referer.
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.
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.
Optional Parameters
fields
You can use this parameter to limit the returning fields (by default, all fields are return).
Available fields are (geometry) (fields should be separated by a ,). By using this parameter you will limit content
of responses to the geometry part. No address component will be returned.
Address Details Response
To retrieve detailed data, including geography and structured address, a Details request must be performed passing in
the public_id of the selected address.
It is possible to narrow down the response of the API to only geographic coordinates, stripping away
the address_components by adding the parameter fields=geometry.
https://api.woosmap.com/localities/details?key={PUBLIC_API_KEY}&public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=
The API responses contains attributes as follows:
{
"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"
}
]
}
}
result
A result contains the following fields:
formatted_address
Contains the text description of the proposal to be used as suggestion in drop down list if needed.
types
Contains the type of result. Value is address.
public_id
The public_id of the result (return by
the Autocomplete response
geometry
The location of the result, in latitude and logitude. Accuracy is also provided.
Postal Code Details Response
Only available on UK territory.
https://api.woosmap.com/localities/details?key={PUBLIC_API_KEY}&public_id=QaCU+fBtigK65ztSrqHqUoUDw
Localities Details provides a JSON response containing one root element, result which contains an array of
addresses, with the associated description contained into the postal code. The address list is paginated.
{
"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="
}
]
}
}
}
result
A result contains the following fields:
formatted_address
Contains the text description of the proposal to be used as suggestion in drop down list if needed.
types
Contains the type of result. Value is postal_code.
public_id
The public_id of the result (return by
the Autocomplete response
address_components
Description of all the components of the address (long and short). Those fields are provided when no fields parameter
is set in the request.
geometry
The location of the result, in latitude and logitude.
Samples
Following are two samples showcasing the autocomplete and details requests to return address suggestions, or a list of addresses beared by a postal code (only available in the UK).