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

Combining the what3words.js AutoSuggest Component with a Mapbox Map

intermediate

The what3words JavaScript API wrapper provides components to make using the what3words API even easier. In this tutorial we will go through using the autosuggest component in combination with a Mapbox map. We will add the search field using the component and then respond to its select event to place a pin on the map at the inputted location.

You will also need to sign up for a Mapbox developer account and be able to view other Mapbox tutorials at https://docs.mapbox.com/mapbox-gl-js/api/.

We also have tutorials demonstrating it’s use with both LeafletJS and Google Map.

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

2

Installation

To load the JavaScript wrapper for the what3words 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 contained in the script tag is the location of a JavaScript file that loads everything you need for using the JavaScript wrapper for the what3words API.

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

3

Usage

Using the AutoSuggest component

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

<what3words-autosuggest/>
Copied

There are a number of ways you can configure the AutoSuggest component to better suite your usecase, including clipping to country and custom validation errors.

For more on the AutoSuggest component see the what3words AutoSuggest JavaScript Component.

Loading a map using Mapbox

You’ll need access to the Mapbox API using your own API key.

<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.js'></script>
<script src="https://assets.what3words.com/sdk/v3/what3words.js?key=YOUR_API_KEY"></script> 
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v1.0.0/mapbox-gl.css' rel='stylesheet' />
Copied

Place the map on the page, centered at a location of your choosing.

<div id='map'>
mapboxgl.accessToken = YOUR_MAPBOX_ACCESS_TOKEN;
var map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v9',
  center: [-0.195499, 51.52086],
  zoom: 12
});
Copied

Set the navigation controls.

var nav = new mapboxgl.NavigationControl();
map.addControl(nav, 'bottom-right');
Copied

Position the component on the map

Determine the position of the component on the map.

<style>
     #autosuggest {
     position: absolute;
     top: 10px;
     left: 10px;
     z-index: 9999;
     }
     #wrapper {
     position: relative;
     height: 100%;
     }
     #map {
     height: 100%;
     } 
     html, body {
     height: 100%;
     margin: 0;
     padding: 0;
     font-size: 10px;
     }
     .marker {
     background-image: url('https://what3words.com/map/images/marker-18.png');
     background-size: cover;
     width: 50px;
     height: 50px;
     border-radius: 50%;
     cursor: pointer;
     } 
</style>
Copied

Tie the component to the styling.

<div id="wrapper">
   <div id="autosuggest">
      <what3words-autosuggest id="autosuggest"/>
   </div>
</div>
Copied

Listen for the select event

Here we use an event listener to pick up when a user selects a 3 word address from the listed suggestions for their input. Here we output information to console for debugging purposes.

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

Use convert to coordinates to get the lat/lng of the address.

With the what3words API we can jump between the 3 word address and the coordinates that relate to it easily. Here we call the API with the 3 word address selected by the user.

what3words.api.convertToCoordinates(value.detail).then(function(response) {
    console.log("[convertToCoordinates]", response);
});
Copied

Use to coordinates gained for the convert to coordinates API call to place a pin on the map and focus on it

Now we have our coordinates we can place a what3words custom marker for our selected 3 word address on our map and focus the map on this location.

response.features.forEach(function (marker) {
// clear existing markers
markers.forEach(function (marker) {
  marker.remove();
});
markers = [];

// create a HTML element for the marker
var el = document.createElement('div');
el.className = 'marker';  

// make a marker and add to the map
var mapMarker = new mapboxgl.Marker(el)
  .setLngLat(marker.geometry.coordinates)
  .addTo(map);

markers.push(mapMarker);
map.jumpTo({
  center: marker.geometry.coordinates,
  zoom: 19
});
Copied

Related tutorials

Back to top