November 08, 2024

Configure the Autocomplete Widget

Explore all configuration parameters to tune the widget.

1. Default Configuration
2. autocomplete config
3. search config
4. google config
5. woosmap config
6. Examples

This API has been deprecated and replaced with MultiSearch JavaScript Library.

The Widget is highly customizable. Asides from defining how you would like to search in Woosmap Localities and Google Places, you can control the fallback between one and the other based on Fuzzy string matching ratio. If you need to support a new parameter, add it first to the default configuration file.

Default Configuration

Here is the full default configuration:

JavaScript

        let defaultConfig = {
    autocomplete: {
        minChars: 2,
        maxItems: 5,
        autoFirst: true,
        sort: false,
        debounceTime: 100,
    },
    search: {
        minRatio: 75,
        breakpointRatio: 100,
        fallbackWoosmap: true
    },
    google: {
        clientId: '',
        apiKey: '',
        channel: '',
        librariesToLoad: ['places'],
        version: '3',
        componentRestrictions: '',
        fields: ['address_component', 'adr_address', 'formatted_address', 'geometry', 'icon', 'name', 'place_id', 'type', 'url', 'vicinity'],
        useSessionTokens: true
    },
    woosmap: {
        projectKey: '',
        componentRestrictions: '',
        types: [],
        data: 'standard',
        language: ''
    }
};

    

autocomplete config

These parameters control the behaviour of autocomplete.

Option	Description	Default
minChars	Minimum characters the user has to type before the autocomplete popup shows up	2
maxItems	Maximum number of suggestions to display. Best practice to let it default to 5. Could be set between 1 and 10 as Woosmap Localities and Google Places return both 5 results.	5
autoFirst	Should the first prediction element be automatically selected?	true
sort	Controls if list items are ordered by string matching ratio. if set to false, predictions are displayed as they come.	false
debounceTime	Time in miliseconds before executing the autocomplete requests when user type (cf. debounce function).	100

search config

Use to manage the Fuzzy string matching ratio values before fallback to google places.

Option	Description	Default
minRatio	Minimum string matching ratio. If calculated ratio of autocomplete item is under this value, the item is deleted from autocomplete predictions list	75
breakpointRatio	Controls the Fallback to Google Places. Do not search and populate predictions response with Google Places in case Woosmap Localities return at least one item with required breakpointRatio	100
fallbackWoosmap	Controls if you want to display Woosmap Localities even with insufficient ratio (minRatio not reached) in case Google Places returns no results	true
fallbackWoosmapAddress	Controls if you want to call Woosmap Address API instead of Google Places	false

google config

The Google Places configuration. Google Places is loaded asynchronously with this option if not already present in your integration. Otherwise, your included google places library will be used.

Option	Description	Default
clientId	ClientID of your google license	''
apiKey	API Key of your google license	''
channel	Channel to track usage of your google license	''
librariesToLoad	load specific google libraries	['places']
version	load specific google version	3
componentRestrictions	restrict search by componentRestrictions. cf. documention	{}
fields	Fields returned by a call to Google Places getDetails request. cf. documention	['address_component', 'adr_address', 'formatted_address', 'geometry', 'icon', 'name', 'place_id', 'type', 'url', 'vicinity']
useSessionTokens	Use Session Token for billing purpose. cf documention	true

Javascript Snippet used to check that Google places is already loaded:

JavaScript

        if (typeof google === "object" && typeof google.maps === "object" && typeof google.maps.places === "object"){}

    

woosmap config

The Woosmap Localities configuration. Read the official doc for more details.

Option	Description	Default
projectKey	Your woosmap Project public Key	''
componentRestrictions	A grouping of places to which you would like to restrict your results. cf. documention	{}
addressComponentRestrictions	A grouping of countries (as ISO 3166-1 alpha-3 code) to which you would like to restrict your results. (example: {country: ["GBR","FRA"]} )	{}
types	An array of types of predictions to return. cf. documention. (example: ["locality", "country"])	[]
data	Data standard or advanced. cf. documention.	'standard'
language	Expected response language (ISO 639-1 code). Default is the country local or browser language. (example: 'de')	''

Examples

Restrict your search by Country

Specify the componentRestrictions parameter like this:

JavaScript

        const config = {
    woosmap: {componentRestrictions: {country: ['UK', 'FR', 'ES']}},
    google: {componentRestrictions: {country: ['UK', 'FR', 'ES']}}
};   

    

Search for custom Woosmap Localities types

Specify the types parameter like this:

JavaScript

        const config = {
    woosmap: {types: ["locality", "postal_code", "admin_level", "country", "airport", "metro_station", "train_station", "shopping", "museum", "zoo", "amusement_park", "art_gallery", "tourist_attraction"]}
};