Tredict API - OAuth2 documentation

This guide enables you to authorize our users into your application via OAuth2 and upload or related activities to our activity endpoint, download a list of activties or upload health data to the users account.

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

Name Required Description
client_id Yes Your client_id you received from us.
state No Some optional url encoded state you can attach and we will send you back as a parameter on the callback url.
You can track back the authorization code to your user by using one time keys.
Please do not attach sensitive information here!

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

Error code Description
server_error The authorization server itself encountered an unexpected condition.

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:

Name Required Description
grant_type Yes This can be "authorization_code" or "refresh_token".
code (Yes) If the grant_type is "authorization_code" this field is required and must be a valid authorization code.
refresh_token (Yes) If the grant_type is "refresh_token" this must be the refresh token you received already by an earlier request.

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 and body values to Tredict.

Endpoints

Activity - 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.

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:

Name Required Description
startDate No If omited, the first list entry will be the newest activity. Must be an UTC ISO date string. F.ex. `2019-07-10T14:14:46.257Z`
pageSize No Defaults to 500. Amount of activities a request should return at maximum. Must be at least 50 and not more then 1000.

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.

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.

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 6 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.


composed at 7/29/2020, 12:28:39 PM by Felix Gertz