Apply

To apply to the API and get your client credentials, please send the following to support@tredict.com:

• Name of your app or service
• A very short description of your service
• The logo of your service as .svg or .png feasible for a dimension of 124 x 124 pixel.
  
• Your OAuth2 callback url, we redirect the user to, after successful authorization.
  
• Link to your privacy statement
  
• Your needed scopes. By default you get "activityWrite".
  
• Your mobile phone number in international format. You will receive a pin on this number to decrypt the KeePass2 vault, we will send you with your client credentials. We won't store this number. Alternativly we will find another way.

The first five points may be displayed to the user.

Please handle the client credentials securely and with care.
In case of a loss or breach of your client credentials, please tell us, so we can generate new ones for you.

Integrate

Tredict enables you to authorize and gain access to selected functionality of our users and system via the OAuth2 principles.

Register account for testing

Register a Tredict account for testing purposes at https://www.tredict.com/register/

Request authorization code

Redirect your user to the following url, so the user can authenticate as a Tredict user and gives an authorization grant.

Authorization dialog URL:

https://www.tredict.com/authorization/

Parameter

Example
https://www.tredict.com/authorization/?client_id=${your_client_id_here}&state=my_user_locale%3Des%26my_oauth_user_id%3D843434

On successfull authorization by the user, we will redirect the user to your given callback url with the authorization code and state attached. You can use the authorization code to obtain the user access token then. The authorization code is only valid once and it expires after 10 minutes.

Redirect on success
https://www.yourapplication.that.does.not.exist.com/?code=92682f9544255285736fb6d2d8a556da&state=my_user_locale%3Des%26my_oauth_user_id%3D843434

On error we will call your callback url just with an error parameter.

Redirect on error
https://www.yourapplication.that.does.not.exist.com/?error=server_error

Localize:
Tredict is also available in German. To display a German authorization dialog, just use https://www.tredict.de/ accordingly.

Request user access token

You can request an user access token either with a freshly received authorization code or a long live refresh token.

Access token url:

POST https://www.tredict.com/user/oauth/v2/token
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Basic auth with base64 encoded string client_id:client_secret. For example, if your client id is 12345 and client secret is verySecret, then you need to base64 encode the string 12345:verySecret, resulting in MTIzNDU6dmVyeVNlY3JldA==. Value of authorization header in that case should be Basic MTIzNDU6dmVyeVNlY3JldA==.
• Content-Type: application/x-www-form-urlencoded
• Accept: application/json;charset=UTF-8

Request POST data:

Status codes:

• 200: Request could be processed successfully.
• 400: You provided invalid post data.
• 401: Your client credentials are invalid.
• 403: You provided an invalid code. Maybe it is expired.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Response JSON object entries:

• access_token: This is the user resource access bearer token encoded as JWT.
  It is valid for two days, before it expires.
  You must request a new one if expired, with the "refresh_token" grant.
  You can do this at any time, but only if necessary.

• expires_at: Lifetime of the token in seconds. This is not a unix timestamp.

• refresh_token: A long living refresh token, which never expires. Please store this securely and tell us if something went wrong, so we can invalidate it. This is only returned if the "grant_type" is "authorization_code".

Scopes

Currently you need to contact us to extend or reduce your scopes. As default "activityWrite" is set. Scopes are applied on the client. It is currently not possible for the user to change scopes on its own.

Available scopes:

• activityWrite: Upload activity files to Tredict.
• activityRead: Download the activity list and activity files from Tredict.
• bodyvaluesWrite: Upload health data, capacity values and body values to Tredict.
• bodyvaluesRead: Download health data, capacity values and body values from Tredict.

Endpoints

Activity list - Download

You can fetch a list of activities from the activitiy list endpoint.

GET https://www.tredict.com/api/oauth/v2/activityList
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request parameters:

Examples:

Start with newest activities: https://www.tredict.com/api/oauth/v2/activityList?pageSize=600

Start at date: https://www.tredict.com/api/oauth/v2/activityList?startDate=2019-07-10T14:14:46.257Z&pageSize=600

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

Response JSON object:

next will be undefined if it is the last page. For performance reasons there is no prev key, so this is an one-way traversal, starting with the newest activities.

{
  "_links": {
    "self": {
      "href": "https://www.tredict.com/api/oauth/v2/activityList?startDate=2020-02-27T18:20:33.000Z&pageSize=100"
    },
    "next": {
      "href": "https://www.tredict.com/api/oauth/v2/activityList?startDate=2019-07-10T14:14:46.257Z&pageSize=100"
    }
  },
  "count": 100,
  "_embedded": {
    "activityList": [
      {
        "_links": {
          "self": {
            "href": "https://www.tredict.com/api/oauth/v2/activity/wvCNvSYES8kd6mQDuf27kc"
          }
        },
        "id": "wvCNvSYES8kd6mQDuf27kc",
        "date": "2020-02-27T18:20:33.000Z",
        "sportType": "running"
      },
      {
        "_links": {
          "self": {
            "href": "https://www.tredict.com/api/oauth/v2/activity/oU6waMM9aPXdfFZw3DVRFf"
          }
        },
        "id": "oU6waMM9aPXdfFZw3DVRFf",
        "date": "2020-02-23T12:22:18.000Z",
        "sportType": "running"
      },
      ...
    ],
  }
}

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Activity - Download

You can fetch the details of an activity from the activity endpoint.

GET https://www.tredict.com/api/oauth/v2/activity/${activityId}
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

On a successfull request you will receive a JSON object with details of the activity like the summary and time series data of the heart rate, speed and so on.

Response JSON object:

{
  "_id": "i7QwbprV4VveXFSRHXcq1R",
  "date": "2020-02-21T14:09:01.000Z",
  "createdAt": "2020-02-21T14:40:55.008Z",
  "sportType": "running",
  "subSportType": "generic",
  "title": "Very short speed run",
  "notes": "",
  "summary": {
    "durationTotal": 1281,
    "duration": 1234,
    "distance": 3442.44,
    "altitude": {
      "ascent": 137,
      "descent": 157,
      "elevation": 35
    },
    "positionLat": 53.6718,
    "positionLong": 10.0099,
    "walkingDuration": 118,
    "calories": 202,
    "speed": 2.7890526315789383,
    "speedMax": 3.947,
    "heartrate": 152,
    "heartrateMax": 182,
    "power": 192,
    "powerMax": 278,
    "pace": 358,
    "paceMax": 253,
    "cadence": 163,
    "cadenceMax": 178
  },
  "timezone": "Europe/Berlin",
  "seriesSampled": {
    "sampleSize": 1,
    "endOffset": 0,
    "data": {
      "positionLat": [ ... ],
      "positionLong": [ ... ],
      "speed": [ ... ],
      "distance": [ ... ],
      "altitude": [ ... ],
      "heartrate": [ ... ],
      "cadence": [ ... ],
      "power": [ ... ]
    }
  }
}

All units are metric.
SportTypes are running, cycling, swimming and misc.
The series sampleSize is the number of seconds each data point in the series represents.

Possible keys in the summary:
durationTotal, duration, distance, altitude, positionLat, positionLong, walkingDuration, calories, speed, speedMax, heartrate, heartrateMax, respirationRate, respirationRateMax, power, powerMax, pace, paceMax, cadence, cadenceMax, temperature, strokes, poolLength

Possible keys in seriesSampled:
positionLat, positionLong, speed, distance, altitude, heartrate, cadence, power, respirationRate, temperature

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Activity file - Download

Download the activity as a raw file in .fit- or .tcx-format. The file extension depends on the original source.

GET https://www.tredict.com/api/oauth/v2/activity/file/${activityId}
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

On a successfull request you will receive a binary download with a content-type of application/octet-stream. The filename is included in the content-disposition header.

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Activity file - Upload

The activity endpoint takes .fit or .tcx workout files. .fit is preferable.

POST https://www.tredict.com/api/oauth/v2/activity/upload
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Content-Type: multipart/form-data
• Accept: application/json;charset=UTF-8

Request POST data:

The POST data should be formed as multipart form-data for file uploads, thus it should include a content disposition with a file field and filename definition.

Content-Disposition: form-data; name="file"; filename="activity-file.fit"

The mime-type does not matter, we check for the file type by extension and header checksums on our own.

Content-Disposition: form-data; name="name"

Optionally you can define the workout name as a "name" field, like "Strength training", which will show up in the activity list of the user then.

Content-Disposition: form-data; name="notes"

You also have the possibility to add an optional description via a "notes" field. This is constrainted to a maximum of 1024 characters.

Response JSON object entries:

On a successfull upload with HTTP response status 200, you will receive a JSON object with details of the upload.

The response object has a success-key with a list of workouts the file included. Normally this is only one, but could be more on a multi sport file.

{
  success: [
    {
      date: "2020-07-29T12:07:04.627Z", // This is the activity date
      trainingId: "eHvBqhSYoSiCKh4dK8mdv3"
    }
  ]
}

On an error with the file, the response object contains an error-key including an error string.

{
  error: "FILE_EXISTS",
  meta: [
    {
      date: "2020-07-29T12:07:04.627Z",
      trainingId: "eHvBqhSYoSiCKh4dK8mdv3"
    }
  ]
}
{
  error: "FILE_EXTENSION_UNSUPPORTED"
}
{
  error: "SPORT_TYPE_UNSUPPORTED"
}

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Planned training list - Download

You can fetch a list of planned training sessions from the planned training list endpoint.

GET https://www.tredict.com/api/oauth/v2/plannedTrainingList
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request parameters:

Examples:

Start from today: https://www.tredict.com/api/oauth/v2/plannedTrainingList
Start at date and filter by cycling: https://www.tredict.com/api/oauth/v2/plannedTrainingList?startDate=2019-07-10T14:14:46.257Z&sportType=cycling

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

Response JSON object:

The response includes all planned training sessions that were found.

{
  "count": 3,
  "_embedded": {
    "plannedWorkoutList": [
      {
        "id": "rKrytkDyXyDj81WbzraiNv",
        "date": "2021-11-13T09:35:32.465Z",
        "updatedAt": "2021-11-12T09:35:39.351Z",
        "timezone": -8,
        "sportType": "running"
      },
      {
        "id": "fa769DTeUzqjyegTqN9jJ9",
        "date": "2021-11-12T09:35:32.465Z",
        "updatedAt": "2021-11-12T09:35:39.367Z",
        "timezone": -8,
        "sportType": "misc"
      },
      {
        "id": "eh4GbpTxTGrPrdgBm3otum",
        "date": "2021-11-02T09:35:32.465Z",
        "updatedAt": "2021-11-12T09:35:39.380Z",
        "timezone": 2,
        "sportType": "cycling",
        "title": "This workout is in the past",
        "notes": "A slightly short description"
      }
    ]
  }
}

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Planned training - Download

You can fetch the details of an planned training session from the planned training download endpoint.

GET /api/oauth/v2/plannedTraining/file/json/${trainingId}?language=de&extraValues=1
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

Request parameters:

On a successfull request you will receive a JSON object with details of the planned training session.
The format and specification of the json object is adopted by the Garmin Training API for scheduled workouts.

Response JSON object:

{
  "workoutName": "Cycling workout",
  "description": "Description",
  "sport": "CYCLING",
  "steps": [{
    "type": "WorkoutRepeatStep",
    "stepOrder": 3,
    "repeatType": "REPEAT_UNTIL_STEPS_CMPLT",
    "repeatValue": 2,
    "steps": [{
      "type": "WorkoutStep",
      "stepOrder": 0,
      "intensity": "INTERVAL",
      "description": "Ramp-up",
      "durationType": "DISTANCE",
      "durationValue": 1000,
      "targetType": "POWER",
      "targetValueLow": 188,
      "targetValueHigh": 228
    }, {
      "type": "WorkoutStep",
      "stepOrder": 1,
      "intensity": "INTERVAL",
      "durationType": "DISTANCE",
      "durationValue": 1000,
      "targetType": "POWER",
      "targetValueLow": 217,
      "targetValueHigh": 257
    }, {
      "type": "WorkoutStep",
      "stepOrder": 2,
      "intensity": "INTERVAL",
      "durationType": "DISTANCE",
      "durationValue": 1000,
      "targetType": "POWER",
      "targetValueLow": 245,
      "targetValueHigh": 285
    }]
  }, {
    "type": "WorkoutStep",
    "stepOrder": 4,
    "intensity": "RECOVERY",
    "durationType": "TIME",
    "durationValue": 600,
    "targetType": "OPEN"
  }, {
    "type": "WorkoutRepeatStep",
    "stepOrder": 7,
    "repeatType": "REPEAT_UNTIL_STEPS_CMPLT",
    "repeatValue": 2,
    "steps": [{
      "type": "WorkoutStep",
      "stepOrder": 5,
      "intensity": "INTERVAL",
      "description": "Full out interval!",
      "durationType": "DISTANCE",
      "durationValue": 200,
      "targetType": "POWER",
      "targetValueLow": 300,
      "targetValueHigh": 340
    }, {
      "type": "WorkoutStep",
      "stepOrder": 6,
      "intensity": "REST",
      "durationType": "DISTANCE",
      "durationValue": 200,
      "targetType": "OPEN"
    }]
  }, {
    "type": "WorkoutRepeatStep",
    "stepOrder": 9,
    "repeatType": "REPEAT_UNTIL_STEPS_CMPLT",
    "repeatValue": 6,
    "steps": [{
      "type": "WorkoutStep",
      "stepOrder": 8,
      "intensity": "INTERVAL",
      "durationType": "DISTANCE",
      "durationValue": 100,
      "targetType": "POWER",
      "targetValueLow": 188,
      "targetValueHigh": 228
    }]
  }]
}

Response JSON object with provided extraValues=1 parameter:

{
  workoutName: 'Example running with Tredict extra values',
  sport: 'RUNNING',
  steps: [{
    type: 'WorkoutStep',
    stepOrder: 0,
    intensity: 'INTERVAL',
    durationType: 'TIME',
    durationValue: 600,
    targetType: 'POWER',
    targetValueLow: 209,
    targetValueHigh: 235,
    extraValuePower: 222
  },
  {
    type: 'WorkoutStep',
    stepOrder: 1,
    intensity: 'INTERVAL',
    durationType: 'DISTANCE',
    durationValue: 2280,
    targetProgressionType: 'ramp',
    targetType: 'SPEED',
    targetValueLow: 2.4691358024691357,
    targetValueHigh: 2.5974025974025974,
    extraValueCadence: 81,
    extraValueHeartrate: 155,
    extraValueSpeed: 2.5316455696202533,
    extraValuePower: 235
  }]
}

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Planned training file - Download

Download the planned training session as a Garmin workout .fit file.
This file can be used on the users device for a planned training session or could be parsed for further processing.

GET /api/oauth/v2/plannedTraining/file/fit/${trainingId}?language=de
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Accept: application/json;charset=UTF-8

On a successfull request you will receive a binary download with a content-type of application/octet-stream. The filename is included in the content-disposition header.

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "activityRead" scope enabled by us.

Health data and body values - Download

Download health data and body values in JSON format from this endpoint.

GET https://www.tredict.com/api/oauth/v2/bodyvalues
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Content-Type: application/json

Response JSON object:

{
  "bodyvalues": [
    {
      "timestamp": "2019-12-19T22:43:08.000Z",
      "timezoneOffsetInSeconds": 3600,
      "restingHeartrate": 53
    },
    {
      "timestamp": "2020-03-21T18:33:42.806Z",
      "timezoneOffsetInSeconds": 3600,
      "restingHeartrate": 54
    },
    {
      "timestamp": "2021-01-13T15:12:35.911Z",
      "timezoneOffsetInSeconds": 3600,
      "restingHeartrate": 53,
      "bodyHeightInCentimeter": 177,
      "weightInKilograms": 69.6,
      "bodyFatInPercent": 15.7,
      "bodyWaterInPercent": 61.6,
      "muscleMassInPercent": 44.5
    }
  ]
}

Status codes:

• 200: Request could be processed successfully.
• 400: The request is invalid or contains invalid data
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "bodyvaluesRead" scope enabled by us.

Health data and body values - Upload

The health data and body values endpoint takes an JSON-object with an array of bodyvalue objects to be processed in Tredict.
You can define as many values in the object as you need.

POST https://www.tredict.com/api/oauth/v2/bodyvalues
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Content-Type: application/json

POST body example with possible fields:

timestamp and timezoneOffsetInSeconds are mandatory fields, all other fields are optional.

{
  "bodyvalues": [
    {
      "timestamp": "2021-07-18T06:00:00Z",
      "timezoneOffsetInSeconds": 7200, // GMT+2
      "restingHeartrate": 48,
      "weightInKilograms": 68.2,
      "bodyHeightInCentimeter": 177.2,
      "bodyFatInPercent": 9.8,
      "bodyWaterInPercent": 63.2,
      "muscleMassInPercent": 45.6
    },
    {
      "timestamp": "2021-07-18T08:00:00Z",
      "timezoneOffsetInSeconds": 7200,
      "restingHeartrate": 50,
      "weightInKilograms": 69.2
    },
    {
      "timestamp": "2021-08-09T14:00:00Z",
      "timezoneOffsetInSeconds": 7200,
      "weightInKilograms": 70.2
    }
  ]
}

Status codes:

• 200: Request could be processed successfully.
• 400: The bodyvalues object is invalid or contains invalid data
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "bodyvaluesWrite" scope enabled by us.

Capacity values - Download

Download capacity values, like FTP or hrMax, in JSON format from this endpoint.

GET https://www.tredict.com/api/oauth/v2/capacity
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}
• Content-Type: application/json

Request parameters:

Response JSON object:

{
  "capacity": {
    "running": [{
      "timestamp": "2020-11-25T16:28:30.150Z",
      "timezoneOffset": 3600,
      "hrMax": 192,
      "hrLth": 166,
      "ftp": 235,
      "ftpa": 305
    }, {
      "timestamp": "2020-11-30T10:14:36.542Z",
      "timezoneOffset": 3600,
      "hrMax": 192,
      "hrLth": 168
    }],
    "cycling": [{
      "timestamp": "2019-12-05T11:52:47.000Z",
      "timezoneOffset": 3600,
      "hrMax": 191,
      "hrLth": 172,
      "ftp": 245,
      "ftpa": 92
    }, {
      "timestamp": "2020-12-02T15:11:54.738Z",
      "timezoneOffset": 3600,
      "ftp": 253,
      "ftpa": 91
    }],
    "swimming": [{
      "timestamp": "2020-01-19T22:45:06.695Z",
      "timezoneOffset": 3600,
      "hrMax": 179,
      "ftp": 246,
      "ftpa": 120
    }],
    "misc": [{
      "timestamp": "2020-06-02T23:55:10.099Z",
      "timezoneOffset": 7200,
      "hrMax": 191,
      "ftp": 246,
      "ftpa": 282
    }]
  }
}

Status codes:

• 200: Request could be processed successfully.
• 400: The request is invalid or contains invalid data
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired or it is out of scope.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Note: In order to make request on this endpoint, your client credentials needs to have the "bodyvaluesRead" scope enabled by us.

Deregistration

Please call the deregistration endpoint if the user wishes to disconnect via your application. Access token and refresh token of the according user will be deleted then.

If the user deregisters via our application, you can safely assume a deregistration by a refresh token request that returns 403.

DELETE https://www.tredict.com/user/oauth/v2/token
_{This is a similar example URL, you will receive the real URL together with your credentials.}

Request headers:

• Authorization: Bearer ${access_token}

Status codes:

• 200: Request could be processed successfully.
• 401: Invalid authorization header.
• 403: You provided an invalid access token. Maybe it is expired.
• 429: Too many requests.
• 500: Something went wrong on our side.
• 503: Sorry, we went to the pub.

Rate limits

Some endpoints are rate limited. Please ensure that you installed a proper retry or queue management on your side.

• Activity upload endpoint: Maximum of 8 request per second.
• Activity download endpoint: Maximum of 10 request per second.
• Token endpoint: Maximum of 20 request per second.

Media & Logos

For the visual integration on your side, you can find the Tredict logo and other media files on the media page.

If you have any further questions, do not hesitate to contact us.