Autosuggest JavaScript Component

A component taken from the what3words JavaScript Wrapper.

The JavaScript API wrapper provides components to make using the what3words API even easier. In this tutorial we will go through using a component from the wrapper which allows the user to get a search input for their page, powered by the what3words Autosuggest API. As you will see it is straight forward to use and allows you to configure it for your needs using a range of properties.

Step 1: Obtain an API key

Sign up to obtain your free API key.

Step 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>

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

The key parameter contains your application's API key. Sign up to obtain your free API key.

Step 3: Usage

Using the autosuggest component

In one line you can have an input box which will call the what3words autosuggest API endpoint

Code Example
 <what3words-autosuggest/>

If you don't require any configuration that's it, try it here:

Available properties

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

placeholder string

default address to display

Example value:"lock.spout.radar"

n-results number

number of results to return

Example value:"3"

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-to-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.

Example value:"51.521,-0.343,142"

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"

validation boolean

turn on and off the validation on entry

Example value:"false"

debug boolean

output information to console for debugging

Example value:"false"

error-message string

overwrite 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

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

n-results

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

Code Example
 <what3words-autosuggest n-results="5"/>

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.

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

clip-to-country

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

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

clip-to-bounding-box

Confine results to a bounding box specified using co-ordinates

Code Example
 <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.

Code Example
 <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.

Code Example
 <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

Code Example
 <what3words-autosuggest validation="false"/>

debug

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

Code Example
 <what3words-autosuggest debug="true"/>

error-message

Return custom error message for three word address validation

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

listening for events

Listen for either the 'change' or 'valid' events

Code Example

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"/>

Then we listen for the event and log the output to the console


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

Step 4: Putting It All Together

The example below takes the concepts described above, and turns some of them into a complete example. This includes a placeholder, expanding results to 5, clipping to Great Britain and the United States, outputting debug to console, using a custom error message for the validation and looking for the valid event and outputting that to the console.

<html>
  <head>
    <title>w3w JavaScript Autosuggest Tutorial</title>
    <meta charset="utf-8" />
    <script src="https://assets.what3words.com/sdk/v3/what3words.js?key=YOUR_W3W_API_KEY"></script>
  </head>
  <body>
    <p>
    <what3words-autosuggest
      id="autosuggest"
      placeholder="daring.lion.race"
      n-results="5"
      clip-to-country="GB,US"
      debug="true"
      error-message="you have entered an invalid address"/>
    </p>
    <script>
      const input = document.getElementById("autosuggest");
      input.addEventListener("select", (value) => {
        console.log("[EVENT:select]", value.detail);
      });
    </script>
  </body>
</html>

Try our configured version below: