Grid Section Map Overlay (Google Maps)


The what3words REST API supports the abilty 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 demostrates integrating the what3words grid onto Google Maps. We also have tutorials demonstrating its use with both Mapbox and Leaflet.

Step 1: Obtain a API keys

Sign up to obtain your free what3words API key.

To display the grid on a Google Map, you will also need to obtain a Google API Key.

Step 2: Installation

To load the what3words JavaScript API, use a script tag like the one in the following example:

<script src="https://assets.what3words.com/sdk/v3/what3words.js?key=YOUR_API_KEY"></script>

The key parameter contains your application's API key. Sign up to obtain your free API key.

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

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_API_KEY"></script>

The key parameter contains your Google Maps API key.

Step 3: Map 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>

Step 4: Map Initialisation

Within the body tag, we need to create a new div element to contain the map component, as well as initialise it using the Google Maps JavaScript API.

<div id="map"></div>
<script>
  // Create the Google Map
  let map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 51.52086, lng: -0.195499 },
    zoom: 19
  });
</script>

Step 5: Grid 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 grid section can be requested, we need to obtain a new grid section each time the map is panned or zoomed.

<script>
  var 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
        .gridSectionGeoJson({
          southwest: {
            lat: sw.lat(), lng: sw.lng()
          },
          northeast: {
            lat: ne.lat(), lng: ne.lng()
          }
        }).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,
    });
  });
</script>

Step 6: Putting It All Together

The example below takes the steps listed above, and puts them into a complete, working example.

<html>
  <head>
    <script src="https://assets.what3words.com/sdk/v3/what3words.js?key=YOUR_API_KEY"></script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_API_KEY"></script>

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

      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>

  <body>
    <div id="map"></div>
    <script>
      // Create the Google Map
      let map = new google.maps.Map(document.getElementById("map"), {
        center: { lat: 51.52086, lng: -0.195499 },
        zoom: 19
      });
    </script>
    <script>
      var 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
            .gridSectionGeoJson({
              southwest: {
                lat: sw.lat(), lng: sw.lng()
              },
              northeast: {
                lat: ne.lat(), lng: ne.lng()
              }
            }).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,
        });
      });
    </script>
  </body>
</html>