We live in a world full of data. It's often hard to tease out the hidden meaning found within it because–in its rawest form–the data is still very abstract. This is particularly true of Geo-based data, where the very elements that give a row of data a sense of location (its “geo-ness”) can be difficult to mentally model. Take latitude and longitude. While they describe precise location, they’re largely useless without a means to plot and calculate over them. Computers are great at this. Humans, not so much. This is where visualizations come to the rescue, revealing a world of interconnectedness that’s often hidden when looked at as raw numbers.
In this post I’ll walk you through how to setup and use Google Maps Platform with deck.gl. We’ll start with a simple “Hello, World!” style introduction to ensure all our plumbing is in order. Then we’ll move to a basic visualization of some real data. And once we’re done, you’ll have sound boilerplate code to work from for future visualizations. Finally, we’ll demonstrate some techniques for interactivity that will help unlock hidden meaning and opportunity.
**Hello, world!**Let’s start by reviewing the simplest of map visualizations using deck.gl. To begin, download the starter project here.
All of the files you’ll need to work with in this tutorial are in the /src directory. The main file we will be looking at is hello-world.html, where you’ll see I’ve already included the code for importing the Maps JavaScript API, as well as using it to initialize and apply some basic styling to the map.
To view this page I recommend using a simple web server. While this page doesn’t absolutely need it, future examples will need some serving mechanism to avoid the dreaded CORS error when loading data and map styles.
To begin, from the command line, go to the directory of the starter project you just downloaded.
Next, run the following from the command line to start a simple web server to serve the project files:
$ python -m SimpleHTTPServer 8000Next, you’ll need to replace YOUR_API_KEY with your actual API key in the script tag at the top of hello-world.html where we're importing the Maps JavaScript API. If you aren’t familiar with how to generate an API key, check out our quick video walkthrough.
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=visualization"></script>Once you’ve done this, you can view the page at:
http://localhost:8000/hello-world.htmlIt should look like this:
**Adding a basic deck.gl visualization**While our map is nice, it’s not exactly ready for exploring real-world use cases. Let’s add a very basic deck.gl visualization: Scatterplot Layer.
To start, we include the unpackaged version of the deck.gl library in the app by adding the following script tag in the <head> section of index.html:
<head>
<title>Google Maps and deck.gl - Hello, World!</title>
<script src="https://unpkg.com/deck.gl@^7.0.0/dist.min.js"></script>
...
</head>Next, in our main script in index.html, you’ll see we have already initialized the map and defined a data point for you:
<script type="text/javascript">
const nyc = { lat: 40.75097, lng: -73.98765 };
const map = new google.maps.Map(document.getElementById('map'), {
center: nyc,
zoom: 14,
disableDefaultUI: true, // de-clutters the UI
zoomControl: true, // brings back zoom controls
styles: mapStyle // use map styles from /styles/map_styles.js
});
</script>The first step in applying deck.gl visualization layers to this map is to import the GoogleMapsOverlay and ScatterplotLayer objects from deck.gl at the top of this script tag:
<script type="text/javascript">
const { GoogleMapsOverlay, ScatterplotLayer } = deck;
...
</script>Next, we initialize GoogleMapsOverlay and pass an instance of the deck.gl ScatterplotLayer layer to it at the bottom of the same script. A "Layer" is a core concept of deck.gl that creates a visualization type that takes data and renders it on a map based on a set of properties that define the look and behavior of the layer.
Here we specify one data point and a radius of 10 meters, then add the overlay to the map:
...
const deckOverlay = new GoogleMapsOverlay({
layers: [
new ScatterplotLayer({
id: 'scatterplot',
data: [{ position: [nyc.lng, nyc.lat, 0], }],
getRadius: 20,
getFillColor: [255, 133, 27]
})
]
});
deckOverlay.setMap(map);The data attribute of deck.gl layers is quite robust. It will take an Iterable (an array of data), String (a URL), Promise or a generic Object (that implements length). For more details on what you can feed a layer see the deck.gl properties documentation.
The end result should be a single lonely marker, lost in the hustle and bustle of the big city.
Scatterplot layer with a single data point
**Adding a datasource**Let’s add some more data from one of BigQuery’s public datasets to create a more meaningful scatterplot visualization. For those new to BigQuery, see this getting started guide to get through the initial setup and to see an example of how to query a public dataset.
We’ll be using New York City’s Citi Bike dataset. Citi Bike is New York City’s bike share system, and the largest in the nation with 10,000 bikes and 600 stations across Manhattan, Brooklyn, Queens, and Jersey City.
To retrieve the data, run the following query in the BigQuery query editor in the Google Cloud console:
SELECT
longitude,
latitude,
name,
capacity
FROM
`bigquery-public-data.new_york_citibike.citibike_stations`Once the query completes, click SAVE RESULTS beneath the query editor, and select JSON (local file) to save the data to your working directory. For this example, we named the file stations.json.
Now let’s tell the layer about this new JSON data source and how to parse the data it contains.
getPosition, getFillColor, and getRadius are our data accessors. They tell the layer how to reach into the data and extract values that it uses to determine how to render different attributes of the visualization. In the case of a ScatterPlot Layer, these accessors allow it to determine place, size, and color for each data point, but you don’t always have to base rendering decisions off of data.
For example, here we are keeping the fill color constant for all rows, but dynamically setting the position and radius of the points based on the data:
const deckOverlay = new GoogleMapsOverlay({
layers: [
new ScatterplotLayer({
id: 'scatterplot',
data: './stations.json',
getPosition: d => [parseFloat(d.longitude), parseFloat(d.latitude)],
getFillColor: d => [255, 133, 27],
getRadius: d => parseInt(d.capacity),
})
]
});Now when we reload the app, our end result visualizes about 800 Citi Bike stations across New York City.
Finished Scatterplot layer
That’s all there is to it. You’ve built your first deck.gl data visualization using data from one of Google Cloud’s BigQuery public datasets. If you ran into any issues, you can also refer to the code in scatterplot.html to see the final code of this tutorial.
In our next post, we’ll pick up where we left off and integrate even more data and some interesting interactivity into this Scatterplot Layer.
For more information on Google Maps Platform, visit our website.
