Developer

All tutorials

Displaying the what3words grid on a Google Map

intermediate

The what3words API supports the ability to obtain a section of the 3m x 3m what3words grid in GeoJSON format, making it very simple to display on a map.

This tutorial will show you how to integrate the what3words grid onto Google Maps. We also have tutorials demonstrating its use with both Mapbox and LeafletJS.

You will also need to sign up for a Google Maps developer account and be able to view other Google Maps tutorials at https://developers.google.com/maps/documentation/javascript/tutorial

1Get API key
2Installation

To load the JavaScript wrapper for the what3words API, use a script tag like the one in the following example. Replace YOUR-API-KEY with your what3words API key to get started.

Note: We prefer to use a fixed version for the Production version of your integrations. A specific version can also be specified within the script to ensure a predictable version of the component is loaded, for example@4.2.1. A log of versions can be found here.

<script src="https://cdn.what3words.com/javascript-components@4.2.1/dist/what3words/what3words.js?key=YOUR_API_KEY"></script>
Copied

The URL contained in the script tag is the location of a JavaScript file that loads everything you need for using the JavaScript wrapper for the what3words API.

The key parameter contains your application’s API key.

You will also need to load the Google Maps API, for example:

    <script>
      ((g) => {
        var h,
          a,
          k,
          p = "The Google Maps JavaScript API",
          c = "google",
          l = "importLibrary",
          q = "__ib__",
          m = document,
          b = window;
        b = b[c] || (b[c] = {});
        var d = b.maps || (b.maps = {}),
          r = new Set(),
          e = new URLSearchParams(),
          u = () =>
            h ||
            (h = new Promise(async (f, n) => {
              await (a = m.createElement("script"));
              e.set("libraries", [...r] + "");
              for (k in g)
                e.set(
                  k.replace(/[A-Z]/g, (t) => "_" + t[0].toLowerCase()),
                  g[k]
                );
              e.set("callback", c + ".maps." + q);
              a.src = `https://maps.${c}apis.com/maps/api/js?` + e;
              d[q] = f;
              a.onerror = () => (h = n(Error(p + " could not load.")));
              a.nonce = m.querySelector("script[nonce]")?.nonce || "";
              m.head.append(a);
            }));
        d[l]
          ? console.warn(p + " only loads once. Ignoring:", g)
          : (d[l] = (f, ...n) => r.add(f) && u().then(() => d[l](f, ...n)));
      })({ key: "GOOGLE-API-KEY", v: "weekly" });
    </script>
Copied

The bootstrap loader prepares the Maps JavaScript API for loading (no libraries are loaded until importLibrary() is called).

The key parameter contains your Google Maps API key.

3Map style

Within the head tag, we need to set style properties for the Google Map. In this example, we’ll set the map to display full screen.

<style>
  #map {
    height: 100%;
  }

  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>
Copied
4Map initialisation

Within the body tag, we need to create a new div element to contain the map component.

<div id="map"></div>
Copied

This section shows you how to load the Maps JavaScript API into your web page and how to construct a new Google Maps object, and adds properties to the map including the center and zoom level. See the documentation for other property options.

The Map library is loaded when the initMap() function is called.

// Initialize and add the map
let map;

async function initMap() {
  const position = { lat: 51.52086, lng: -0.195499 };
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 19,
    center: position,
    mapId: "DEMO_MAP_ID"
  });
}

initMap()
Copied
5Grid overlay

The what3words grid can be displayed on top of a Google Map by passing GeoJSON data to the maps Data object.

Because only a segment of the grid section can be requested, we need to obtain a new grid section each time the map is panned or zoomed.

// Initialize and add the map
let map;

async function initMap() {

  ...

  let gridData;

  // Add the what3words grid to the Google Map data layer once the desired zoom level is meet
  map.addListener("bounds_changed", function () {
    const zoom = map.getZoom();
    const loadFeatures = zoom > 17;

    if (loadFeatures) {
      // Zoom level is high enough
      var ne = map.getBounds().getNorthEast();
      var sw = map.getBounds().getSouthWest();

      // Call the what3words Grid API to obtain the grid squares within the current visble bounding box
      what3words.api
        .gridSection({
          boundingBox: {
            southwest: {
              lat: sw.lat(),
              lng: sw.lng()
            },
            northeast: {
              lat: ne.lat(),
              lng: ne.lng()
            }
          },
          format: "geojson"
        })
        .then(function (data) {
          if (gridData !== undefined) {
            for (var i = 0; i < gridData.length; i++) {
              map.data.remove(gridData[i]);
            }
          }
          gridData = map.data.addGeoJson(data);
        })
        .catch(console.error);
    }

    // Set the grid display style
    map.data.setStyle({
      visible: loadFeatures,
      strokeColor: "#777",
      strokeWeight: 0.5
    });
  });
}

initMap();
Copied
WebsiteUse 3 word addresses with a mapJavaScript

Related tutorials