Box Jumping for ArcGIS
An alternative address system comes to the rescue where good old postal addresses cannot help. Now for ArcGIS Experience Builder.
A Bavarian parks his car at ///psyches.army.truck and enters the headquarters of Esri Germany in ///perceptions.retakes.somebody. This situation could just as well be described as: A Bavarian parks his car at Raiffeisenstr. 16 and enters the headquarters of Esri Germany in Ringstr. 7. Is similar, even if he would probably have to turn around a few times to find the right building and the entrance door.
It gets complicated when he has not driven his tractor home after 8 ‘Maß’ of beer at the village fair, but has parked it in the field. The next morning, he now tries to remember the amount and location of the bushes along the way in order to find his vehicle again. Had he had a very specific app handy in the moment he got out, he could have simply looked up the location: Clearly, he didn't make the turn around the forest on the way home from Kranzberg to Sünzhausen and left the tractor at ///failsafe.renowned.cluttered to be on the safe side.
This is how it turns out when you sit in your office at ///sector.dared.madder and try to imagine a real-life situation of a typical inhabitant of the extended Munich surroundings. In this case, it doesn’t matter how realistic the description is. What’s important is that a spot on earth without an address has been unambiguously designated and made retrievable. Transferred to life in civilization the case could arise that a delivery is expected in my office. The main entrance is in ///grab.secretly.tractor, but better parking is in the courtyard and the entrance there is in ///wedding.scrap.bossy. The address for both points is equally Konrad-Adenauer-Ufer 41-45.
What is all this about? Concert promoter Chris Sheldrick had the same problem: delivery points for equipment or entrances for artists are not describable with postal addresses. Festivals take place in large areas, and outside densely populated areas, there is no dense network of streets and house addresses. Together with mathematician Mohan Ganesalingam he looked for an idea to make every place in the world addressable and developed the alternative address system what3words. This system covers the entire globe in a 3x3 meter grid and uses a sophisticated algorithm to assign each square a unique address consisting of three words. In contrast to geographic coordinates, such as used by a GPS system, the resulting designations are memorable and easy to convey even in natural language.
The words are chosen in a way that inner-city addresses are described by shorter words and similar combinations are as far apart as possible. Even if there are doubts as to whether the measures taken for acoustic differentiation are sufficient for the system to be used in safety-critical areas, it's already finding a broad user base: Mercedes Benz was the first car manufacturer to come aboard in 2017. A look at the Products page on the official website shows that the system has since found its way into the vehicles of numerous other manufacturers, but is also being used by companies in the fields of mobility, logistics, sports, security and, of course, map, GIS and CAD providers.
what3words is thus included in so-called embedded systems, i.e. permanently installed systems such as navigation systems in vehicles. Other implementations bring the squares as a plugin into existing software products, among which are planning tools for desktop workstations or mobile apps for localizing missing paragliders or for drone control. A dedicated mobile map app is also available that locates the device via GPS and places it in the appropriate grid cell on the map.
For developers, what3words can be used in a variety of ways: The REST API enables a connection to all systems that can communicate via HTTP. In addition, there are libraries for the most common programming languages, which simplify the handling of the REST API. Among the GIS extensions there is also an implementation as ArcGIS Locator Service. All programming interfaces can be used via API key and tested with a free plan.
The what3words GeocodeServer comes in versions for every available language and also in a combined variant. It can be hooked into ArcGIS desktop software as well as into an ArcGIS online organization or an ArcGIS Enterprise installation. Via the Locator module of the ArcGIS API for JavaScript, the URL of the respective GeocodeServer can also be used directly in the code. Step-by-step instructions can be found on the what3words website. In addition, the company offers numerous programming examples in different languages on its GitHub account, including the ArcGIS API for JavaScript.
Now we need to know how to easily integrate the system into a web application. Fortunately, the ArcGIS Experience Builder Developer Edition is an extensible, configurable WYSIWYG application for WebGIS apps. The Experience Builder runs on the JavaScript-based server Node.js, which brings the Node Package Manager (NPM) to load external dependencies from the Internet. A package just like this is provided by what3words to use its REST API. We took advantage of this to develop a widget, which is freely available on GitHub.
Clicking on the map sends the click point as a coordinate to the REST API and gets back a response object in GeoJSON format containing the vertices of the square and of course the three-word address, among other information. From this response, the square is drawn on the map and the widget is filled with data. The wrapper in the NPM package of what3words is mostly correctly typed and is therefore comfortable to use with TypeScript. Here is a snippet from the TypeScript Definitions that defines the response object:
export interface LocationProperties {
country: string;
nearestPlace: string;
words: string;
language: string;
map: string;
}
export interface LocationGeoJsonResponse {
bbox: [number, number, number, number];
geometry: {
coordinates: number[];
type: string;
};
type: string;
properties: LocationProperties;
}
In the backend of the Experience Builder, which is the configuration page used to assemble your app out of data sources and widgets, the what3words widget offers a wide range setting options. As usual, a connection to a map widget needs to be established in order to retrieve the click point and visible extent and to draw on the map in return. The aforementioned API Key is stored here and used in the background for every request to the REST API.
When the backend is initialized, it queries the shortcodes of all available languages at what3words. The setting affects the language of the three-word address on the widget and on the map. Other settings are related to the map display as well as the widget display and behavior.
The REST API provides a function to return the grid, but in maximum 4x4 km size. The widget reacts to the zoom level of the map view and checks the geodesic distance of two vertices in larger scales. If it falls below 4 km, the grid is downloaded and created as a client-side FeatureLayer. Numerical values are assigned to all lines, increasing continuously from the click point to the edge of the image. A renderer visualizes a grid based on these values, which appears in what3words' own red at the edge of the image and becomes lighter and more transparent towards the click point.
There are a number of ideas for the future development of the widget: We want so integrate a search functionality by text input, meaning the geocoding of a three-word address. In order not to have to implement a suggestion function manually but to use the Search widget of the ArcGIS API for JavaScript for this purpose, this function could be implemented by using the ArcGIS Locator Services instead of the REST API. Other ideas include converting selected vertices or point features to three-word addresses, or checking which features are in the 3x3 meter square hit by click.
The source code is publicly available on GitHub. If you want to participate, please fork the repository and send a merge request after developing a new feature. Feel free to use the discussion functions on GitHub or here on Esri Community! We’re looking forward to your ideas and maybe even productive uses of the widget!
Here you can find a German version of this article.
Please follow me and GeoDevGermany on Twitter if you liked this content.