Tutorials | what3words
We use cookies, including third party cookies, to improve your experience and for marketing purposes. By continuing to browse we assume you have consented to their use.Learn more
got it
All tutorials

Creating an AutoSuggest input box with what3words.js

easy

The what3words API JavaScript Wrapper provides components to make the what3words API even easier to use. These components can be added to any site using JavaScript and HTML. In this tutorial, you’ll learn how to use a component from the wrapper. This will allow a user to get a search input for their page, powered by the Autosuggest function of the what3words API. The wrapper is straightforward to use and you can configure it for your needs using a range of properties.

Find out how else you can utilise the what3words API using JavaScript by taking a look at the what3words JavaScript API Wrapper 

You will need a what3words API key to complete this tutorial.

2

Installation

To load the what3words JavaScript API, use a script tag like the one in the following example:

<script src="https://assets.what3words.com/sdk/v3/what3words.js?key=YOUR_API_KEY"></script>
Copied

The URL in the <code>script</code> tag is the location of a JavaScript file that loads everything you need for using the what3words API in JavaScript.

The key parameter contains your application’s API key.

3

Usage

In one line, you can have an input box that will call the what3words API AutoSuggest endpoint.

Code example:

<what3words-autosuggest/>
Copied

Available properties

There are a range of customisation properties you can use to configure the AutoSuggest component.

ParameterTypeDescription
placeholderstringdefault address to display. Example value:"lock.spout.radar"
n-resultsnumbernumber of results to return. Example value:"3"
autosuggest-focusstringcomma separated lat/lng of point to focus on. Example value:"51.521251,-0.203586"
n-focus-resultsnumberthe number of results within what is returned to apply the focus to. Example value:"2"
clip-to-countrystringconfine results to a given country or comma separated list of countries. Example value:"GB,US"
clip-to-bounding-boxstringConfine results to a bounding box specified using co-ordinates. Example value:"51.521,-0.343,52.6,2.3324"
clip-to-circlestringRestrict AutoSuggest results to a circle, specified by lat,lng,kilometres, where kilometres in the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.
clip-to-polygonstringRestrict AutoSuggest results to a polygon, specified by a comma-separated list of lat,lng pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs. Example value:"51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343"
validationbooleanturn on and off the validation on entry. Example value:"false"
debugbooleanoutput information to console for debugging. Example value:"false"
error-messagestringoverwrite the validation error message with a custom value. Example value:"you have entered an invalid address"

placeholder

Set the default address appearing in the input box

<what3words-autosuggest placeholder="daring.lion.race"/>
Copied

n-results

Set the number of results to return, the default is 3

<what3words-autosuggest n-results="5"/>
Copied

autosuggest-focus / n-focus-results

These two properties work in combination. User autosuggest-focus to define a lat/lng around which to apply a focus to your results. n-focus-results then determines the number of results returned to which this focus get applied.

<what3words-autosuggest
          autosuggest-focus="51.521251,-0.203586" n-focus-results="2"/>
Copied

clip-to-country

Restrict results to a given country or comma separated list of countries

<what3words-autosuggest clip-to-country="GB,US"/>
Copied

clip-to-bounding-box

Restrict results to a bounding box specified using co-ordinates

<what3words-autosuggest
          clip-to-bounding-box="51.521,-0.343,52.6,2.3324"/>
Copied

clip-to-circle

Restrict AutoSuggest results to a circle, specified by lat,lng,kilometres, where kilometres in the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example, 181 is equivalent to -179.

<what3words-autosuggest
          clip-to-circle="51.521,-0.343,142"/>
Copied

clip-to-polygon

Restrict AutoSuggest results to a polygon, specified by a comma-separated list of lat,lng pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs.

<what3words-autosuggest
          clip-to-polygon="51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343"/>
Copied

validation

Turn off validation, it is on by default

<what3words-autosuggest validation="false"/>
Copied

debug

Turn on debug information to console, it is off by default

<what3words-autosuggest debug="true"/>
Copied

error-message

Return custom error message for 3 word address validation

<what3words-autosuggest error-message="you have entered an invalid address"/>
Copied

Listening for events

Listen for either the change or valid events

This requires debugging to be enabled and we are giving the component an id to reference when listening for the event

<what3words-autosuggest id="autosuggest" debug="true"/>
Copied

Listen for either the ‘change’ or ‘valid’ events

This requires debugging to be enabled and we are giving the component an id to reference when listening for the event

const input = document.getElementById("autosuggest");
    input.addEventListener("select", (value) => {
        console.log("[EVENT:select]", value.detail);
    });
Copied

Related tutorials

Back to top