Autocomplete Requests
How to build your Localities API autocomplete requests
The Localities Autocomplete provides worldwide suggestions for a for text-based geographic searches.
It can match on full words as well as substrings. You can therefore send queries as the user types, to provide on-the-fly city names, postal codes or suburb name suggestions.
The returned suggestions are designed to be presented to the user to aid them in selecting their desired location.
Overview
A Woosmap Localities /autocomplete request is an HTTP URL of the following form:
https://api.woosmap.com/localities/autocomplete/?parameters
Required Parameters
Certain parameters are required to initiate a Localities request. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.
https://api.woosmap.com/localities/autocomplete/?input=london&key={PUBLIC_API_KEY}
input
The text string on which to search. Localities API will return candidate matches based on this string and order results based on their perceived relevance.
key
Your project’s API key. This key identifies your Woosmap Project for purposes of quota management.
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.
Optional parameters
.../localities/autocomplete/?input=lond&key=[YOUR_API_KEY]&types=postal_code&components=country:gb&language=en&data=advanced
types
The types of suggestion to return. Several types are available, see the list below:
locality |
includes locality names (from city to village) and suburbs |
postal_code |
publicly-used postal codes around the world |
address |
addresses (only available for UK and France) |
admin_level |
most commonly used administrative areas |
country |
countries as whole point of interest |
airport |
includes all medium sized to international sized airports |
train_station |
includes all train stations |
metro_station |
includes all metro stations |
shopping |
includes shopping malls (or “shopping centers”) - may include private retail brands |
museum |
includes museums |
tourist_attraction |
includes tourist attractions like the Eiffel tower |
amusement_park |
includes amusement parks like Disneyland Paris |
art_gallery |
includes art galleries |
zoo |
includes zoos |
Not specifying any type will only query locality and postal_code. Multiple types can be passed using the pipe character (|) as a separator.
For example: types=locality|airport|admin_level.
The information returned on an address suggestion contain only a “single-line” description. A request to the Details endpoint of the API must be performed to retrieve the location (geographic coordinates) and the address components (street address, zipcode, city..).
components
A grouping of places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible country code. For example: components=country:fr would restrict your results to places within France and components=country:fr-fr returns locations only in Metropolitan France. Multiple countries must be passed as multiple country:XX filters, with the pipe character (|) as a separator. For example: components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to city names or postal codes within the United Kingdom, France, Belgium, Spain and Italy.
language
The language code, indicating in which language the results should be returned, if possible. Searches are also biased to the selected language; results in the selected language may be given a higher ranking. If language is not supplied, the Localities service will use the default language of each country. No language necessary for postal_code request.
data
Two values for this parameter: standard or advanced. By default, if the parameter is not defined, value is set as standard. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. A dedicated option subject to specific billing on your license is needed to use this parameter. Please contact us if you are interested in using this parameter and you do not have subscribed the proper option yet.
extended
If set, this parameter allows a refined search over locality names that bears the same postal code. By triggering this parameter, integrators will benefit from a search spectrum on the locality type that includes postal codes. To avoid confusion, it is recommended not to activate this parameter along with the postal_code type which could lead to duplicate locations. Also, the default description returned by the API changes to name (postal code), admin_1, admin_0. It is only available for France and Italy.
Localities Suggestions Responses
Localities autocomplete provides a JSON response containing one root element, localities which contains an array of up to 5 suggestions sorted from most to least relevant.
{
"localities": [
{
"description": "20121, Milano, Italy",
"name": "20121",
"admin_0": "Italy",
"admin_1": "Milano",
"postal_town": "Milano",
"type": "postal_code",
"public_id": "MkvnYy6K6oVGqeqfWJGO/6eCgqo=",
"viewpoint": {
"bounds": {
"east": 9.205397,
"south": 45.463764,
"north": 45.482056,
"west": 9.169627
}
},
"matched_substrings": {
"name": [{"offset": 0, "length": 5}],
"admin_1": [{"offset": 0, "length": 3}],
"description": [{"offset": 0, "length": 5}, {"offset": 7, "length": 3}],
"postal_town": [{"offset": 0, "length": 3}]
},
"location": {
"lat": 45.472416,
"lng": 9.18711
}
},
{...},
{...},
{...}
]
}
Suggestions Fields
Suggestion results can contain the following fields:
name
contains the human-readable name for the returned result. For postal_code results, this is directly the postal code value. For locality results, name in the specified language is returns. If no language is specified, default name (country local language) is returned.
location
contains latitude and longitude of the searched city or postal code. For postal_code results, coordinates represent the center of the area. For locality results, coordinates represent the center of the populated area.
public_id
contains a unique ID for each suggestion. Please use this ID if you need to give us feedbacks on results. This ID is also required to perform Localities Details request.
type
contains the type of the suggestion, either locality, postal_code, admin_level, airport, train_station, metro_station, shopping, museum, zoo, amusement_park, art_gallery, tourist_attraction or country.
admin_0
contains the country name.
admin_1
contains the administrative level including the suggestion.
admin_2
for small locality type points of interests (suburbs, neighborhoods, villages), contains the municipality it belongs to.
viewpoint
contains geographic bounds (north, south, east, west) to help center a map on a suggestion’s selection by the user.
description
is the concatenation of name, admin_1, admin_0 to be used as suggestion in drop down list if needed. The description can vary depending on the type requested.
postal_codes
contains an array of known postal codes for a locality (only available on suggestions with country:fr for France or it for Italy and type: locality).
postal_town
contains the larger city (or the post office city) for a postal_code (only available on suggestions with type: postal_code).
matched_substrings
contains a set of substrings for each field (description, name, admin_0, admin_1, admin_2, postal_town) that match elements in the input. It can be used to highlight those substrings. Each substring is identified by an offset and a length.