Example API Calls

Introduction

API calls are made via the HTTP methods GET, POST, PUT, DELETE, and HEAD. The responses return status codes indicating success or failure, along with any applicable headers, and JSON representing the affected fields (or nothing) in the message-body. The following examples demonstrate common operations using these methods.

Note: Not all methods can be used on every data set. For a list of which methods you can use on which data set, please refer to the “Supported Operations” section on the respective Documentation page.

GET

GET is used to retrieve data without directly modifying it.

Retrieving User Information

The following demonstrates how to retrieve all of the fields associated with an individual user.

Sample Request
GET /user HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.User+json
Sample Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.User+json
Content-Length: nnn

{
"userID": 1234567890,
"profile": "/profile",
"settings": "/settings",
"fitness_activities": "/fitnessActivities",
"strength_training_activities": "/strengthTrainingActivities",
"background_activities": "/backgroundActivities",
"sleep": "/sleep",
"nutrition": "/nutrition",
"weight": "/weight",
"general_measurements": "/generalMeasurements",
"diabetes": "/diabetes",
"records": "/records",
"team": "/team"
}

Retrieving Activity History

The following demonstrates how to retrieve a page of a user’s activity history, or information for a past activity. By default, each page contains 25 entries. To specify a different page size, use the pageSize query parameter.

Request
GET /fitnessActivities HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.FitnessActivityFeed+json
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.FitnessActivityFeed+json
Content-Length: nnn

{
"size": 40,
"items": [
{
   "type": "Running",
   "start_time": "Tue, 1 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "API",
   "has_map": "true",
   "uri": "/activities/40"
},
{
   "type": "Running",
   "start_time": "Thu, 3 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "Web",
   "has_map": "true",
   "uri": "/activities/39"
},
{
   "type": "Running",
   "startTime": "Sat, 5 Mar 2011 11:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "API",
   "has_map": "true",
   "uri": "/activities/38"
},
{
   "type": "Running",
   "startTime": "Mon, 7 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "API",
   "has_map": "false",
   "uri": "/activities/37"
},
⋮
],
"previous": "https://api.runkeeper.com/user/1234567890/activities?page=2"
}

Custom Page Size

The pageSize query parameter controls how many entries are returned per page.

Request
GET /fitnessActivities?pageSize=4 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.FitnessActivityFeed+json
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.FitnessActivityFeed+json
Content-Length: nnn

{
"size": 40,
"items": [
{
   "type": "Running",
   "start_time": "Tue, 1 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "uri": "/activities/40"
},
{
   "type": "Running",
   "start_time": "Thu, 3 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "Web",
   "has_map": "true",
   "uri": "/activities/39"
},
{
   "type": "Running",
   "startTime": "Sat, 5 Mar 2011 11:00:00",
   "total_distance": 70,
   "duration": 10,
   "uri": "/activities/38"
},
{
   "type": "Running",
   "startTime": "Mon, 7 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "API",
   "has_map": "false",
   "uri": "/activities/37"
}
],
"previous": "https://api.runkeeper.com/user/1234567890/activities?page=2&pageSize=4"
}

Individual Activity

To retrieve an individual activity, specify the activity’s ID in the request.

Request
GET /fitnessActivities/40 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.FitnessActivity+json
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.FitnessActivity+json
Content-Length: nnn
Last-Modified: Tue, 1 Mar 2011 10:00:00 GMT

{
"uri": "/fitnessActivities/40",
"userID": 1234567890,
"type": "Running",
"equipment": "None",
"start_time": "Sat, 1 Jan 2011 12:00:00",
"total_distance": 70,
"distance": [],
"duration": 10,
"heart_rate": [],
"calories": [],
"total_climb": 0,
"path": [
{
   "timestamp":0,
   "altitude":0,
   "longitude":-70.95182336425782,
   "latitude":42.312620297384676,
   "type":"start"
},
{
   "timestamp":10,
   "altitude":0,
   "longitude":-70.95255292510987,
   "latitude":42.31230294498018,
   "type":"end"
}
],
"comments": "/fitnessActivities/40/comments",
"source": "RunKeeper",
"entry_mode": "API",
"previous": "/fitnessActivities/39",
"nearest_teammate_strength_training_activities": [],
"nearest_teammate_background_activities": [],
"nearest_teammate_sleep": [],
"nearest_teammate_nutrition": [],
"nearest_teammate_weight": [],
"nearest_teammate_general_measurements": [],
"nearest_teammate_diabetes": []
}

If-Modified-Since Header

If the request includes the If-Modified-Since header and the feed/activity has not been modified since the given time, the response will be 304 Not Modified.

Note: per the HTTP specification, such dates MUST be specified in GMT.

Request
GET /fitnessActivities HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.FitnessActivityFeed+json
If-Modified-Since: Sun, 1 Jan 2012 00:00:00 GMT
Response
HTTP/1.1 304 Not Modified

Time Scope

The noEarlierThan, noLaterThan, modifiedNoEarlierThan, and modifiedNoLaterThan query parameters restrict the scope of the returned feed. Each takes a date in YYYY-MM-DD format.

Request
GET /fitnessActivities?noEarlierThan=2011-03-01&noLaterThan=2011-03-03 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Accept: application/vnd.com.runkeeper.FitnessActivityFeed+json
If-Modified-Since: Sun, 1 Jan 2012 00:00:00 GMT
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.FitnessActivityFeed+json
Content-Length: nnn

{
"size": 2,
"items": [
{
   "type": "Running",
   "start_time": "Tue, 1 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "API",
   "has_map": "true",
   "uri": "/activities/40"
},
{
   "type": "Running",
   "start_time": "Thu, 3 Mar 2011 07:00:00",
   "total_distance": 70,
   "duration": 10,
   "source": "RunKeeper",
   "entry_mode": "Web",
   "has_map": "true",
   "uri": "/activities/39"
}
]
}

POST

POST is used to record, or finish recording, new data.

Recording An Activity

The following demonstrates how to record a newly-completed activity, or begin recording a live one. This can be done for any page in the user’s activity history. The system will return the URI of the new activity in the response.

Request
POST /fitnessActivities HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.runkeeper.NewFitnessActivity+json
Content-Length: nnn

{
   "type": "Running",
   "equipment": "None",
   "start_time": "Sat, 1 Jan 2011 00:00:00",
   "notes": "My first late-night run",
   "path": [
   {
      "timestamp": 0,
      "altitude": 0,
      "longitude": -70.95182336425782,
      "latitude": 42.312620297384676,
      "type": "start"
   },
   {
      "timestamp": 8,
      "altitude": 0,
      "longitude": -70.95255292510987,
      "latitude": 42.31230294498018,
      "type": "end"
   }
   ],
   "post_to_facebook": true,
   "post_to_twitter": true
}
Response
HTTP/1.1 201 Created
Location: /fitnessActivities/5

Finishing a Live Activity

The following demonstrates how to update, or finish recording, a live activity.

Request
POST /fitnessActivities/20 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.runkeeper.LiveFitnessActivityUpdate+json
Content-Length: nnn

{
"path": [
{
   "timestamp": 0,
   "altitude": 0,
   "longitude": -70.95182336425782,
   "latitude": 42.312620297384676,
   "type": "gps"
},
{
   "timestamp": 5,
   "altitude": 0,
   "longitude": -70.95255292510987,
   "latitude": 42.31230294498018,
   "type": "gps"
}
]
}
Response
HTTP/1.1 204 No Content

PUT

PUT is used to modify existing data, or update an existing data set with new fields.

Editing a User’s Profile

Request
PUT /profile HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.runkeeper.Profile+json

{
"athlete_type": "Ultra Marathoner"
}
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.Profile+json
Content-Length: nnn

{
"name": "John Doe",
"location": "Sometown, USA",
"athlete_type": "Ultra Marathoner",         
"gender": "M",
"birthday": "Sat, Jan 1 2011 00:00:00",
"elite": true,
"profile": "http://www.runkeeper.com/user/JohnDoe",
"small_picture": "http://www.runkeeper.com/user/JohnDoe/small.jpg",
"normal_picture": "http://www.runkeeper.com/user/JohnDoe/normal.jpg",
"medium_picture": "http://www.runkeeper.com/user/JohnDoe/medium.jpg",
"large_picture": "http://www.runkeeper.com/user/JohnDoe/large.jpg"
}

Editing A Past Activity

The following demonstrates how to edit a past activity. Submit any new values for editable fields (values for non-editable fields are ignored and can be omitted). The system will return the updated activity in the response.

Request
PUT /fitnessActivities/40 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.runkeeper.FitnessActivity+json
Content-Length: 41

{
   "notes": "It was really cold out…"
}
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.com.runkeeper.FitnessActivity+json
Content-Length: nnn
Last-Modified: Tue, 1 Mar 2011 10:00:00 GMT

{
   "userID": 1234567890,
   "type": "Running",
   "equipment": "None",
   "start_time": "Sat, 1 Jan 2011 12:00:00",
   "total_distance": 70,
   "distance": [],
   "duration": 10,
   "heart_rate": [],
   "calories": [],
   "total_climb": 0,
   "path": [
   {
      "timestamp":0,
      "altitude":0,
      "longitude":-70.95182336425782,
      "latitude":42.312620297384676,
      "type":"start"
   },
   {
      "timestamp":10,
      "altitude":0,
      "longitude":-70.95255292510987,
      "latitude":42.31230294498018,
      "type":"end"
   }
   ],
   "notes": "It was really cold out…",
   "comments": "/fitnessActivities/40/comments",
   "source": "Acme Fitness Tracker",
   "entry_mode": "API",
   "has_map": "true",
   "previous": "/fitnessActivities/39",
   "nearest_teammate_strength_training_activities": [],
   "nearest_teammate_background_activities": [],
   "nearest_teammate_sleep": [],
   "nearest_teammate_nutrition": [],
   "nearest_teammate_weight": [],
   "nearest_teammate_general_measurements": [],
   "nearest_teammate_diabetes": []
}

DELETE

Deleting an Activity

The following demonstrates how to remove an individual activity from a user’s feed.

Request
DELETE /fitnessActivities/20 HTTP/1.1
Host: api.runkeeper.com
Authorization: Bearer xxxxxxxxxxxxxxxx
Response
HTTP/1.1 204 No Content