All tutorials
Creating an AutoSuggest input box with what3words.js (v3.1 - deprecated)
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
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>
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.
In one line, you can have an input box that will call the what3words API AutoSuggest endpoint.
Code example:
<what3words-autosuggest/>
Available properties
There are a range of customisation properties you can use to configure the AutoSuggest component.
| Parameter | Type | Description |
|---|---|---|
| placeholder | string | default text to display. Example value:"e.g lock.spout.radar" |
| autosuggest-focus | string | comma separated lat/lng of point to focus on. Example value:"51.521251,-0.203586" |
| n-focus-results | number | the number of results within what is returned to apply the focus to. Example value:"2" |
| clip-tp-country | string | confine results to a given country or comma separated list of countries. Example value:"GB,US" |
| clip-to-bounding-box | string | Confine results to a bounding box specified using co-ordinates. Example value:"51.521,-0.343,52.6,2.3324" |
| clip-to-circle | string | 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. |
| clip-to-polygon | string | 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. Example value:"51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343" |
| error-message | string | overwrite the validation error message with a custom value. Example value:"you have entered an invalid address" |
| return-coordinates | boolean | Calls 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"/>
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"/>
clip-to-country
Restrict results to a given country or comma separated list of countries
<what3words-autosuggest clip-to-country="GB,US"/>
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"/>
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"/>
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"/>
validation
Turn off validation, it is on by default
<what3words-autosuggest validation="false"/>
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>
debug
Turn on debug information to console, it is off by default
<what3words-autosuggest debug="true"/>
error-message
Return custom error message for 3 word address validation
<what3words-autosuggest error-message="you have entered an invalid address"/>
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" />
document.querySelector('what3words-autosuggest') .addEventListener("select", ({target}) => { console.log(target.coordinatesLng) console.log(target.coordinatesLat) })
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"/>
const input = document.getElementById("autosuggest"); input.addEventListener("select", (value) => { console.log("[EVENT:select]", value.detail); });