Runkeeper API
***This API has been depreciated. This used an old method of screen scraping runkeeper.com to obtain the run information. Runkeeper has made changes to their pages which breaks this method. I’m working on a new program which uses the official Runkeeper HealthGraph API, which will be much more reliable. Stay tuned!***
Overview
I’ve been working on an interface in to Runkeeper that has garnered some interest in the Runkeeper Forums. The purpose of the interface is to capture and save information about each run that Runkeeper has tracked. The data can then be manipulated, summed, graphed, etc. in many ways. I, for example, utilize this data in a WordPress Widget to produce the data in the right sidebar of this blog entitled, MY RUNS.
Runkeeper does not provide a published API. The interface that I developed is written in PHP and utilizes a combination of screen scraping and JSON retrieval to capture as much data about the run as possible. Data captured is stored in two MYSQL tables within one database:
- The first table contains summary information about each run; date/time, distance, duration, calories burned, and weather conditions. This data is used to produce all of the data in the right sidebar including, weekly, monthly, yearly, and individual run information.
- The second table contains detail information about each run, that is information pertaining to each point that is captured by Runkeeper. This data includes, the latitude/longitude of each point, the elevation of each point, the distance between points, and the speed between points. This data can be used for graphing, and mapping, individual runs.
It should be noted that although all of the detail information is stored in the second table, it is currently not being used by the WordPress widget to produce the graphs that you see by hovering over the headings in the right sidebar. These graphs were produced when the interface was run, as the data was being manipulated and stored in the tables, and are stored as .png files within the webserver filesystem. There was no reason to do this in real time when the page was loaded, and doing it in batch significantly improves page loading time. In my configuration I run this interface via cron once per day, where it picks up all new runs, stores the summary and detail information in the db, and generates the individual, weekly, monthly, and yearly graphs. The detail table exists to ensure that the Runkeeper user has ALL data pertaining to their runs available to them. This data is also useful in case graphs need to be regenerated or if other uses of the data are discovered.
Version
This is version 0.1 of the Runkeeper interface.
Requirements / Prerequisites
I’m running the runkeeper.php interface on Ubuntu Lucid Lynx (10.04LTS), with PHP Version 5.3.2 and MySql version 5.1.41. There is no reason to believe that it wouldn’t work under different operating systems and/or different versions of PHP and MySql, but YMMV.
Additional packages required:
- Simplehtmldom – An easy to use HTML DOM parser written in PHP. The library can be downloaded from http://simplehtmldom.sourceforge.net/.
- ZEND Framework – This is used to POST login information to Runkeeper and to keep track of login cookies for subsequent access. Download from http://www.zend.com/en/community/downloads.
- Jpgraph – This is a php based graphing package and can be downloaded from http://jpgraph.net/download/.
There is a file included in the tar.gz that is named runkeeper.sql. If you use this as input to phpmyadmin import, or to a command-line mysql source command, it will create the required tables for you.
Download
Download the gzipped tar-ball here:
http://www.firehole.us/rungraphs/distribute/runkeeper_interface.tar.gz
License
This software is “Free as in speech and free as in beer” and is licensed under the GPL v3, so have at it!
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.For a copy of the GPL license see http://www.gnu.org/licenses/.
