Ride with GPS API

Welcome to the Ride with GPS API documentation.

Please email developers@ridewithgps.com with any feedback or questions.

API clients and authentication

An API client is required for all API requests. Manage the API clients associated with your account.

Once the API client is created, an API key (api_key) will be assigned to it.

The preferred method to authenticate is with OAuth, which you can configure from your API clients management page.

The API also supports Basic authentication, using your api_key and an authentication token. Authentication tokens can be created on the API clients management page.

Read more about authentication

Versioning

Our current (and only) API version is v1 and is available at the http://ridewithgps.com/api/v1 namespace.

Only major, incompatible changes will trigger a version upgrade. We will add new endpoints and keys to existing responses without a version upgrade.

Formats

The API supports only JSON for requests and responses. To specify JSON, you can either add a content-type: application/json header to your requests, or add a .json extension to the endpoints you call. The documentation specifies URLs with a .json extension.

Webhooks

You can configure your API client to send webhooks to your servers whenever one of your users creates or updates an asset in their library.

Read more about webhooks

Responses

API responses always contain a root key named after the requested resource(s):

// 200 - OK
{
  "route": {
    "id": 1,
    "name": "Loop around the house",
    // ...
  }
}

Pagination

Some requests (like the routes index request at /api/v1/routes.json) support pagination with ?page=<page>&page_size=<page_size> query parameters. Page sizes must be between 20 and 200. If you do not include a page size, it will use the default for the route. Pagination meta data is included in the response:

// GET /api/v1/routes.json?page=1?page_size=20
// 200 - OK
{
  "routes": [
    // ...
  ],
  "meta": {
    "pagination": {
      "record_count": 207,
      "page_count": 11,
      "page_size": 20,
      "next_page_url": "https://ridewithgps.com/api/v1/routes.json?page=2?page_size=20"
    }
  }
}

• A null value of next_page_url indicates that you have reached the last page of results.

Error responses

Successful requests are responded with either 200 - OK, 201 - Created, or 204 - No Content http status codes.

When reporting an error, the API responds with one of the following status codes:

• 404 - Not Found - the requested resource cannot be found
• 400 - Bad Request - malformed request
• 401 - Not Authorized - authentication is required and has failed
• 403 - Forbidden - authenticated user lacks required permissions
• 422 - Unprocessable Entity - request is unable to be processed
• 500 - Internal Server Error - an unexpected condition was encountered

In case of errors, the response body includes an array of error messages:

// 401 - Not Authorized
{
  "errors": ["Authentication is required and has failed"]
}

// 422 - Unprocessable Entity
{
  "errors": ["name is required", "start_date is required"]
}