Workouts¶

GET /api/workouts¶

Get workouts for the authenticated user.

Scope: workouts:read

Example requests:

without parameters:

GET /api/workouts/ HTTP/1.1

with some query parameters:

GET /api/workouts?from=2019-07-02&to=2019-07-31&sport_id=1  HTTP/1.1

Example responses:

returning at least one workout:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "id": "kjxavSTUrJvoAh2wvCeGEF",
          "map": null,
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 13,
              "record_type": "HA",
              "sport_id": 1,
              "user": "Sam",
              "value": 43.97,
              "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
              "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            }
          ],
          "segments": [],
          "sport_id": 1,
          "title": null,
          "user": "admin",
          "weather_end": null,
          "weather_start": null,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT"
        }
      ]
    },
    "status": "success"
  }

returning no workouts

HTTP/1.1 200 OK
Content-Type: application/json

  {
      "data": {
          "workouts": []
      },
      "status": "success"
  }

Query Parameters:

page (integer) – page if using pagination (default: 1)
per_page (integer) – number of workouts per page (default: 5, max: 100)
sport_id (integer) – sport id
title (string) – any part (or all) of the workout title; title matching is case-insensitive
from (string) – start date (format: %Y-%m-%d)
to (string) – end date (format: %Y-%m-%d)
distance_from (float) – minimal distance
distance_to (float) – maximal distance
duration_from (string) – minimal duration (format: %H:%M)
duration_to (string) – maximal distance (format: %H:%M)
ave_speed_from (float) – minimal average speed
ave_speed_to (float) – maximal average speed
max_speed_from (float) – minimal max. speed
max_speed_to (float) – maximal max. speed
order (string) – sorting order: asc, desc (default: desc)
order_by (string) – sorting criteria: ave_speed, distance, duration, workout_date (default: workout_date)
equipment_id (string) – equipment id (if ‘none’, only workouts without equipments will be returned)
notes (string) – any part (or all) of the workout notes, notes matching is case-insensitive
description (string) – any part of the workout description; description matching is case-insensitive

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)¶

Get a workout.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF HTTP/1.1

Example responses:

success:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "ascent": null,
          "ave_speed": 16,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 18:57:14 GMT",
          "descent": null,
          "description": null,
          "distance": 12,
          "duration": "0:45:00",
          "equipments": [],
          "id": "kjxavSTUrJvoAh2wvCeGEF",
          "map": null,
          "max_alt": null,
          "max_speed": 16,
          "min_alt": null,
          "modification_date": "Sun, 14 Jul 2019 18:57:22 GMT",
          "moving": "0:45:00",
          "next_workout": 4,
          "notes": "workout without gpx",
          "pauses": null,
          "previous_workout": 3,
          "records": [],
          "segments": [],
          "sport_id": 1,
          "title": "biking on sunday morning",
          "user": "admin",
          "weather_end": null,
          "weather_start": null,
          "with_gpx": false,
          "workout_date": "Sun, 07 Jul 2019 07:00:00 GMT"
        }
      ]
    },
    "status": "success"
  }

workout not found:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

  {
    "data": {
      "workouts": []
    },
    "status": "not found"
  }

Parameters:

workout_short_id (string) – workout short id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden – you do not have permissions
404 Not Found – workout not found

GET /api/workouts/(string: workout_short_id)/gpx¶

Get gpx file for a workout displayed on map with Leaflet.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "gpx": "gpx file content"
  },
  "message": "",
  "status": "success"
}

Parameters:

workout_short_id (string) – workout short id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found –
- workout not found
- no gpx file for this workout
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/chart_data¶

Get chart data from a workout gpx file, to display it with Chart.js.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/chart HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "chart_data": [
      {
        "distance": 0,
        "duration": 0,
        "elevation": 279.4,
        "latitude": 51.5078118,
        "longitude": -0.1232004,
        "speed": 8.63,
        "time": "Fri, 14 Jul 2017 13:44:03 GMT"
      },
      {
        "distance": 7.5,
        "duration": 7380,
        "elevation": 280,
        "latitude": 51.5079733,
        "longitude": -0.1234538,
        "speed": 6.39,
        "time": "Fri, 14 Jul 2017 15:47:03 GMT"
      }
    ]
  },
  "message": "",
  "status": "success"
}

Parameters:

workout_short_id (string) – workout short id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found –
- workout not found
- no gpx file for this workout
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/chart_data/segment/(int: segment_id)¶

Get chart data from a workout gpx file, to display it with Chart.js.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/chart/segment/0 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "chart_data": [
      {
        "distance": 0,
        "duration": 0,
        "elevation": 279.4,
        "latitude": 51.5078118,
        "longitude": -0.1232004,
        "speed": 8.63,
        "time": "Fri, 14 Jul 2017 13:44:03 GMT"
      },
      {
        "distance": 7.5,
        "duration": 7380,
        "elevation": 280,
        "latitude": 51.5079733,
        "longitude": -0.1234538,
        "speed": 6.39,
        "time": "Fri, 14 Jul 2017 15:47:03 GMT"
      }
    ]
  },
  "message": "",
  "status": "success"
}

Parameters:

workout_short_id (string) – workout short id
segment_id (integer) – segment id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
400 Bad Request – no gpx file for this workout
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – workout not found
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/gpx/segment/(int: segment_id)¶

Get gpx file for a workout segment displayed on map with Leaflet.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx/segment/0 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "gpx": "gpx file content"
  },
  "message": "",
  "status": "success"
}

Parameters:

workout_short_id (string) – workout short id
segment_id (integer) – segment id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
400 Bad Request – no gpx file for this workout
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – workout not found
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/map/(map_id)¶

Get map image for workouts with gpx.

Example request:

GET /api/workouts/map/fa33f4d996844a5c73ecd1ae24456ab8?1563529507772
  HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

Parameters:

map_id (string) – workout map id

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – map does not exist
500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/map_tile/(s)/(z)/(x)/(y).png¶

Get map tile from tile server.

Example request:

GET /api/workouts/map_tile/c/13/4109/2930.png HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

Parameters:

s (string) – subdomain
z (string) – zoom
x (string) – index of the tile along the map’s x axis
y (string) – index of the tile along the map’s y axis

Status codes are status codes returned by tile server

GET /api/workouts/(string: workout_short_id)/gpx/download¶

Download gpx file.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx/download HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/gpx+xml

Parameters:

workout_short_id (string) – workout short id

Status Codes:

200 OK – success
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found –
- workout not found
- no gpx file for workout

POST /api/workouts¶

Post a workout with a gpx file.

Scope: workouts:write

Example request:

POST /api/workouts/ HTTP/1.1
Content-Type: multipart/form-data

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

 {
    "data": {
      "workouts": [
        {
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "id": "kjxavSTUrJvoAh2wvCeGEF",
          "map": null,
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF",
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            }
          ],
          "segments": [],
          "sport_id": 1,
          "title": null,
          "user": "admin",
          "weather_end": null,
          "weather_start": null,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT"
        }
      ]
    },
    "status": "success"
  }

Form Parameters:

file – gpx file (allowed extensions: .gpx, .zip)
data –
sport id, equipment id, description, title and notes, for example: {"sport_id": 1, "notes": "", "title": "", "description": "", "equipment_ids": []}. Double quotes in notes, description and title must be escaped.

The maximum length is 500 characters for notes, 10000 characters for description and 255 for title. Otherwise, they will be truncated. When description and title are provided, they replace the description and title from gpx file.

For equipment_ids, the id of the equipment to associate with this workout. Note: for now only one equipment can be associated. If not provided and default equipment exists for sport, default equipment will be associated.

Notes, description, title and equipment ids are not mandatory.

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

201 Created – workout created
400 Bad Request –
- invalid payload
- no file part
- no selected file
- file extension not allowed
- equipment_ids must be an array of strings
- only one equipment can be added
- equipment with id <equipment_id> does not exist
- invalid equipment id <equipment_id> for sport
- equipment with id <equipment_id> is inactive
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
413 Request Entity Too Large – error during picture update: file size exceeds 1.0MB
500 Internal Server Error – error, please try again or contact the administrator

POST /api/workouts/no_gpx¶

Post a workout without gpx file.

Scope: workouts:write

Example request:

POST /api/workouts/no_gpx HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

 {
    "data": {
      "workouts": [
        {
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "map": null,
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            }
          ],
          "segments": [],
          "sport_id": 1,
          "title": null,
          "user": "admin",
          "uuid": "kjxavSTUrJvoAh2wvCeGEF"
          "weather_end": null,
          "weather_start": null,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT"
        }
      ]
    },
    "status": "success"
  }

Request JSON Object:

ascent (float) – workout ascent (not mandatory, must be provided with descent)
descent (float) – workout descent (not mandatory, must be provided with ascent)
description (string) – workout description (not mandatory, max length: 10000 characters, otherwise it will be truncated)
distance (float) – workout distance in km
duration (integer) – workout duration in seconds
equipment_ids (array of strings) – the id of the equipment to associate with this workout. Note: for now only one equipment can be associated. If not provided and default equipment exists for sport, default equipment will be associated.
notes (string) – notes (not mandatory, max length: 500 characters, otherwise they will be truncated)
sport_id (integer) – workout sport id
title (string) – workout title (not mandatory, max length: 255 characters, otherwise it will be truncated)
workout_date (string) – workout date, in user timezone (format: %Y-%m-%d %H:%M)

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

201 Created – workout created
400 Bad Request –
- invalid payload
- equipment_ids must be an array of strings
- only one equipment can be added
- equipment with id <equipment_id> does not exist
- invalid equipment id <equipment_id> for sport
- equipment with id <equipment_id> is inactive
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
500 Internal Server Error – error, please try again or contact the administrator

PATCH /api/workouts/(string: workout_short_id)¶

Update a workout.

Scope: workouts:write

Example request:

PATCH /api/workouts/1 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
    "data": {
      "workouts": [
        {
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "map": null,
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF",
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF",
            }
          ],
          "segments": [],
          "sport_id": 1,
          "title": null,
          "user": "admin",
          "uuid": "kjxavSTUrJvoAh2wvCeGEF"
          "weather_end": null,
          "weather_start": null,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT"
        }
      ]
    },
    "status": "success"
  }

Parameters:

workout_short_id (string) – workout short id

Request JSON Object:

ascent (float) – workout ascent (only for workout without gpx, must be provided with descent)
descent (float) – workout descent (only for workout without gpx, must be provided with ascent)
description (string) – workout description (max length: 10000 characters, otherwise it will be truncated)
distance (float) – workout distance in km (only for workout without gpx)
duration (integer) – workout duration in seconds (only for workout without gpx)
notes (string) – notes (max length: 500 characters, otherwise they will be truncated)
sport_id (integer) – workout sport id
title (string) – workout title (max length: 255 characters, otherwise it will be truncated)
equipment_ids (array of strings) – the id of the equipment to associate with this workout (any existing equipment for this workout will be replaced). Note: for now only one equipment can be associated. If an empty array, equipment for this workout will be removed.
workout_date (string) – workout date in user timezone (format: %Y-%m-%d %H:%M) (only for workout without gpx)

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – workout updated
400 Bad Request –
- invalid payload
- equipment_ids must be an array of strings
- only one equipment can be added
- equipment with id <equipment_id> does not exist
- invalid equipment id <equipment_id> for sport
- equipment with id <equipment_id> is inactive
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – workout not found
500 Internal Server Error – error, please try again or contact the administrator

DELETE /api/workouts/(string: workout_short_id)¶

Delete a workout.

Scope: workouts:write

Example request:

DELETE /api/workouts/kjxavSTUrJvoAh2wvCeGEF HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Parameters:

workout_short_id (string) – workout short id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

204 No Content – workout deleted
401 Unauthorized –
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
404 Not Found – workout not found
500 Internal Server Error – error, please try again or contact the administrator