API access to Intervals.icu

david · 1 April 2020 16:19

Intervals.icu now has a public API for other applications. To use it you need to generate an API key in /settings (look for “Developer Settings” near the bottom). Your API key allows other applications to access your Intervals.icu data. Be careful what you do with it! If you suspect that your key may have been compromised immediately clear or re-generate it.

By using the API you agree to the Intervals.icu API Terms and Conditions .

The API uses basic authentication for personal use. The username is “API_KEY” and the password your API key. Example using curl:

$ curl -u API_KEY:1l0nlqjq3j1obdhg08rz5rfhx https://intervals.icu/api/v1/athlete/2049151/activities.csv

Apps intended to be used by more than one person should use OAuth and Bearer tokens.

I generated some API docs:

Note that you can use “0” for the athlete id for endpoints that accept an athlete id in the path. This will use the athlete for the API key or bearer token used to make the call.

Also you can extend Intervals.icu itself using Javascript.

There are some guides for common API tasks:

Rate Limits

There are limits per day (reset at midnight UTC) and per rolling 15 minute window. The following http headers are returned on each request:

X-RateLimit-Limit: <15m limit>,<daily limit>
X-RateLimit-Remaining: <15m limit remaining>,<daily limit remaining>

Over rate limit requests receive a 429 status code and a Retry-After http header indicating how many seconds need to elapse until the call might succeed.

Retry-After: 370

There is an additional limit of 10 calls per second per IP address. This limit does not return any rate limit related http headers.

Rate limits are enforced differently for API key callers and OAuth client apps.

OAuth Client Apps

The default daily rate limit is 100/user per day up to 500 users (max 50000 requests), with a minimum of 5000. The daily limit resets at midnight UTC. Note that the per-user number is used to calculate the total daily limit and is not applied per-user, so backfills and new-user setup tasks should not be an issue.

The requests per 15 minute limit is 1/8 of the daily limit with a minimum of 2500. This is a rolling limit and does not reset at specific intervals.

If you have more than 500 users and need a higher daily limit, or a lower limit for safety, contact [email protected]. The limits are to protect the Intervals.icu infrastructure from apps with many users suddenly generating many more calls than usual.

Current limits and API usage information can be found on the oauth client management page (look for “Manage App” on your app on /settings/apps).

API Key Callers

API key calls are limited to 5000 requests per day and 2500 requests per rolling 15 minute window. If you need more than that you need to create an app using OAuth.

Cloudflare Note

Intervals.icu uses Cloudflare and CF considers requests from some client libraries (e.g. Python-urllib) to be suspicious and maybe challenge or block them. The easy fix is to change the user agent to look like a browser.

Andrii_Magalich · 2 April 2020 20:58

Great! Now I could try myself some metrics before suggesting them to you. Also it would be great to have an easy access to the detailed activity files.

E.g., I’ve been wondering if a series of week-to-week plots showing the HR @ running pace would be something useful to track improvement in aerobic fitness (conversely, HR @ power for cycling). For that I’d need the files. Or is there an easy way to get them from Strava?

PS: are there any privacy measures?

david · 3 April 2020 05:37

I have to be careful to not just proxy stuff you can get from Strava. Would be best if I added those HR stats you are looking for to each activity then they will be in the CSV and I can also plot them in Intervals.icu at some point.

The Strava API is relatively easy to use especially if you only want to look at your own data.

The Intervals.icu API will only let you see your own data and data for athletes you follow so I think is ok re privacy.

I need to re-do the athletes and followers pages (got some good ideas from @Cyclopaat) and then I will start adding support for custom calculated values and plots (e.g. for chronic intensity load).

david · 13 April 2020 15:45

I have added REST JSON endpoints for calendar access. If you have a clever way of generating training plans you can now get those into Intervals.icu easily.

GET /api/v1/athlete/{id}/calendars List all calendars

GET /api/v1/athlete/{id}/events List all calendar events. Requires parameters oldest and newest in yyyy-MM-dd format (local dates i.e. no timezone). The range may be expanded if oldest and/or newest fall inside a multiday event to include the whole event. Only events from enabled calendars are returned. Supports optional calendar_id parameter to filter for events for a particular calendar.

GET /api/v1/athlete/{id}/events/{eventId} Fetch an event by id.
GET /api/v1/athlete/{id}/events/{eventId}/download{ext} Download a planned workout in .zwo, .mrc or .erg format.
POST /api/v1/athlete/{id}/events Create event and return it.
PUT /api/v1/athlete/{id}/events/{eventId} Update event and return it.
DELETE /api/v1/athlete/{id}/events/{eventId} Delete the event.

Example POST payload to create a workout (note that the dates cannot have time i.e. must end with T00:00:00 and the athlete needs to be yourself or someone you are coaching):

{
    "start_date_local": "2020-05-01T00:00:00",
    "icu_training_load": 120,
    "category": "WORKOUT",
    "name": "Outdoor ride at last!",
    "description": "Lockdown finally over, just go ride around all over the place!",
    "type": "Ride",
    "moving_time": 7200
}

Response:

{
    "id": 127,
    "start_date_local": "2020-05-01T00:00:00",
    "icu_training_load": 120,
    "icu_atl": 18.852789,
    "icu_ctl": 39.18664,
    "calendar_id": 1,
    "uid": "fcb69e1a-934e-47ac-a5f1-a207830466f2",
    "category": "WORKOUT",
    "end_date_local": "2020-05-02T00:00:00",
    "name": "Outdoor ride at last!",
    "description": "Lockdown finally over, just go ride around all over the place!",
    "type": "Ride",
    "color": null,
    "moving_time": 7200,
    "icu_ftp": null,
    "atl_days": null,
    "ctl_days": null,
    "updated": "2020-04-13T14:58:50.314+0000"
}

Note that the future fitness parameters (after the workout) for that date have been calculated.

If anyone is looking at the athlete’s calendar or fitness chart they will see any changes immediately.

Update 22 April 2021:

The workout description is now parsed. This means that workouts created or updated via the API have training load calculated and get “time in zones” and so on. This also applies to workouts synced from an external calendar.
You can now create/update workouts from zwo, mrc and erg files.

POST /api/v1/athlete/{id}/events

{
  "category": "WORKOUT",
  "start_date_local": "2021-04-29T00:00:00",
  "type": "Ride",
  "filename": "4x8m.zwo",
  "file_contents": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<workout_file>..."
}

Response:

{
  "id": 610062,
  "icu_training_load": 116,
  ...
  "name": "4x8m VO2 Max",
  "description": "These are horribly nasty.\nCategory: Horrible\n\n- 20m 60% 90-100rpm\n\nMain set 4x\n- 8m 110%\n- 8m 50%\n\n- 10m 60%\n",
  ...
  "workout_doc": {
    "steps": [
      {
        "power": {"units": "%ftp", "value": 60},
        "cadence": {"end": 100, "start": 90, "units": "rpm"}, "duration": 1200
      }, ...
    ],
    "duration": 5640,
    "zoneTimes": [1920, 1800, 0, 0, 1920, 0, 0, 0],
    "hrZoneTimes": [1920, 1800, 0, 0, 1920, 0, 0, 0]
  },
  "icu_intensity": 86.04798
}

Jules_Cusson-Fradet · 13 May 2020 03:32

Hi David,

First of all, thank your for the very well designed and highly useful web platform!

I am relatively new to programming, actually working with R.
I tried to access the API but was unsuccessful.
Does I need to have some specific id to replace {id} in the endpoint: /api/v1/athlete/{id}/activities.csv ?

david · 13 May 2020 10:47

Tx. Yes that {id} is a Strava athlete id. If you “copy link” on the CSV link in the app you can see the ID for the athlete you are looking at (2049151 is me):

https://intervals.icu/api/athlete/2049151/activities.csv

You can just edit that (add in the /v1).

Jules_Cusson-Fradet · 13 May 2020 14:56

Got it thanks!

Is there an option to access also the raw data?

david · 13 May 2020 15:27

What data in particular? I need to be careful to not just proxy things that you can get from the Strava API.

Jules_Cusson-Fradet · 13 May 2020 16:24

Oh ok!

Actually I am working as a sport scientist with a national track cycling team and was looking for a way to easily get the data from athletes via the cloud and compute some additional metrics like the numbers of sprints in a session, etc.

As I understand, I should look at the Strava API if I want the raw data?
I was hoping for an easy way via Intervals.icu… and your’s API access seemed a good alternative to get data from multiples athletes!

I’d really appreciate any suggestions in that regard.

david · 14 May 2020 03:31

I can give your the intervals detected or manually added in Intervals.icu via the API if that helps?

Jules_Cusson-Fradet · 14 May 2020 14:10

Yes it would be cool to have the intervals detected!

Thanks a lot David, very excited to follow the development of Intervals.icu!

Jules_Cusson-Fradet · 26 May 2020 03:14

Hi David,

I would really like to have access to the intervals detected in Intervals.icu via the API.

Hopefully this is an easy add…!

Thanks a lot!

david · 26 May 2020 11:53

Not too hard. Will get on it soon.

david · 29 May 2020 04:24

I have added API access to the data for each activity:

GET /api/v1/activity/{id}?intervals=true

This returns a JSON document which includes the interval data and lots of other stuff:

"icu_intervals": [
    ...,
    {
      "start_index": 1582,
      "distance": 3872.1006,
      "moving_time": 719,
      "elapsed_time": 719,
      "average_watts": 327,
      "min_watts": 6,
      "max_watts": 626,
      "average_watts_kg": 4.52,
      "max_watts_kg": 8.67,
      "intensity": 112,
      "w5s_variability": 0.022526897,
      "weighted_average_watts": 327,
      "training_load": 13.339117,
      "joules": 235394,
      "decoupling": 2.050206,
      "zone": 5,
      "zone_min_watts": 305,
      "zone_max_watts": 348,
      "average_speed": 5.3853974,
      "min_speed": 3.9,
      "max_speed": 7.8,
      "average_heartrate": 173,
      "min_heartrate": 139,
      "max_heartrate": 185,
      "average_cadence": 72,
      "min_cadence": 53,
      "max_cadence": 96,
      "average_torque": 43,
      "min_torque": 11,
      "max_torque": 89,
      "total_elevation_gain": 217.8,
      "min_altitude": -61.4,
      "max_altitude": 156.4,
      "average_gradient": 0.056248534,
      "id": 1582,
      "type": "WORK",
      "end_index": 2299,
      "group_id": "719s@327w72rpm",
      "segment_effort_ids": [
        2700622372552880600,
        2700622372552880600
      ],
      "estimated_cp": null,
      "start_time": 1586,
      "end_time": 2305
    },
    ...

Leave out intervals or set it to false if you don’t need interval data.

Jules_Cusson-Fradet · 29 May 2020 15:29

Thank you very much David! Very useful for me.

Ross_Wildman · 31 October 2020 18:36

Hi David, outstanding work!

Do you have an end point for adding to a work out to library ?

Ross

david · 1 November 2020 19:32

I will add that soon. On the list.

Ross_Wildman · 1 November 2020 20:25

Perfect,

ive made a phpsdk to collect workouts from zwift and add them as workouts / session.

Welcome to the code if you wish, will make it available on GitHub as a package

david · 2 November 2020 17:14

I have added some endpoints for this (will deploy Tuesday AM GMT+2):

GET /api/v1/athlete/{id}/folders List all folders and workouts
POST /api/v1/athlete/{id}/folders Create a folder
PUT /api/v1/athlete/{id}/folders/{folderId} Update folder
DELETE /api/v1/athlete/{id}/folders/{folderId} Delete folder
GET /api/v1/athlete/{id}/folders/{folderId}/shared-with Show who folder has been shared with
PUT /api/v1/athlete/{id}/folders/{folderId}/shared-with Update folder sharing
GET /api/v1/athlete/{id}/workouts List all workouts (excluding those shared by others)
GET /api/v1/athlete/{id}/workouts/{workoutId} Get a workout
POST /api/v1/athlete/{id}/workouts Create a workout
PUT /api/v1/athlete/{id}/workouts/{workoutId} Update a workout
DELETE /api/v1/athlete/{id}/workouts/{workoutId} Delete a workout
POST /api/v1/download-workout{ext} Download a workout in .zwo .mrc or .erg format

These mirror the private endpoints used by Intervals.icu so you can use the browser inspector to see what payloads to send and so on.

There is a catch: Workouts have a “workout_doc” field which is the parsed workout steps. Currently the parser is only available client side. So before you can download a workout in a different format or have it sync to Garmin Connect you need to edit it using the Intervals.icu app so the workout_doc field is populated.

The Intervals.icu server is Java and the parsing code is JavaScript. So I need to setup a little node service to do the parsing.

Ross_Wildman · 6 November 2020 12:43

Hi David;
Get 401s on those end points; I’ve tried regenerating api key etc as well and still the same.

Ross