All tutorials

Using the what3words Locator within ArcGIS API for JavaScript

intermediate

This guide describes how to use what3words ArcGIS Locator for ArcGIS API for JavaScript to build compelling web apps that unlock your data’s potential with interactive user experiences and stunning 2D and 3D visualizations.

There are multiple options for bringing the ArcGIS API for JavaScript into your app. The most common way is to use the AMD modules via ArcGIS CDN, however, you can also use ES modules for local builds. The examples here will show how to integrate what3words ArcGIS locator to the AMD modules via ArcGIS CDN.

Resources: Full examples of how to use what3words ArcGIS Locator for ArcGIS API for JavaScript are available in our
Github repository

1Get API key

Signup to create key

2Getting started with ArcGIS Developer guide

If you are new to ArcGIS start with the mapping APIs and location services guide.

3What can you do with ArcGIS Locator

4Install and set up ArcGIS API for Javascript

In this example, we will use the AMD modules via ArcGIS CDN. Add the following code to the <head> tag of your index.html file.

<link rel="stylesheet" href="https://js.arcgis.com/4.21/esri/themes/light/main.css">

<script src="https://js.arcgis.com/4.21/"></script>

Copied

5Create an HTML page

Define an HTML page to create a map that is the full width and height of the web browser window.

Add HTML and CSS to create a page with an viewDiv element. The viewDiv is the element that displays the map and its CSS resets any browser settings, so it can consume the full width and height of the browser.
The <!DOCTYPE html> tag is not required in CodeSandbox. If you are using a different editor or running the page on a local server, be sure to add this tag to the top of your HTML page.

<html>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
   <title>The what3words Locator on ArcGIS API for Javascript</title>
   <style>
     html,
     body,
     #viewDiv {
       padding: 0;
       margin: 0;
       height: 100%;
       width: 100%;
     }
   </style>
 </head>
 <body>
   <div id="viewDiv"></div>
 </body>
</html>

Copied

6Reference the API

In the <head> tag, add references to the CSS file and JS library.

<html>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
   <title>The what3words Locator on ArcGIS API for Javascript</title>
   <style>
     html,
     body,
     #viewDiv {
       padding: 0;
       margin: 0;
       height: 100%;
       width: 100%;
     }
   </style>

    <link rel="stylesheet" href="https://js.arcgis.com/4.21/esri/themes/light/main.css">
    <script src="https://js.arcgis.com/4.21/"></script>

 </head>
 <body>
   <div id="viewDiv"></div>
 </body>
</html>

Copied

7Add AMD modules

The ArcGIS JS API contains Asynchronous Module Definition (AMD) modules to load JS resources into memory. By defining their API’s object classes in modules, Esri made those classes easier to maintain and reuse. Loading the modules asynchronously (in parallel rather than one at a time) means that apps built on the API will load faster than they would in a non-AMD framework.

One of your recurring tasks as an Esri JS developer will be to identify the modules containing the object classes needed by your app.
In our case, we are going to refer to the following modules:

Map
MapView
locator
esriRequest

Add these modules to the require() statement.

In the <head> tag, add a <script> tag and an AMD require a statement to load these modules.

<html>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
   <title>The what3words Locator on the search bar widget</title>
   <style>
     html,
     body,
     #viewDiv {
       padding: 0;
       margin: 0;
       height: 100%;
       width: 100%;
     }
   </style>

    <link rel="stylesheet" href="https://js.arcgis.com/4.21/esri/themes/light/main.css">
    <script src="https://js.arcgis.com/4.21/"></script>
<script>
      require([
        "esri/rest/locator",
        "esri/Map",
        "esri/views/MapView",
        "esri/request",
        "esri/Graphic"
      ], (locator, Map, MapView, esriRequest, Graphic) => {

}); </script></head>
 <body>
   <div id="viewDiv"></div>
 </body>
</html>

Copied

8List of all available languages

ArcGIS has its geocoder, to get the what3words ArcGIS Locator user needs to

1. import the Esri locator. Represents a geocode service resource exposed by the ArcGIS Server REST API.

require(["esri/rest/locator"], (locator) => { /* code goes here */ });

Copied

It is used to

Find address candidates for multiple input addresses(addressesToLocations())
Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter(addressToLocations())
Locates an address based on a given point (locationToAddress())
Get character-by-character autocomplete suggestions (suggestLocations())

2. Get the token from the what3words ArcGIS locator by

using your credentials, what3words email address as username and what3words API key as password;
using the esriRequest to retrieve data from the ArcGIS what3words remote server;
adding the response.data.token to the URL of the what3words ArcGIS Server REST resource that represents a Locator service, for example, https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_EN_English/GeocodeServer

require([
   "esri/rest/locator",
   "esri/Map",
   "esri/views/MapView",
   "esri/request",
   "esri/Graphic"
], function (locator, Map, MapView, esriRequest, Graphic) {
   // Set up a locator task using the world geocoding service
   const w3wLocator = esriRequest(
       // First get the token for the what3words Locator
       "https://arcgis.what3words.com/v2/arcgis/tokens", {
           method: "get",
           query: {
               f: "json",
               username: "YOUR-W3W-EMAIL-ADDRESS", // YOUR-W3W-EMAIL-ADDRESS
               password: "YOUR-W3W-API-KEY", // YOUR-W3W-API-KEY
               expiration: 10
           }
       }
   ).then((response) => {
       // create url for using the what3words Locator to reverse geocode
       const locatorUrl =
      "https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_EN_English/GeocodeServer?token=" + response.data.token;

…

   });
});

Copied

Here is the list of all the what3words locator URLs for all languages that can be used to replace the one mentioned above.

https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_AF_Afrikaans/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_AR_Arabic/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_BG_Bulgarian/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_BN_Bengali/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_COMBINED_Combined/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_CS_Czech/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_CY_Cymraeg/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_DA_Dansk/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_DE_Deutsch/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_EL_Greek/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_EN_English/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_ES_Espanol/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_FI_Suomi/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_FR_Francais/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_GU_Gujarati/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_HE_Hebrew/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_HI_Hindi/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_HU_Magyar/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_ID_Bahasa/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_IT_Italiano/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_JA_Japanese/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_KN_Kannada/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_KO_Korean/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_ML_Malayalam/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_MN_Mongolian/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_MR_Marathi/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_MS_Bahasa_Malayia/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_NE_Nepali/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_NL_Netherlands/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_NO_Norsk/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_PA_Panjabi/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_PL_Polski/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_PT_Portugues/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_RO_Romanian/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_RU_Russian/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_SV_Svenska/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_SW_Kiswahili/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_TA_Tamil/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_TE_Telugu/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_TH_Thai/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_TR_Turkish/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_UR_Urdu/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_VI_Vietnamese/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_XH_IsiXhosa/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_ZH_Chinese/GeocodeServer https://arcgis.what3words.com/v2/arcgis/rest/services/what3words_ZU_IsiZulu/GeocodeServer

9Convert to Coordinates

This function converts a 3 word address to a position, expressed as coordinates of latitude and longitude.

This function takes the words parameter as a string of 3 word addresses, e.g. filled.count.soap.

In ArcGIS API for JavaScript to achieve this task we use the following locator method called addressToLocations(), which sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter.

addressToLocations(url, params, requestOptions){Promise<AddressCandidate[]>}

Copied

Parameters are:

Url => URL to the ArcGIS Server REST resource that represents a locator service.
Address => The address argument is a data object that contains properties representing the various address fields accepted by the corresponding geocode service.

10Convert to 3 word address

This function converts coordinates (expressed as latitude and longitude) to a 3 word address. In ArcGIS API for JavaScript to achieve this task we use the following locator method called locationToAddress(), which locates an address based on a given point.

locationToAddress(url, params, requestOptions){Promise<AddressCandidate>}

Copied

Parameters are:

Url => URL to the ArcGIS Server REST resource that represents a locator service.
Location => (point feature) The point at which to search for the closest address. The location should be in the same spatial reference as that of the geocode service.

5AutoSuggestion of 3 word addresses

When presented with a 3 word address that may be incorrectly entered, AutoSuggestion returns a list of potentially correct 3 word addresses. It needs the first two words plus at least the first character of the third word to produce suggestions, e.g. filled.count.s.

This method provides corrections for mistyped words (including plural vs singular), and words being in the wrong order.

In ArcGIS API for JavaScript to achieve `Autosuggested Locations` we use the following locator method called suggestLocations(), which gets character-by-character auto-suggestions.

suggestLocations(url, params, requestOptions){Promise<SuggestionResult[]>}

Copied

Parameters are:

Url => URL to the ArcGIS Server REST resource that represents a locator service.
Text => The input text entered by a user which is used by the suggest operation to generate a list of possible matches.

12Batch geocode of a list of 3 word addresses

Users can use the batch geocoding function to convert a list of 3 word addresses to a set of complete addresses with locations using the what3words ArcGIS Locator.

In ArcGIS API for JavaScript, to achieve Batch geocoding we use the following locator method called addressesToLocations(), which finds address candidates for multiple input addresses. Note that this method requires an ArcGIS Server 10.1 or greater geocode service.

addressesToLocations(url, params, requestOptions){Promise<AddressCandidate[]>}

Copied

Parameters are:

Url => URL to the ArcGIS Server REST resource that represents a locator service.
Addresses => The input addresses in the format supported by the geocode service. If the service supports ‘Single Line Input’ the input addresses will be in the following format:

{ 
     OBJECTID: 1,
    what3words: "clean.wider.both"
}

Copied

In case users are interested in adding the what3words ArcGIS Locator to their Search bar widget, make sure to

Follow these instructions to share the ArcGIS locator within the organisation in your ArcGIS Online account;
And pass the locator URL + token to the Search widget as is shown on the CodeSandbox

GIS Batch convert 3 word addresses or co-ordinates Display a 3 word address Use 3 word addresses with a map Use 3 word addresses within a GIS Use 3 word addresses within an address search ArcGIS

Developer

All tutorials

Using the what3words Locator within ArcGIS API for JavaScript

Related tutorials

How to add the what3words Locator to ArcGIS Desktop

How to add the what3words Locator to ArcGIS Online

How to add the what3words Locator to ArcGIS Online and Survey123