Skip to main content

Using with Google Maps Platform

Pure JSReactOverlaidInterleaved
✓✓exampleexample

deck.gl as a Google Maps overlay

Integration Modes​

When using deck.gl and Google Maps JavaScript API, there are three options you can choose from: interleaved, overlaid, and reverse-controlled.

Interleaved​

The interleaved mode renders deck.gl layers into the WebGL2 context created by Google's vector map, using the Maps JavaScript API WebGLOverlayView class. If you need to mix deck.gl layers with Maps layers, e.g. having deck.gl objects and Maps 3D buildings occluding each other correctly, then you have to use this option.

Interleaving is supported by using GoogleMapsOverlay with an instance of Google's vector map. Some limitations apply when using this option.

Overlaid​

The overlaid mode renders deck.gl in a separate canvas inside the Maps' controls container, using the Maps JavaScript API OverlayView class.

This is supported by using GoogleMapsOverlay with Google's raster map. When a deck.gl overlay instance is added to the map, if a vector map is not detected or the user's device does not support WebGL2, it will automatically fallback to overlaid mode. You can also explicitly use this mode by setting the option interleaved to false when creating the GoogleMapsOverlay. In this mode, 3D features like tilt, rotation, and fractional zoom are not supported.

Reverse Controlled​

The reverse-controlled mode renders deck.gl above the Maps container and blocks any interaction to the base map. If your use case does not require interleaving, but you need to implement your own pointer input handling, have multiple maps or a map that does not fill the whole canvas (with Deck's multi-view feature), you need this to allow deck.gl manage the map's size and camera.

You cannot use Maps' own UI controls such as the zoom buttons or layer selector with this option. Instead, use the components from @deck.gl/widgets.

Examples​

Example: interleaved or overlaid​

Both the interleaved and the overlaid options are supported in by the @deck.gl/google-maps module. This is recommended approach for developers coming from the Google Maps JavaScript API ecosystem, as it handles fallbacks gracefully, as well as being compatible with other Maps controls and plugins.

import {Loader} from '@googlemaps/js-api-loader';
import {GoogleMapsOverlay} from '@deck.gl/google-maps';
import {ScatterplotLayer} from '@deck.gl/layers';

const loader = new Loader({apiKey: '<google_maps_api_key>'});
const googlemaps = await loader.importLibrary('maps');

const map = new googlemaps.Map(document.getElementById('map'), {
  center: {lat: 51.47, lng: 0.45},
  zoom: 11,
  mapId: '<google_map_id>'
});

const overlay = new GoogleMapsOverlay({
  layers: [
    new ScatterplotLayer({
      id: 'deckgl-circle',
      data: [
        {position: [0.45, 51.47]}
      ],
      getPosition: d => d.position,
      getFillColor: [255, 0, 0, 100],
      getRadius: 1000
    })
  ]
});

overlay.setMap(map);

You can find full project setups in the react get-started example and pure js get-started example.

Example: reverse controlled​

The reverse-controlled option is currently only supported in React when used with the @visgl/react-google-maps library.

import React from 'react';
import {APIProvider, Map} from '@vis.gl/react-google-maps';
import DeckGL from '@deck.gl/react';
import {ScatterplotLayer} from '@deck.gl/layers';

function App() {
  const layers = [
    new ScatterplotLayer({
      id: 'deckgl-circle',
      data: [
        {position: [0.45, 51.47]}
      ],
      getPosition: d => d.position,
      getFillColor: [255, 0, 0, 100],
      getRadius: 1000
    })
  ];

  return <APIProvider apiKey="<google_maps_api_key>">
    <DeckGL
      initialViewState={{
        longitude: 0.45,
        latitude: 51.47,
        zoom: 11
      }}
      controller
      layers={layers}
    >
      <Map mapId="<google_maps_id>" />
    </DeckGL>
  </APIProvider>;
}

Additional Information​

react-google-maps​

@visgl/react-google-maps is a React wrapper around Google Maps JavaScript API maintained by the vis.gl community. If you'd like to use deck.gl together with Google Maps and React, this library is the recommended companion.

When you choose the interleaved or overlaid option, the @visgl/react-google-maps Map React component acts as the root component, and GoogleMapsOverlay is used with a useMemo hook.

When you choose the reverse-controlled option, the DeckGL React component acts as the root component, and the @visgl/react-google-maps Map is a child. In this case, Map will automatically interpret the deck.gl view state (i.e. latitude, longitude, zoom etc), so that deck.gl layers will render as a synchronized geospatial overlay over the underlying map.

Google Maps Platform API key​

Note that to use deck.gl with the Google's basemap, you must load the Maps JavaScript API using a valid API key. For more information on getting an API key, see the Google Maps Platform API key documentation for the Maps JavaScript API.

If you are using @visgl/react-google-maps, supply the API key to the APIProvider and wrap it around all components that should have access to the Google Maps API.