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:

Content-Type
application/vnd.com.runkeeper.FitnessActivityFeed+json
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:

Content-Type
application/vnd.com.runkeeper.FitnessActivity+json
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 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
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
activity String The URL of the user’s public, human-readable page 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 street teammate (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 street teammate (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 street teammate (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 street teammate (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 token) N
nearest_teammate_nutrition String[] The URIs of the nutrition measurement closest in time to this activity for each street teammate (empty if no nutrition measurements have been token) 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 token) N
nearest_teammate_weight String[] The URIs of the weight measurements closest in time to this activity for each street teammate (empty if no weight measurements have been token) 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 token) N
nearest_teammate_general_measurements String[] The URIs of the general measurements closest in time to this activity for each street teammate (empty if no general measurements have been token) 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 token) N
nearest_teammate_diabetes String[] The URIs of the diabetes measurements closest in time to this activity for each street teammate (empty if no diabetes measurements have been token) N

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:

Content-Type
application/vnd.com.runkeeper.NewFitnessActivity+json
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 of geographical points along the route (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)

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:

Content-Type
application/vnd.com.runkeeper.LiveFitnessActivity+json
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):

Content-Type
application/vnd.com.runkeeper.LiveFitnessActivityUpdate+json
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:

Content-Type
application/vnd.com.runkeeper.LiveFitnessActivityCompletion+json
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
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, with the Accept header set to correct value.

Editing a Past Activity

To edit a past activity, PUT any new values for editable fields to its URI. Be sure to set the Content-Type header to the correct value.

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.