API

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 2.0

Third-party applications built on dailymile must use OAuth 2.0 to authenticate. OAuth 2.0 is a simpler version of OAuth that does away with complex signatures and instead relies on SSL. (If you've been frustrated in the past with OAuth, you'll be happy with the improved flows in 2.0!)

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.

Response Formats

We currently support only JSON. Unless otherwise specified, wherever format is used in a URI, it can be replaced with json.

We also support JSONP on all JSON requests. Simply include a callback parameter with the name of your JavaScript callback. E.g., if you add this script tag to your page:

  <script type="text/javascript" src="http://api.dailymile.com/people/ben.json?callback=myCallback"></script>
  

You'll get this response with its Content-Type set to application/javascript:

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

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.

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.

• Streams — entries, comments, and likes all together
• Entries — read, create, and delete entries
• Comments — create comments
• Likes — create likes
• People — read people and their friends
• Routes and GPS — upload GPS tracks for workouts and read/write routes

Each feed accepts since and until as parameters. Both of these parameters accept a UNIX timestamp. (If you're familiar with the Twitter API, these parameters roughly correspond to using their since_id and max_id parameters.) This allows you to fetch new entries in a feed since a certain time and to paginate through a feed keeping the same starting point with until. Each entry has an at attribute that can be converted to a UNIX timestamp and used as the value for these parameters.

Person's Stream

GET http://api.dailymile.com/people/username/entries.json

The most recent 20 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

until, unix timestamp (optional)

Fetch all entries with a timestamp less than or equal to the given until.

since, unix timestamp (optional)

Fetch all entries with a timestamp greater than the given since.

show sample response

OAuthYou and Friends Stream

GET https://api.dailymile.com/entries/friends.json

The most recent 20 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

until, unix timestamp (optional)

Fetch all entries with a timestamp less than or equal to the given until.

since, unix timestamp (optional)

Fetch all entries with a timestamp greater than the given since.

Public Stream

GET http://api.dailymile.com/entries.json

The most recent 20 entries.

Parameters:

page, integer (optional)

page of results to return, starting with 1

until, unix timestamp (optional)

Fetch all entries with a timestamp less than or equal to the given until.

since, unix timestamp (optional)

Fetch all entries with a timestamp greater than the given since.

show sample response

Nearby Stream

GET http://api.dailymile.com/entries/nearby/lat,lon.json

The most recent 20 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

until, unix timestamp (optional)

Fetch all entries with a timestamp less than or equal to the given until.

since, unix timestamp (optional)

Fetch all entries with a timestamp greater than the given since.

show sample response

OAuthCreate an Entry

POST https://api.dailymile.com/entries.json

Parameters:

message, string (optional)

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

Geo-tagging an entry:

lat, float (optional)

the latitude of this entry, between -90 and 90

lon, float (optional)

the longitude of this entry, between -180 and 180

Include if posting a workout:

workout[activity_type], string

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

workout[completed_at], datetime (optional)

when the workout was done, formatted in ISO 8601 and in UTC. ex: 2011-01-11T03:54:43Z

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 activity 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

workout[title], string (optional)

optional title for a workout

workout[route_id], integer (optional)

the id of the route associated with this workout (see route docs)

Include if sharing an image:

media[type], string

image

media[url], string

the URL to the photo

Example: Posting a note with curl:

  curl -F 'oauth_token=<OAUTH_TOKEN>' \
       -F 'message=my first note' \
          https://api.dailymile.com/entries.json
  

Example: Posting a 5 mile run with curl:

  curl -d '{"message":"fun!","workout":{"distance":{"value":5,"units":"miles"},"activity_type":"running"}}' \
       -H 'Content-Type: application/json' \
          https://api.dailymile.com/entries.json?oauth_token=<OAUTH_TOKEN>
  

Entry

GET http://api.dailymile.com/entries/id.json

OAuthDelete Entry

DELETE https://api.dailymile.com/entries/id.json

OAuthCreate Comment

POST https://api.dailymile.com/entries/id/comments.json

Parameters:

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

the comment text

OAuthCreate Like

POST https://api.dailymile.com/entries/id/likes.json

Person

GET http://api.dailymile.com/people/username.json show sample response

OAuthPerson who authorized token

Special resource that returns the same response as a person, but for the user who authorized the OAuth token. GET https://api.dailymile.com/people/me.json

Friends

GET http://api.dailymile.com/people/username/friends.json show sample response

OAuthCreate or Update GPS Track for an Entry

PUT https://api.dailymile.com/entries/id/track.json

Upload a GPX file to create or update the GPS track for a workout. This method expects raw data with a Content-Type of application/gpx+xml. The body of the request should contain the XML.

Route

GET http://api.dailymile.com/routes/id.gpx

Routes for a Person

GET http://api.dailymile.com/people/username/routes.json

A list of the user's routes.

show sample response

OAuthCreate Route

POST https://api.dailymile.com/routes.json

After creating a route, you can associate a GPS track with it by using the endpoint listed below. Associating workouts with this route is accomplished by including workout[route_id] as documented in the Create Entry endpoint.

Parameters:

name, string (optional)

name of the route

activity_type, string (optional)

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

OAuthCreate or Update GPS Track for a Route

PUT https://api.dailymile.com/routes/id/track.json

Upload a GPX file to create or update the GPS track for a route. This method expects raw data with a Content-Type of application/gpx+xml. The body of the request should contain the XML.