All tutorials
Using the what3words Locator within ArcGIS API for JavaScript
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.
Getting started with ArcGIS Developer guide
If you are new to ArcGIS start with the mapping APIs and location services guide.
What can you do with ArcGIS Locator
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>
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>
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>
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>
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 */ });
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; … }); });
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
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[]>}
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.
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>}
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.
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[]>}
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.
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[]>}
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" }
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