API Documentation

Introduction

The dailymile API enables third-party developers to build applications on dailymile's social workout platform. You're free to build for the Web, the desktop, or on mobile devices. The API does its best to adhere to the principles of REST and should hopefully feel familiar if you've interacted with APIs of other consumer Web apps before. Manipulating resources is done over HTTP. We do our best to follow standards and best practices.

Authorization

Authorization is required to modify data (generally whenever using POST, PUT, or DELETE). Some resources are protected and will require authorization to manipulate, such as a user's private data. Protected resources exposed by this API can be accessed using OAuth, a simple and open protocol.

OAuth

Third-party applications built on dailymile must use OAuth to authenticate. There are libraries already built for most languages, which you can find here. This API supports OAuth 1.0a and HMAC-SHA1 for signing requests.

To get started using OAuth, you'll first have to register your application. If you haven't yet, you'll want to read the OAuth Documentation.

OAuth is used throughout the documentation to mark resources that are protected.

Rate Limiting

You are allowed to make 1500 requests per hour. This limit should be high enough for most applications and we reserve the right to tune it in the future. If you need more, please contact us. If you exceed this limit, a 503 response will be returned with the Retry-After header set, which will contain the number of seconds until you can start sending requests again.

Formats and HTTP Response Codes

Supported Formats

We currently support both XML and JSON. Unless otherwise specified, wherever format is used in a URI, it can be replaced with either xml or json.

HTTP Response Codes

The following HTTP status codes may be returned in responses from the server:

200 OK

It worked :)

404 Not Found

The resource doesn't exist.

401 Not Authorized

You're accessing resources without the correct authorization. (Make sure your authorization code is properly working!)

422 Unprocessable Entity

This is likely the result of invalid or missing parameters. Make sure the data you're sending in your request is correct.

405 Method Not Allowed

The method used to manipulate the resource is not allowed. Check the Allow header for valid methods.

406 Not Acceptable

The resource you've requested cannot be represented in the format you asked for.

503 Service Unavailable

You have may have hit your rate limit, check the Retry-After header.

502 or 503

Service is down for maintenance. Please try again later. If it's a 503, check the headers to see if it's because you hit your rate limit.

Table of Contents

• Read Data
  • Person — a person identified by username
  • Friends — the friendships of a person
  • Entry — view an entry
• Read Streams
  • Public — a stream of everyone's entries
  • Person — a person's stream
  • You And Friends — the stream of the authenticated user and their friends
  • Nearby — a stream of entries nearby a location
• Publish Data
  • Create Entry — post a workout, note, or image
  • Delete Entry — delete an entry
  • Create Comment — add a comment to an entry
  • Create Like — like an entry

Resources

OAuthCreate an Entry

Parameters:

message, string (optional)

text of the note to post or the "how did it go?" text to accompany a workout

Include if posting a workout:

workout[type], string (optional)

one of "running", "cycling", "swimming", "walking", or "fitness"

workout[completed_at], datetime (optional)

when the workout was done, ex: 2010-12-25 12:15:00

workout[distance][value], float (optional)

the distance indicated by units

workout[distance][units], string (optional)

one of "miles", "kilometers", "yards", or "meters"; defaults depending on user's units preference and workout type

workout[duration], integer (optional)

the number of seconds spent working out

workout[felt], string (optional)

one of "great", "good", "alright", "blah", "tired" or "injured"

workout[calories], integer (optional)

the number of calories burned during the workout

Include if sharing an image:

media[type], string

image

media[url], string

the URL to the photo

OAuthDelete an Entry

Read an Entry

Person

show sample response

{ 
  "display_name": "Ben W.",
  "username": "ben",
  "url": "http://www.dailymile.com/people/ben",
  "photo_url": "http://media.dailymile.com/pictures/users/1/1218627641_avatar.jpg",
  "location": "San Francisco, CA",
  "time_zone": "Pacific Time (US & Canada)"
}

Friends

show sample response

{ 
  "friends" : [
    {
      "display_name": "Raphael W.",
      "username": "raphael",
      "location": "Corvallis, OR",
      "url": "http://www.dailymile.com/people/raphael",
      "photo_url": "http://media.dailymile.com/pictures/users/32/1222917090_avatar.jpg"
    },
    {
      "display_name": "Kelly K.",
      "username": "kelly",
      "location": "San Francisco, CA",
      "url": "http://www.dailymile.com/people/kelly",
      "photo_url": "http://media.dailymile.com/pictures/users/2/1218627641_avatar.jpg"
    }
  ]
}

User's Stream

The most recent 20 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

For an example response, view the response below for You and Friends.

OAuthYou and Friends Stream

The most recent 20 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

max_id, integer (optional)

Fetch all entries with an ID less than or equal to the given max_id.

since_id, integer (optional)

Fetch all entries with an ID greater than the given since_id.

show sample response

{
  "entries": [
    {
      "id": 232323232,
      "message": "great run",
      "workout": {
        "type": "running",
        "distance": {
          "value": 5.5,
          "units": "miles"
        },
        "duration": 23252332432,
        "felt": "great",
        "calories": 421
      },
      "user": {
        "display_name": "Ben W.",
        "url": "http//www.dailymile.com/people/ben",
        "photo_url": "http://media.dailymile.com/pictures/2.jpg"
      },
      "permalink": "http://www.dailymile.com/entries/23131323",
      "created_at": "2010-07-21T02:20:24-05:00"
    },
    {
      "id": 232323233,
      "message": "hi, i'm just a note",
      "user": {
        "display_name": "Ben W.",
        "url": "http//www.dailymile.com/people/ben",
        "photo_url": "http://media.dailymile.com/pictures/2.jpg"
      },
      "permalink": "http://www.dailymile.com/entries/23131322",
      "created_at": "2010-07-21T02:20:24-05:00"
      "comments": [
        {
          "body": "wow, awesome note",
          "created_at": "2010-07-23T20:57:08-05:00",
          "user": {
            "display_name": "Ben W.",
            "url": "http//www.dailymile.com/people/ben",
            "photo_url": "http://media.dailymile.com/pictures/2.jpg"
          }
        },
      ],
      "likes": [
        {
          "created_at": "2010-07-23T20:57:08-05:00",
          "user": {
            "display_name": "Ben W.",
            "url": "http//www.dailymile.com/people/ben",
            "photo_url": "http://media.dailymile.com/pictures/2.jpg"
          }
        }
      ]
    },
    { 
      "id": 232323234,
      "message": "beautiful photo i took along my run",
      "media": [
        {
          "content": {
            "type": "image",
            "url": "http://s3.amazonaws.com/someimg.jpg",
            "width": 150,
            "height": 150
          },
          "preview": {
            "type": "image",
            "url": "http://s3.amazonaws.com/preview.jpg",
            "height": 75,
            "width": 75
          }
        }
      ],
      "user": {
        "display_name": "Ben W.",
        "url": "http//www.dailymile.com/people/ben",
        "photo_url": "http://media.dailymile.com/pictures/2.jpg"
      },
      "permalink": "http://www.dailymile.com/entries/23131322",
      "created_at": "2010-07-21T02:20:24-05:00"
    }, 
    { 
      "id": 232323234,
      "message": "awesome video i took today, really cool footage",
      "media": [
        {
          "content": {
            "type": "video",
            "url": "http://s3.amazonaws.com/video.mp4"
          },
          "preview": {
            "type": "image",
            "url": "http://s3.amazonaws.com/video_thumbnail.jpg",
            "height": 120,
            "width": 90
          }
        }
      ],
      "user": {
        "display_name": "Ben W.",
        "url": "http//www.dailymile.com/people/ben",
        "photo_url": "http://media.dailymile.com/pictures/2.jpg"
      },
      "permalink": "http://www.dailymile.com/entries/23131322",
      "created_at": "2010-07-21T02:20:24-05:00"
    }
  ]
}

Public Stream

The most recent 25 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

max_id, integer (optional)

Fetch all entries with an ID less than or equal to the given max_id.

since_id, integer (optional)

Fetch all entries with an ID greater than the given since_id.

Nearby Stream

The most recent 25 entries posted nearby the given coordinates.

Parameters:

radius, integer (optional)

radius in miles to show results in, default is 50 miles

page, integer (optional)

page of results to return, starting with 1

max_id, integer (optional)

Fetch all entries with an ID less than or equal to the given max_id.

since_id, integer (optional)

Fetch all entries with an ID greater than the given since_id.

OAuthEntry Comments

Parameters:

body, string with a max length of 510 (required)

the comment text

OAuthEntry Likes