Maps are one of the oldest and most powerful forms of visualization. Lately I’ve been learning how to make my own maps using open source data and public APIs.
I started by simply plotting locations on a world map. World maps in svg format are readily available on the web. Wikimedia Commons, for example, has free maps in a variety of formats. The simplest is an equirectangular projection.
It’s dirt simple to plot locations on an equirectangular map: longitudes are X and latitudes are Y. All you have to do is scale your svg to the size you want and then multiply your X and Y values by a zoom factor to match.
Comparison of map projections
But most mapping applications (Google, Open Street Maps, etc.) prefer the Mercator projection, or to be more precise, the web mercator or “spherical pseudo-Mercator”. Converting latitudes and longitudes requires a bit of trigonometry, but not much. For my projects I chose a map from amcharts which is free with attribution for non-commercial uses.
If you look inside this svg file you will find a nice surprise: each country is individually tagged. Among other things, this makes it easy to color code each country by region or anything else. Here is a region map I made:
Individual countries colored by region
By adding just a bit of css and javascript, you can also use these tags to make a map interactive, with rollovers and click actions. For a nice tutorial on how to do this, see this article from Smashing Magazine.
I’ve built all my maps using NodeBox. NodeBox lets me import svgs, slice them up, and layer in additional information from data imported from csv or json files. Here, for example, is a map of locations and timezones I made for a work project I did a few years ago:
World map with city bubbles and time zone bars
The blue and red dots represent cities where workers were located. In order to place them, I needed latitudes and longitudes for each one. Since my data file only had city names, I had to look up each city and enter the coordinates by hand. This was before I learned about the marvels of public APIs. (For another example of what you can do with public APIs, see Fun With FaceBook.)
As you might expect, Google has a very polished and complex set of public APIs. Give one of these APIs a city name and it will spit back its latitude and longitude; give it a thousand cities and it will do the same in the blink of an eye. To try this out, I decided to make a new map of Oracle offices around the world using an old spreadsheet I had lying around. This spreadsheet had 146,000 rows of employee data which referenced 403 distinct city names.
The first challenge when using Google APIs is figuring out which API family to enable. There are currently 17 different families, each with different pricing plans. Most APIs are free up to a certain number of requests per day.
For this project I needed the Web Services Geocoding API. In order to use it, I first needed to get an API key, which requires a credit card (even for free requests). I thought my request would be free, but accidentally went over my limit, incurring a charge of $3.75. So proceed with caution.
Once you have an API key, the request itself is straightforward; you can even just type it into a browser if you want:
https://maps.googleapis.com/maps/api/geocode/json?address=LOOKUP_STRINGkey=YOUR_API_KEY
For lookup sting I just fed it a list of city names from my CSV (with spaces replaced by plus signs). Results are returned in JSON format with a hierarchy of values including short name, long name, etc. One of these, location, gives you latitude and longitude. You can query for that using JSONPath notation: e.g. $.results[0].geometry.location
Once you have the latitudes and longitudes, and the formula to convert these into Y and X coordinates, it’s a simple matter to plot city dots on your svg world map. Here is my final result:
World map with 403 city locations
Google’s API is a simple thing, but it makes maps like this much faster and easier to create. It’s a nice example of the ways in which public API data can augment and complement existing enterprise reporting tools, filling gaps in the available data.
Plotting locations on pre-existing maps is just the beginning. In my next installment I will roll up my sleeves and really start to make maps of my own. Stay tuned!
