HERE Technologies LogoHERE
HERE Technologies LogoHERE
HERE Technologies LogoHERE
APIs

7 min read

07 March 2024

How to use HERE-hosted what3words API

hero w3w

Earlier this year, we announced an expansion of our global partnership with an innovative addressing system what3words. As of this year, users of the HERE platform's Location Services APIs can seamlessly activate their what3words license via HERE. In this blog post, we will explore the integration of what3words addresses within HERE Location Services.

HERE-hosted what3words API

The HERE-hosted what3words API introduces an alternative geocoding system designed to pinpoint any location on Earth. Dividing the world into a grid of 57 trillion 3-by-3-metre squares, each square is assigned a unique three-word address. For instance, the front door of HERE's Berlin office is identified as "///wage.mere.heap."

The HERE-hosted what3words API facilitates the conversion of 3-word addresses to coordinates and vice versa. It incorporates a robust AutoSuggest feature that validates and autocorrects user input, restricting it to specific geographical areas. Additionally, users can request a section of the what3words grid in GeoJSON format for display on online maps and obtain an up-to-date list of supported languages.

All coordinates adhere to standard WGS-84 latitude and longitude pairs, commonly used in GPS systems. Latitude values must fall within the -90 to 90 range.

Endpoints

Endpoints

Description

Sample Request 

Convert to 3 word address

This function converts a latitude and longitude to a 3 word address, in the language of your choice. It also returns country, the bounds of the grid square and a nearby place (such as a local town).

https://what3words.search.hereapi.com/v3/convert-to-3wa?coordinates=51.44401%2C5.48052&apiKey=[YOUR-API-KEY]&language=en&format=json

Convert to coordinate

This function converts a 3 word address to a latitude and longitude. It also returns country, the bounds of the grid square, a nearest place (such as a local town) and a link to our map site.

https://what3words.search.hereapi.com/v3/convert-to-coordinates?words=browser.knitted.elaborate&apiKey=[YOUR-API-KEY]&format=json

Autosuggest

AutoSuggest can take a slightly incorrect 3 word address and suggest a list of valid 3 word addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritise results that are near the user (see Clipping and Focus, below).

https://what3words.search.hereapi.com/v3/autosuggest?input=film.crunchy.spiri&key=[YOUR-API-KEY]

Grid section

Returns a section of the 3m x 3m what3words grid for a bounding box. The bounding box is specified by lat,lng,lat,lng as south,west,north,east. You can request the grid in GeoJSON format, making it very simple to display on a map.

https://what3words.search.hereapi.com/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json

Use Case 1: One box search navigation

Detailed in this tutorial, this use case involves regex pattern detection, AutoSuggest for location suggestions, and converting the selected 3-word address to coordinates.

image 04

Use Case 2: Finding what3words address from a given location

A scenario not covered in the tutorial involves creating a web mapping application to find what3words addresses based on a given location. 

So I created the sample web mapping application below to show how to do just that, based on an existing this HERE Maps API for Javascript sample : Calculating a Location from a mouse click. This sample takes a click input in the map, then translate that in to a coordinate (lat and long), and I extended the sample to use the returned coordinate to show the what3words address for that location as shown below. 

Below is the supplementary code that executes a REST call to the "convert to 3 words address" endpoint using the coordinate: 

This function constructs a URL with appropriate query parameters, including the coordinates in latitude and longitude format, the desired language, and the API key. It then makes a GET request to the specified endpoint using the Fetch API. Upon receiving a response, it processes the data, logging the what3words address, setting the center coordinates, and drawing a rectangle based on the northeast and southwest bounds of the grid square. Any errors encountered during the process are caught and logged for further investigation.

https://what3words.search.hereapi.com/v3/convert-to-3wa?coordinates=51.44401%2C5.48052&apiKey=[YOUR-API-KEY]&language=en&format=json

Here is the sample request generated to the endpoint:

This request includes the coordinates 34.0628512262729, -118.18453169977087, specifying the location for which the what3words address is desired. Additionally, it specifies the desired language as English and the response format as JSON, along with the API key for authentication.

https://what3words.search.hereapi.com/v3/convert-to-coordinates?words=browser.knitted.elaborate&apiKey=[YOUR-API-KEY]&format=json

Here is the sample response received from the endpoint:

This response provides detailed information about the specified coordinates. It includes the country (US), the bounds of the grid square, the nearest place (Los Angeles, California), the coordinates, the corresponding what3words address ("detail.discrepancy.keep"), the language of the response (English), and a link to view the location on a map.

https://what3words.search.hereapi.com/v3/autosuggest?input=film.crunchy.spiri&key=[YOUR-API-KEY]

Closing Thought

The integration of what3words addresses with HERE Location Services offers exciting possibilities. Give it a try and explore the seamless convergence of these powerful location technologies.

Resources

Portrait of Erwin Soekianto

Erwin Soekianto

Developer Evangelist

Share article

Sign up for our newsletter

Why sign up:

  • Latest offers and discounts

  • Tailored content delivered weekly

  • Exclusive events

  • One click to unsubscribe