All tutorials
Displaying the what3words grid on a Google Map
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
Installation
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>
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>
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.
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>
Map initialisation
Within the body
tag, we need to create a new div element to contain the map component.
<div id="map"></div>
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()
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 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();