Localities Widget Quick Start
How to embed and customize our Autocomplete search box Javascript Widget
Introduction
The Woosmap Localities Widget aims to ease the embedding of a localities, postcodes, addresses and other geographical places search box in your website. It’s a lightweight JavaScript library to quickly implement Woosmap Localities. Please use the hosted and updated online version, as in the example below :
<script src="https://sdk.woosmap.com/localities/localitieswidget.2.0.js?key=woos-xxxx"></script>
Replace “woos-xxxx” with your own Woosmap API Key.
To instantiate the Localities Widget, you need to build a new Autocomplete
object .
This constructor receives 2 arguments:
- the input ID selector where user will perform searches
- an optional JSON Config Object (e.g.
{"types":"locality"}
) to specify all desired settings.
new woosmap.localities.Autocomplete('myInputID', {types: "locality"});
Refer to the Sample Usage to see full widget integration.
Settings Overview
Please refer to the Localities Reference to see all configurable settings. Below is a summary of main parameters. All parameters are optional.
minLength
Localities search will only trigger when the number of typed chars is superior or equal to minLength.
Defaults to 1.
"minLength": 3
types
Requested suggestion type : ‘locality’, ‘postal_code’, ‘address’, ‘admin_level’, ‘country’, ‘train_station’, ‘metro_station’, ‘shopping’, ‘airport’, ‘museum’, ‘zoo’, ‘amusement_park’, ‘art_gallery’ or ‘tourist_attraction’. When omitted, will return localities + postcodes.
"types": "locality"
data
Default config will return Postcodes only for (most of) Western Europe countries. “advanced” data will return postcodes for any country.
Defaults to ‘standard’
"data": "advanced"
extended
If set, this parameter allows a refined search over locality names that bear the same postal code.
See the extended parameter documentation in the autocomplete section.
components
Components restrictions. Country subparameter restricts results to a single country, or an array of countries.
(using ISO 3166-1 Alpha-2 country codes, case insensitive)
If your use case is specific to certain countries, you should always use this parameter to get more accurate suggestions.
"components": {
"country": "es"
}
"components": {
"country": ["fr", "es"]
}
Translations Settings
The results can be displayed in different languages. Define the preferred language
parameter when building your config
object (e.g. {language: "en"}
).
Multiple Settings example
{
"minimumInputLength": 3,
"types": ["locality", "postal_code"],
"data": "advanced",
"components": {
"country": ["fr", "es"]
},
"language": "zh"
}