EXPEDIA GROUP TECHNOLOGY — DATA
Hello, Map Maker!
A Python package to make interactive maps from tabular data
Here at Expedia Group™, geography is obviously a pretty important part of what we do. We spend a lot of time studying where people like to go, what they like to see, and what the easiest and best ways are to get there. We’ve written a bit about how we approach these problems computationally and mathematically in our Unified Geo Data Layer series (part 1 and part 2). Today we’re happy to share another part of our geo toolkit — Map Maker, a Python package for easily creating interactive maps from structured tabular data. We’ve been using Map Maker internally at Vrbo and Expedia Group for about three years now, and we’re pleased to announce that it is now open source.
We wrote it because producing interactive maps from within Python is pretty challenging and code intensive. Even the simple tools have fairly complicated APIs for creating very specific map types (like choropleths), or require very specific data formats (like a GeoJSON FeatureCollection) that weren’t always easy to work with. We wanted something very simple that could take some data in a format we already had (or close to it) and convert it to something Bokeh or Folium could display. That’s what Map Maker does.
Read on for a very simple walkthrough.
Map Maker, the library
For this walkthrough we’re going to work with a highly relevant dataset that most people have worked with already: Bigfoot sightings. Specifically, Bigfoot sightings in Texas (just to keep it simple). There’s a csv file here in the repository if you want to see the entire thing, but we’ll cover the basics of this file here. These are the first few rows.
A quick rundown of the fields before we start going into the Map Maker library. shape is a column of WKT encoded geometries. It is required for Map Maker, and represents the shape to draw. Map Maker supports points, lines, multipoints, multilines, polygons and multipolygons. It also supports GeoJSON for encoding shapes at the command line, and Shapely polygons of geo-interface dictionaries as a library. Shape is the only column required by Map Maker, but there are others it can use if needed.
color is the color to make the shape. It’s passed directly to the underlying mapping library. alpha is the opacity, and should always be between zero and one. The other two columns, date and classification[1], are part of the dataset itself, and will be turned into tooltips.
The following quick walkthrough is also available as a notebook in the repo. Obviously the notebooks have a little more detail than we’ll present here.
Start by loading the data into a pandas DataFrame.
Map Maker needs the data as a list of dictionaries. That’s easy enough with DataFrame’s to_dict() method. It looks like this:
It’s much simpler than GeoJSON or shapefiles. Once the data’s in the right format, just call make_map_plot on it. I’ve also set the height/width of the map to something a little more reasonable.
And that’s it. The elements of the list don’t need to be homogeneous either. There’s a second file with slightly different columns in the repo as well, texas_cities.csv. It looks like this:
Note it has city and size, which the points don’t have. city becomes a tooltip, but size is used by Map Maker to draw the width of the lines (since these are polygons and linestrings — for points it would be the size of the points). Combining these two datasets into a single list to draw the map is very simple. I’ve thrown in a couple of other arguments for turning on the tooltips for all geometry types and setting the point size to make them a little larger.
Map Maker doesn’t just work with Bokeh. It can also draw maps with Folium too. All you have to do is change the import.
Instead of a Bokeh object, the Folium version of make_map_plot returns a Folium Map object. So if you don’t want to mess with the heavier Bokeh stuff, the Folium version works just as well. We hope to add more backends, particularly Cartopy (so we don’t destroy our browsers for large maps), in the future.
Map Maker, the command line tool
Map Maker doesn’t need to be run in a notebook or a Python script either. It comes bundled with a command line tool that takes one or more CSV files (having the same structure mentioned above), and produces the same map as a standalone HTML file. The command is very simple (assuming your data is in the data/ directory).
The command produces a map.html file and opens a browser window with the same map shown above. By default it uses Bokeh, but there’s a flag that lets you switch to Folium if you’d like. Check out the repo for more information.
Comparison to other interactive mapping tools
There are a number of mapping tools out there for Python already. Here’s an incomplete list:
Most of these fall into one of two categories (or with APIs for both): a full GIS plotting apparatus, complete with customizable projections, etc, or a high level interface for the most commonly used map types that performs the necessary computations through its API. Map Maker sits in the middle of these — it doesn’t allow customizable projections because for simple interactive maps the Web Mercator system is good enough. It also assumes if there are aggregations or other custom calculations that need to be performed, the user can do that themselves, including mapping the color scales (though we could add some support for this in the future).
The whole point of Map Maker is to make it very simple to create maps. It does this by removing the heavy GIS stuff like projections, and having a very simple data format that is easy to remember. So if you want quick maps that don’t require a lot of googling for data formats and APIs, or you need a command line tool for producing standalone map files, Map Maker is a good choice.
Future work
There are a few obvious improvements we can start working on. The first is to support Cartopy. This is important in allowing Map Maker to build maps that are too big for the browser. There’s been some work already in this area but the installation process for the more GIS-heavy libraries can get very tricky. Another is to support directly passing pandas DataFrames. That would be pretty quick. Finally, support for simple color coding would be a nice usability improvement.
If any of that seems interesting, feel free to raise an issue or open a pull request.
Links!
- Github Repo: github.com/ExpediaGroup/map-maker
- API Docs: expediagroup.github.io/map-maker
- Example Notebooks: github.com/ExpediaGroup/map-maker/tree/main/notebooks
[1] The BFRO report classification system is a way of cataloging evidence. Class A is a direct, clear sighting, Class B is evidence without clear visual observation (footprints, howls, etc), and Class C is a secondhand report. Read more about it on the BFRO website.
