How to use HERE-hosted what3words API

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

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

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

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

        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.

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.

        function callingHEREW3W(coord){
  const apiUrl = 'https://what3words.search.hereapi.com/v3/convert-to-3wa';

  // Set up query parameters
  const queryParams = {
    coordinates: ''+coord.lat+','+coord.lng,
    language: 'en',
    format: 'json',
    apiKey: window.apikey,
  };

  // Convert query parameters to a string
  const queryString = new URLSearchParams(queryParams).toString();

  // Combine API endpoint with query parameters
  const fullUrl = `${apiUrl}?${queryString}`;

  // Make a GET request using the Fetch API
  fetch(fullUrl)
    .then(response => {
      if (!response.ok) {
        throw new Error('Network response was not ok');
      }
      return response.json();
    })
    .then(data => {
      // Process the list of recent users
      console.log('Response: ', data);
      logEvent("whats3words : " + data.words);
      setCenter(data.coordinates);
      drawRectangle(data.square.northeast, data.square.southwest);
    })
    .catch(error => {
      console.error('Error:', error);
    });
  }
  

Here is the sample request generated to the endpoint:

        https://what3words.search.hereapi.com/v3/convert-to-3wa?coordinates=34.0628512262729%2C-118.18453169977087&language=en&format=json&apiKey=<apikey>
  

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.

        {
    "country": "US",
    "square": {
        "southwest": {
            "lng": -118.184538,
            "lat": 34.06285
        },
        "northeast": {
            "lng": -118.184505,
            "lat": 34.062877
        }
    },
    "nearestPlace": "Los Angeles, California",
    "coordinates": {
        "lng": -118.184521,
        "lat": 34.062864
    },
    "words": "detail.discrepancy.keep",
    "language": "en",
    "map": "https:\/\/w3w.co\/detail.discrepancy.keep"
}
  

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

• Press Release: HERE Technologies x whats3words
• HERE What3Words Tutorial: One Box Search
• HERE Maps API for Javascript Sample: Calculating a Location from a Mouse Click