Autocomplete Requests
Autocomplete as the user types
Overview
The Localities Autocomplete endpoint provides worldwide suggestions 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 suggestions such as city names, postal codes, suburb names or addresses.
The returned suggestions are designed to be presented to the users to aid them in selecting their desired location. If you want to get more information on one of the suggestions, you must send a /Details request using its public_id .
Autocomplete and details on address and postal_code may be subject to specific product activation. Please see coverage page for more details.
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
Autocompletion is done based on this string.
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. Alternatively, you can use the private_key parameter 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) from which 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, where no referer checkings are performed.
You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.
Optional parameters
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.
Example
https://api.woosmap.com/localities/autocomplete/?input=london&key={PUBLIC_API_KEY}&types=locality|airport|admin_level
components
Geographic places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries are identified by a two character, ISO 3166-1 Alpha-2 or a three character, ISO 3166-1 Alpha-3 compatible country code. Multiple countries must be passed as separates components, with the pipe character (|) as a separator.
Example
components=country:fr or components=country:fra would restrict your results to places within France. components=country:fr-fr returns locations only in Metropolitan France.
Multiple countries example
components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to the United Kingdom, France, Belgium, Spain and Italy.
See coverage for more details on the countries covered by Localities
language
The language code, indicating in which language the results should be returned, if possible. If no language parameter is supplied, the Localities service will use the default language of each country. No language is necessary for a postal_code request.
location
This parameter is used to add a bias to the autocomplete feature. The location defines the point around which to retrieve results in priority. It must be specified in the latitude,longitude string format.
radius
This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results in priority. Results outside of the defined area may still be displayed. Default radius if this parameter is not set is 100 000.
data
This parameter accepts two values: standard (default) or advanced. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. See details in the Localities API Coverage web page
Notice: 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.
custom_description
This parameter allows to choose the description format for all or some of the suggestion types selected. The custom formats are described as follows:
custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"
Available fields
| name | administrative_area_level_0 | administrative_area_level_1 | administrative_area_level_2 | postal_codes | postal_town | locality | iata_code | |
|---|---|---|---|---|---|---|---|---|
| locality | • | • | • | • | • | • | ||
| postal_code | • | • | • | • | ||||
| admin_level | • | • | ||||||
| country | • | |||||||
| airport | • | • | • | |||||
| train_station | • | • | • | • | • | |||
| metro_station | • | • | • | • | • | |||
| shopping | • | • | • | • | • | |||
| museum | • | • | • | • | • | |||
| tourist_attraction | • | • | • | • | • | |||
| amusement_park | • | • | • | • | • | |||
| art_gallery | • | • | • | • | • | |||
| zoo | • | • | • | • | • |
Example
custom_description=locality:"{name} - {administrative_area_level_0}"|postal_code:"{name} ({administrative_area_level_1})"
Suggestions of the locality type will look like München - Germany", instead of the default format: München, Bayern, Germany
Suggestions of the postal_code type will look like SW6 1HN (City of London), instead of the default format: SW6 1HN, City of London, United Kingdom
extended
This parameter accepts one value: postal_code. 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. This behavior is only available for France and Italy.
Response
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.
Suggestion results can contain the following fields:
public_id
Contains a unique ID for each suggestion. This ID is required to perform Localities Details request.
description
The description of the suggestion. The description format varies depending on the type of the retrieved object. You can customize the description format using the custom_description param.
type
Contains the type of the suggestion, See the list of existing types).
matched_substrings
Contains a set of substrings that match elements in the input. It can be used to highlight those substrings. Each substring is identified by an offset and a length.
has_addresses
On the specific territory of United Kingdom, Localities Autocomplete request can return the has_addresses attribute 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 the Details endpoint with the Localities public_id. To get the details of an address you need to request the Details endpoint once more passing in the dedicated address public_id.
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.
Notice : name is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field name in the Details endpoint instead.
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.
Notice : location is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field geometry.location in the Details endpoint instead
admin_0
Contains the country name.
Notice : admin_0 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_0 in the Details endpoint instead
admin_1
Contains the administrative level including the suggestion.
Notice : admin_1 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_1 in the Details endpoint instead
admin_2
For small locality type points of interests (suburbs, neighborhoods, villages), contains the municipality it belongs to.
Notice : admin_2 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_2 in the Details endpoint instead
viewpoint
Contains geographic bounds (north, south, east, west) to help center a map on a suggestion’s selection by the user.
Notice : viewpoint is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field geometry.viewport in the Details endpoint instead
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).
Notice : postal_codes is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : postal_codes in the Details endpoint instead
postal_town
Contains the larger city (or the post office city) for a postal_code (only available on suggestions with type: postal_code).
Notice : postal_town is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : postal_town in the Details endpoint instead
iata_code
Contains the International Air Transport Association (IATA) code of an airport (only available on suggestions with type: airport)
Notice : iata_code_ is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : iata_code in the Details endpoint instead
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)
Example
{
"localities": [
{
"public_id": "SRji5gQLTz9EznRhLkjD/1pYWLQ=",
"description": "SW6 1HL, City of London, United Kingdom",
"type": "postal_code",
"matched_substrings": {
"description": [
{"offset": 17, "length": 6}
],
[...]
},
"has_addresses": true,
[...]
},
{
"public_id": "Ch6qA8cLmvyvEEoFy6nYeFcEdNU=",
"description": "London, City of London, United Kingdom",
"type": "locality",
"matched_substrings": {
"description": [
{"offset": 0,"length": 6},
{"offset": 16,"length": 6}
],
[...]
},
[...]
}
]
}
Samples
Following are two samples showcasing the autocomplete requests.