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 is available in our GitHub repository.

1

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

2

Getting started with ArcGIS Developer guide

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

4

Install and set up ArcGIS API for Javascript

In this example, we will use the AMD modules via ArcGIS CDN. Add the following code within 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
5

Create 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 a 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
6

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

Add 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’s made those classes easier to maintain and re-use. 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 into the require() statement.

In the <head> tag, add a <script> tag and an AMD require 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
8

List of all available languages

ArcGIS has their own geocoder, in order 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

2. Get the token from the what3words ArcGIS locator by

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

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

9

Convert 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 address, e.g. filled.count.soap.

In ArcGIS API for JavaScript to achieve this task we use the following locator method called addressToLocations(), that 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.
10

Convert 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(), that 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.
11

AutoSuggestion of 3 word addresses

When presented with a 3 word address that may be incorrectly entered, AutoSuggestion returns a list of potential 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(), that 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.
12

Batch geocode of a list of 3 word addresses

Users can use the batch geocode 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(), that 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
13

What3words Locator on the search bar widget

In case users are interested to add 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 it shown on the CodeSandbox

Related tutorials

Back to top