All tutorials

Creating an AutoSuggest input box with what3words.js (v3.1 - deprecated)

easy

Please note this version of the component has been deprecated. The new version of the component can be found here.

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

1
2

Installation

Please note this version of the component has been deprecated. The new version of the component can be found here.

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

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

The URL in the script 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 text to display. Example value:"e.g lock.spout.radar"
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"
error-messagestringoverwrite the validation error message with a custom value. Example value:"you have entered an invalid address"
return-coordinatesbooleanCalls the what3words API to obtain the coordinates for the selected 3 word address

placeholder

Set the default text appearing in the input box. We recommend adding e.g. in front of a 3 word address so the user can see the text is an example only.

<what3words-autosuggest placeholder="daring.lion.race"/>
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

Enterprise Suite API Server

If you run our Enterprise Suite API Server yourself, you may specify the URL to your own server by appending the baseUrl parameter to the script

<script src="https://assets.what3words.com/sdk/v3.1/what3words.js?key=YOUR_API_KEY&baseUrl=YOUR_API_SERVER_URL/v3"></script>
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

Returning coordinates

If you would like to return coordinates for a 3 word address to plot on a map then you can request a call is made to the what3words API.

Add a listener to the select event to obtain the value and use within your application.

<what3words-autosuggest return-coordinates="true" />
Copied
document.querySelector('what3words-autosuggest')
  .addEventListener("select", ({target}) => {
    console.log(target.coordinatesLng)
    console.log(target.coordinatesLat)
  })
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
const input = document.getElementById("autosuggest");
    input.addEventListener("select", (value) => {
        console.log("[EVENT:select]", value.detail);
    });
Copied
WebsiteAdd a 3 word address input fieldJavaScript

Related tutorials