Localities Widget Quick Start

How to embed and customize our Autocomplete search box Javascript Widget
  1. Introduction
  2. Settings Overview
    1. minLength
    2. types
    3. data
    4. extended
    5. components
    6. Translations Settings
    7. Multiple Settings example


The Woosmap Localities Widget aims to ease the embedding of a localities, postcodes 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.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('#InputSelector', {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’, ‘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"


The type locality only searches on locality names by default. Activating the parameter extended=postal_code will retrieve locality suggestions while searching for a postcode too. Only works on the locality type and on France and Italy localities.

"extended": "postal_code"


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)

"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