Description

The unofficial Runkeeper API - Pretty much hacked, but better than nothing

Requirements

PHP 5+, json_decode(), cURL, Runkeeper Account

Details

This API is a hack that will allow you to log into your Runkeeper.com account and get your miles, calories, pacing, speed (mph), your street team members, their stats, keeps logs, local cache, etc.

To use the API you must meet the requirements above.

Create your object

/**
Arguments
--------------
Email     (string)  = Your email address for RK
Password  (string)  = Your password
Username  (string)  = Your username used on the site
Keep Logs (boolean) = Set to true to keep logs, false to not (defaults to true)
Use Cache (boolean) = Set to true to use local cache, false to not (default to true)

Return
--------------
N/A

Cached
--------------
N/A

Notes
--------------
If not storing the stats in a local DB, use cache. It cuts back call time from about
50 seconds to 0.03.
**/

$rk = new Runkeeper('EMAIL', 'PASSWORD', 'USERNAME', KEEP_LOGS, USE_CACHE);

Get your street team members (never cached)

/**
Arguments
--------------
Action (string)  = street_team

Return
--------------
Associative array with [$username] => $real_name
Array
(
  [jason] => Jason Jacobs
  [phpfunk] => Jeff Johns
  [asdiet] => Annie
  ...
)

Cached
--------------
No, never

Notes
--------------
This includes your username to make it easy to loop through stats if so desired.
**/

$street_team = $rk->get('street_team');

Extracting Calories, Pace, Miles, Speed and Stats

For each of the above they are all called the same way. You use the get() method and submit the first argument as the action and an array of data for the second. That array of data can be used to narrow down the data returned.

Example:
$calories = $rk->get('calories', array(
  'username'  =>  'phpfunk',
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'variance'  =>  .25,
  'min_date'  => '05/01/2011',
  'max_date'  => '05/31/2011'
));

Those are the keys you can submit for each method in the heading above. None of which are required. They can all be used to narrow down the data to be returned.

Explanation
--------------
username    =>  The username to get the data for
  - Defaults to your username
  
type        =>  The type of activity to extract (walk, run, etc)
  - Defaults to ALL
  
distance    =>  The distance to use
  - You can use the =, >, <, >= or <= symbols for distance
  - Defaults to ALL
  
variance    =>  If you want to extract all 5Ks but want to allow for overage, set the overage here
  - Defaults to 0
  
min_date    =>  The minimum date to extract data from
  - Defaults to the 1st of the current month
  
max_date    =>  The maximum date to extract data from
  - Defaults to the current data

Extract your calories

/**
Arguments
--------------
Action  (string) =  calories
Options (array)  =  see explanation above


Return
--------------
Array
(
  [activity] => Array
      (
          [1307176800] => Array
              (
                  [date] => 06/04/2011
                  [calories] => 931
              )
          ...
      )

  [total] => 1573
  [most] => 931
  [least] => 642
  [average] => 786.50
)

Cached
--------------
Yes

Notes
--------------
Will also return average, total, most and least calories earned.
**/

$calories = $rk->get('calories', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

Extract your pacing

/**
Arguments
--------------
Action  (string) =  pace
Options (array)  =  see explanation above


Return
--------------
Array
(
  [activity] => Array
      (
          [1307176800] => Array
              (
                  [date] => 06/04/2011
                  [pace] => 8:33
              )
          ...
      )

  [fastest] => 7:52
  [slowest] => 8:33
  [average] => 8:13
)

Cached
--------------
Yes

Notes
--------------
Will also return average, fastest and slowest pace.
**/

$pace = $rk->get('pace', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

Extract your miles

/**
Arguments
--------------
Action  (string) =  miles
Options (array)  =  see explanation above


Return
--------------
Array
(
  [activity] => Array
      (
          [1307176800] => Array
              (
                  [date] => 06/04/2011
                  [distance] => 8.19
              )
          ...
      )

  [total] => 13.26
  [longest] => 8.19
  [shortest] => 5.07
  [average] => 6.63
)

Cached
--------------
Yes

Notes
--------------
Will also return average, total, longest and shortest miles.
**/

$miles = $rk->get('miles', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

Extract your speed

/**
Arguments
--------------
Action  (string) =  speed
Options (array)  =  see explanation above


Return
--------------
Array
(
  [activity] => Array
      (
          [1307176800] => Array
              (
                  [date] => 06/04/2011
                  [speed] => 7.02
              )
          ...
  [fastest] => 7.63
  [slowest] => 7.02
  [average] => 7.33
)

Cached
--------------
Yes

Notes
--------------
Will also return average, fastest and slowest speed.
**/

$speed = $rk->get('speed', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

Extract all stats

/**
Arguments
--------------
Action  (string) =  stats
Options (array)  =  see explanation above


Return
--------------
Array
(
  [1307176800] => Array
      (
          [distance] => 8.19
          [pace] => 8:33
          [calories] => 931
          [duration] => 1:10:00
          [speed] => 7.02
          [elevation] => 786
          [type] => RUN
      )
  ...
)

Cached
--------------
Yes

Notes
--------------
Have fun.
**/

$stats = $rk->get('stats', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

Get total miles in June for your entire street team

$street_team = $rk->get('street_team');
foreach ($street_team as $username => $fqn) {
  $miles = $rk->get('miles', array(
    'username' => $username,
    'type'     => 'run',
    'min_date' => '06/01/2011'
  ));

  print 'RUNNER: ' . $fqn . ' (' . $username . ') ran ' . $miles['total'] . ' miles in June.<BR>';
}

/**
Example :: 
RUNNER: Jason Jacobs (jason) ran 18.98 miles in June.
RUNNER: Jeff Johns (phpfunk) ran 13.26 miles in June.
RUNNER: Annie (asdiet) ran 3.1 miles in June.
**/

Get the raw data

For every call the application goes out and grabs all the activity json URLs and extracts the data. If you want to use the raw data feeds, you can simply call the $rk->json variable and see all the data.

$stats = $rk->get('stats', array(
  'type'      =>  'run',
  'distance'  =>  '>=3.1',
  'min_date'  => '06/01/2011'
));

print '<pre>';
print_r($rk->json);
print '</pre>';