RWGPS API

The Ride With GPS API is JSON based and under active development. To use it, email info@ridewithgps.com requesting an API key. Keys allow us to track, authorize and provide versioning to specific apps, and are vital in ensuring your app will always remain supported by Ride With GPS.

To get started, you should be familiar with your framework of choice. We provide this basic javascript based example page to give concrete examples of interacting with the API. The concepts are the same across different languages and frameworks.

In order to get consistent results, and to avoid losing access to the API, it is important to use an apikey parameter with every request. When your API key is issued we will set it to use the current version of the API by default. As of March 2014, the current version is 2. You can always override the version by providing the version parameter.

Most of the API requires user authentication (and notice, the API is SSL enabled), so the first thing to do is to login using an email/password and retrieve an auth_token to use in subsequent requests. Open up your developer console's network tab to see the request in action.

GET /users/current.json?email={some_email}&password={some_password}&apikey=testkey1&version=2
Get Token

If you entered a valid email/password, you will see the auth_token parameter was filled in below. When using the API in your own site/app, make sure to store away the auth_token returned on the user object for future use. You will need to provide it for most API requests. Notice: we expire auth_tokens on a regular basis, so make sure you check for a failed login or an expired token response on each request. This is your indication to prompt a user to log back in.

Now that you have an auth_token populated, you can use the following playground to get an idea of what we provide.



Full Request URL

JSON Encoded Request

Response

Authenticated User Detail
Get details about the currently authenticated user
/users/current.json
GET
User Detail
Get details about any user. Example uses a user id of 1
/users/{id}.json
GET
Route Details
Get details about a route. Example uses a route id of 36534661
/routes/{id}.json
GET
Trip Details
Get details about a trip. Example uses a trip id of 94
/trips/{id}.json
GET
User Routes
Get a list of a user's routes. Example uses a user id of 1
/users/{id}/routes.json
GET
User Rides
Get a list of a user's rides. Example uses a user id of 1
/users/{id}/trips.json
GET
New Ride From Points

Create a new ride from raw points. Look below for an example point format with all available fields populated.

Notice, this endpoint is JSONP compatible for cross site capabilities in-browser. jQuery makes this easy, but if you are handling manually just provide a callback parameter with your request. 

//valid keys
{
  x: -122.0, //longitude
  y: 45.0, //latitude
  e: 100.0, //elevation in meters
  t: 1368018754, //time in seconds since epoch. **Note** NOT in milliseconds!
  c: 90, //cadence
  h: 150, //heartrate
  p: 250, //power in watts
  s: 4.5, //speed, meters/second.  Don't provide unless from wheel sensor
  d: 45, //distance from start in meters. Only provide if from wheel sensor
  T: 20 //temperature in celcius
}
/trips.json OR /trips.js
POST
New Ride From File

Create a new ride from an uploaded TCX, GPX, FIT or KML file. Due to the potential time it takes to parse a file, this end point is non-blocking and queues up a background job to process the file. As a result, you will need to poll a second endpoint in order to get the actual trip information. Usually jobs are processed within ten seconds, though occasionally they can take a couple minutes depending on server load. As a result, please implement some sort of exponential back-off to reduce the number of requests.

Notice, this endpoint is JSONP compatible for cross site capabilities in-browser. jQuery makes this easy, but if you are handling manually just provide a callback parameter with your request.

/trips.json OR /trips.js
POST
User Clubs
Get details about all clubs a particular user belongs to. Example uses a user id of 1
/users/{id}/clubs.json
GET
Club Details
Get details about a particular club. Example uses a club id of 1
/clubs/{id}.json
GET
Club Routes
Get details about all of a particular club's routes. Example uses a club id of 1. Optional parameters limit and offset can be used to return a subset of the result set, useful for pagination.
/clubs/{id}/routes.json
GET
Queued Task Status

After uploading a file (only file, not raw points) and getting a queued task id back, use this end point to poll for the status of the queued job. Status is -1 for failed, 0 for pending, 1 for success. You can optionally get back the associated routes/rides by setting include_objects to true.

To test, upload a TCX/GPX/FIT file using the upload end point. Use the returned queued task's id.

Note: Successful queued tasks are deleted nightly

/queued_tasks/status.json
GET