Localities Widget Quick Start

How to embed and customize our Autocomplete search box Javascript Widget

  1. Introduction
  2. Settings Overview


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:

        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.


Localities search will only trigger when the number of typed chars is superior or equal to minLength.
Defaults to 1.

"minLength": 3


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"


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"


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 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"

Was this article helpful?
Have more questions? Submit a request