Fitness Activities
Introduction
Fitness activities appear in a user’s fitness feed on the RunKeeper website. Fitness activities take one of several forms, depending upon whether they reflect past events, newly-completed events, or in-progress events (“live activities”). Fitness activities are grouped in reverse chronological order in a fitness activity feed.
Note: The term “fitness activity” is historical. With the addition of strength training activities, fitness activities will likely be renamed “cardio activities.” Any such change will retain backwards compatibility with existing applications.
Feed
Because a user’s activity feed can grow very large, feeds are divided into pages. Each page contains links to the previous and next pages as well as the total number of activities across all pages. Each page of a user’s activity feed has the following structure:
| Field | Type | Description |
|---|---|---|
size |
Integer |
The total number of fitness activities across all pages |
items |
Item[] |
The user’s activities, from newest to oldest |
previous |
String |
The URI of the previous page in the user’s feed (omitted for the oldest page) |
next |
String |
The URI of the next page in the user’s feed (omitted for the newest page) |
Past Activities
Past activities have the following structure:
Note: The URIs for individual nearest-in-time measurements continue to use the "old" measurement format.
| Field | Type | Description | Editable |
|---|---|---|---|
uri |
String |
The URI for this activity | N |
userID |
Integer |
The unique ID of the user for the activity | N |
type |
String |
The type of activity, as one of the following values: Running,
Cycling, Mountain Biking, Walking,
Hiking, Downhill Skiing, Cross-Country
Skiing, Snowboarding, Skating, Swimming,
Wheelchair, Rowing, Elliptical,
Other |
Y |
secondary_type |
String |
The secondary type of the activity, as a free-form string
(max. 64 characters). This field is used only if the type
field is Other."
|
Y |
equipment |
String |
The equipment used to complete this activity, as one of
the following values: None, Treadmill,
Stationary Bike, Elliptical, Row
Machine. (Optional; if not specified, None is
assumed.)
|
Y |
start_time |
String |
The starting time for the activity (e.g., Sat,
1 Jan 2011 00:00:00)
|
Y |
total_distance |
Double |
The total distance traveled, in meters | Y |
distance |
Distance[] |
The sequence of time-stamped distance measurements (empty if not available) | N |
duration |
Double |
The duration of the activity, in seconds | Y |
average_heart_rate |
Integer |
The user’s average heart rate, in beats per minute (omitted if not available) | Y |
heart_rate |
HeartRate[] |
The sequence of time-stamped heart rate measurements (empty if not available) | Y |
total_calories |
Double |
The total calories burned (omitted if not available) | Y |
calories |
Calories[] |
The sequence of time-stamped caloric burn measurements (empty if not available) | N |
climb |
Double |
The total elevation climbed over the course of the activity, in meters | N |
notes |
String |
Any notes that the user has associated with the activity | Y |
is_live |
Boolean |
Whether this activity is currently being tracked via RunKeeper Live | N |
path |
WGS84[] |
The sequence of geographical points along the route (empty for stationary activities) | Y |
images |
Image[] |
The sequence of images along the route (empty if not available) | N |
share |
String |
The visibility of this activity to
others, as one of the following values: "Just Me", "Street
Team", "Everyone"
|
N |
share_map |
String |
The visibility of this activity's routes to others,
as one of the following values: "Just Me", "Street
Team", "Everyone"
(omitted if the activity has no routes)
|
N |
source |
String |
The name of the application that last modified this activity | N |
entry_mode |
String |
The mode by which this activity was originally entered, as one of the
following values: API, Web |
N |
activity |
String |
The URL of the user’s public, human-readable page for this activity | N |
comments |
String |
The URI of the comment thread for this activity | N |
previous |
String |
The URI of the previous activity in the user’s fitness feed (omitted for the oldest activity) | N |
next |
String |
The URI of the next activity in the user’s fitness feed (omitted for the most-recent activity) | N |
nearest_teammate_fitness_activities |
String[] |
The URIs of the fitness activities closest in time to this activity for each friend (empty if no fitness activities have been recorded) | N |
nearest_strength_training_activity |
String |
The URI of the strength training activity closest in time to this activity for the user (omitted if no strength training activities have been recorded) | N |
nearest_teammate_strength_training_activities |
String[] |
The URIs of the strength training activities closest in time to this activity for each friend (empty if no strength training activities have been recorded) | N |
nearest_background_activity |
String |
The URI of the background activity closest in time to this activity for the user (omitted if no background activities have been recorded) | N |
nearest_teammate_background_activities |
String[] |
The URIs of the background activities closest in time to this activity for each friend (empty if no background activities have been recorded) | N |
nearest_sleep |
String |
The URI of the sleep measurements closest in time to this activity for the user (omitted if no sleep measurements have been taken) | N |
nearest_teammate_sleep |
String[] |
The URIs of the sleep measurements closest in time to this activity for each friend (empty if no sleep measurements have been taken) | N |
nearest_nutrition |
String |
The URI of the nutrition measurement closest in time to this activity for the user (omitted if no nutrition measurements have been taken) | N |
nearest_teammate_nutrition |
String[] |
The URIs of the nutrition measurement closest in time to this activity for each friend (empty if no nutrition measurements have been taken) | N |
nearest_weight |
String |
The URI of the weight measurement closest in time to this activity for the user (omitted if no weight measurements have been taken) | N |
nearest_teammate_weight |
String[] |
The URIs of the weight measurements closest in time to this activity for each friend (empty if no weight measurements have been taken) | N |
nearest_general_measurement |
String |
The URI of the general measurement measurement closest in time to this activity for the user (omitted if no general measurements have been taken) | N |
nearest_teammate_general_measurements |
String[] |
The URIs of the general measurements closest in time to this activity for each friend (empty if no general measurements have been taken) | N |
nearest_diabetes |
String |
The URI of the diabetes measurement closest in time to this activity for the user (omitted if no diabetes measurements have been taken) | N |
nearest_teammate_diabetes |
String[] |
The URIs of the diabetes measurements closest in time to this activity for each friend (empty if no diabetes measurements have been taken) | N |
Past activities are also available in a summary form that is more conducive to bandwidth-constrained environments. This form is as follows:
| Field | Type | Description | Editable |
|---|---|---|---|
uri |
String |
The URI for this activity | N |
userID |
Integer |
The unique ID of the user for the activity | N |
type |
String |
The type of activity, as one of the following values: Running,
Cycling, Mountain Biking, Walking,
Hiking, Downhill Skiing, Cross-Country
Skiing, Snowboarding, Skating, Swimming,
Wheelchair, Rowing, Elliptical,
Other |
Y |
secondary_type |
String |
The secondary type of the activity, as a free-form string
(max. 64 characters). This field is used only if the type
field is Other."
|
Y |
equipment |
String |
The equipment used to complete this activity, as one of
the following values: None, Treadmill,
Stationary Bike, Elliptical, Row
Machine. (Optional; if not specified, None is
assumed.)
|
Y |
start_time |
String |
The starting time for the activity (e.g., Sat,
1 Jan 2011 00:00:00)
|
Y |
total_distance |
Double |
The total distance traveled, in meters | Y |
duration |
Double |
The duration of the activity, in seconds | Y |
average_heart_rate |
Integer |
The user’s average heart rate, in beats per minute (omitted if not available) | Y |
total_calories |
Double |
The total calories burned | Y |
climb |
Double |
The total elevation climbed over the course of the activity, in meters | N |
notes |
String |
Any notes that the user has associated with the activity | Y |
is_live |
Boolean |
Whether this activity is currently being tracked via RunKeeper Live | N |
share |
String |
The visibility of this activity to
others, as one of the following values: "Just Me", "Street
Team", "Everyone"
|
N |
share_map |
String |
The visibility of this activity's routes to others,
as one of the following values: "Just Me", "Street
Team", "Everyone"
(omitted if the activity has no routes)
|
N |
source |
String |
The name of the application that last modified this activity | N |
entry_mode |
String |
The mode by which this activity was originally entered, as one of the
following values: API, Web |
N |
activity |
String |
The URL of the user’s public, human-readable page for this activity | N |
This form can be requested by setting the Accept header to application/vnd.com.runkeeper.FitnessActivitySummary+json in the HTTP GET request.
Newly-Completed Activities
Applications can submit newly-completed activities for inclusion in a user’s fitness feed (they appear as past activities upon retrieval). Newly-completed activities have the following structure:
| Field | Type | Description |
|---|---|---|
type |
String |
The type of activity, as one of the following values: Running,
Cycling, Mountain Biking, Walking,
Hiking, Downhill Skiing, Cross-Country
Skiing, Snowboarding, Skating, Swimming,
Wheelchair, Rowing, Elliptical,
Other |
secondary_type |
String |
The secondary type of the activity, as a free-form string
(max. 64 characters). This field is used only if the type
field is "Other."
|
equipment |
String |
The equipment used to complete this activity, as one of
the following values: None, Treadmill,
Stationary Bike, Elliptical, Row
Machine. (Optional; if not specified, None is
assumed.)
|
start_time |
String |
The starting time for the activity (e.g., Sat,
1 Jan 2011 00:00:00)
|
total_distance |
Double |
The total distance traveled, in meters (optional) |
duration |
Double |
The duration of the activity, in seconds |
average_heart_rate |
Integer |
The user’s average heart rate, in beats per minute (optional) |
heart_rate |
HeartRate[] |
The sequence of time-stamped heart rate measurements (optional) |
total_calories |
Double |
The total calories burned (optional) |
notes |
String |
Any notes that the user has associated with the activity |
path |
WGS84[] |
The sequence geographical points along the route (must have at least a start point and end point; leave empty to indicate that no map exists for the activity) |
post_to_facebook |
Boolean |
True to post this activity to Facebook, false
to prevent posting (optional; if not specified, the user’s
default preference is used) |
post_to_twitter |
Boolean |
True to post this activity to Twitter, false
to prevent posting (optional; if not specified, the user’s
default preference is used) |
detect_pauses |
Boolean |
True to automatically detect and insert
pause points into the supplied path, false otherwise
(optional; if not specified, no pause detection is performed) |
Live Activities
Live activities are supported for RunKeeper Elite users. Live activities are in-progress activities that can be followed in real-time on the RunKeeper website. Live activities have the following initial form:
| Field | Type | Description |
|---|---|---|
type |
String |
The type of activity, as one of the following values: Running,
Cycling, Mountain Biking, Walking,
Hiking, Downhill Skiing, Cross-Country
Skiing, Snowboarding, Skating, Swimming,
Wheelchair, Rowing, Elliptical,
Other |
start_time |
String |
The starting time for the activity (e.g., Sat,
1 Jan 2011 00:00:00)
|
secondary_type |
String |
The secondary type of the activity, as a free-form string
(max. 64 characters). This field is used only if the type
field is "Other."
|
equipment |
String |
The equipment used to complete this activity, as one of
the following values: None, Treadmill,
Stationary Bike, Elliptical, Row
Machine. (Optional; if not specified, None is
assumed.)
|
Updates
Updates to live activities have the following form (each update appends new information to the existing activity):
| Field | Type | Description |
|---|---|---|
heart_rate |
HeartRate[] |
The sequence of time-stamped heart rate measurements (optional) |
path |
WGS84[] |
The sequence of time-stamped geographical points along the route (optional) |
Completions
Completions of live activities have the following form:
| Field | Type | Description |
|---|---|---|
notes |
String |
Any notes that the user has associated with the activity (optional) |
post_to_facebook |
Boolean |
True to post this activity to Facebook, false
to prevent posting (optional; if not specified, the user’s
default preference is used) |
post_to_twitter |
Boolean |
True to post this activity to Twitter, false
to prevent posting (optional; if not specified, the user’s
default preference is used) |
detect_pauses |
Boolean |
True to automatically detect and insert
pause points into the supplied path, false
otherwise (optional; if not specified, no pause detection is
performed) |
Array Structures
Each of the following array types consists of the respective fields listed.
items
| Field | Type | Description |
|---|---|---|
type |
String |
The type of activity, as one of the following values: Running,
Cycling, Mountain Biking, Walking,
Hiking, Downhill Skiing, Cross-Country
Skiing, Snowboarding, Skating, Swimming,
Wheelchair, Rowing, Elliptical,
Other |
start_time |
String |
The starting time for the activity (e.g., Sat,
1 Jan 2011 00:00:00)
|
total_distance |
Double |
The total distance for the activity, in meters |
duration |
Double |
The duration of the activity, in seconds |
source |
String |
The name of the application that last modified this activity |
entry_mode |
String |
The mode by which this activity was originally entered, as one of the
following values: API, Web |
has_path |
Boolean |
Whether a path exists for this activity |
uri |
String |
The URI of the detailed information for the past activity |
distance
| Field | Type | Description |
|---|---|---|
timestamp |
Double |
The number of seconds since the start of the activity |
distance |
Double |
The total distance traveled since the start of the activity, in meters |
heartRate
| Field | Type | Description |
|---|---|---|
timestamp |
Double |
The number of seconds since the start of the activity |
heart_rate |
Integer |
The instantaneous heart rate, in beats per minute |
calories
| Field | Type | Description |
|---|---|---|
timestamp |
Double |
The number of seconds since the start of the activity |
calories |
Double |
The total calories burned since the start of the activity |
path
| Field | Type | Description |
|---|---|---|
timestamp |
Double |
The number of seconds since the start of the activity |
latitude |
Double |
The latitude, in degrees (values increase northward and decrease southward) |
longitude |
Double |
The longitude, in degrees (values increase eastward and decrease westward) |
altitude |
Double |
The altitude of the point, in meters |
type |
String |
One of the following values: start, end,
gps, pause, resume, manual |
images
| Field | Type | Description |
|---|---|---|
timestamp |
Double |
The number of seconds since the start of the activity |
latitude |
Double |
The latitude, in degrees (values increase northward and decrease southward) |
longitude |
Double |
The longitude, in degrees (values increase eastward and decrease westward) |
uri |
String |
The URI of the image |
thumbnail_uri |
String |
The URI of the thumbnail version of the image |
Supported Operations
Retrieving Activity Information
To retrieve a page of a user’s activity history or information for
a past activity,
GET
its URI.
Retrieving Headers for a Past Activity
Header information for a past activity can be retrieved by making a
HEAD
request to the URI.
Editing a Past Activity
To edit a past activity,
PUT
any new values for editable fields to its URI.
Recording An Activity
To record a newly-completed activity, or to begin recording a live
activity,
POST
its fields to any page in the user’s activity
feed.
Updating or Finishing a Live Activity
To update a live activity, or to finish recording one,
POST
to its URI.
Deleting an Activity
To delete an activity,
DELETE
its URI.