Visualizing running data through aggregation with hexagonal binning
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Visualizing running data through aggregation with hexagonal binning

Output of hexruns for the author's runs in Worcester, MA. Binning to a grid size of 28 × 28 hexes.

To see hexruns in action, check out this blog post and the other posts in the "running" tag.

Its rough purpose is to extract locations from GPS (or whatever it actually is that RunKeeper uses to track your location) tracks, filter to those in a compact area (e.g., Providence, RI), display them in a 2-d histogram with hexagonal binning, and superimpose over a map for context.

A current area of active work is finding colormaps that convey useful information about duration and pace when overlaid on the various map types that the Google Static Maps API makes available. I've found this guide useful but I'm still a long way from a really satisfying solution.


  1. Make sure you have a working Python 3.x setup and all the requirements listed below. (Alternatively, just use the error messages to figure out what needs to be installed.)
  2. Place the script in a directory with the runs to be analyzed. If acquired from RunKeeper's data export, these should all have filenames and contents that the script won't choke on.
  3. Make it executable: chmod u+x
  4. Acquire a Google public API key, as per these instructions.
  5. Place the API key into a file: echo "YOUR-KEY" > google_public_api_key.
  6. Run the script, e.g., ./ "Providence, RI".

For more control over the output, take a look at ./ --help.

TODO: Switch to a smoother install by running the following commands in a destination directory:

git clone
cd hexruns/
./ install