How to use Suunto Workout Upload Cloud API

This guide describes the steps necessary to upload new workout to Suunto App using Suunto Workout Upload Cloud API.

Workout Upload workflow overview

Workout Upload to Suunto Cloud API is multi-stage:

  1. First you have to initialize an upload with required metadata to get upload id and link to upload location in object storage.

  2. Upload workout file to the storage.

  3. Monitor upload processing status and get a link to workout using id.

1. Registration and auth

Please consult main how to start -page to setup application and auth. After that you should have access token and subscription key.

2. Initialize upload

The following command will initialize the upload:

curl -X POST -H "Content-Type: application/json" \
--data '{"description": "some description", "comment": "Some Comment"}' \
https://cloudapi.suunto.com/v2/upload" \
-H "Authorization: <your access token>" \
-H "Ocp-Apim-Subscription-Key: <your subscription key>"

You can pass the following fields (all fields are optional):

  • description : string - Description of workout.

  • comment : string - Adds comment to workout, use it as notes.

  • notifyUser : boolean (default: true) - Set if user should receive push notification on workout arrival. Should be set to false in case of uploading workouts in bulk.

  • privacy : string ("DEFAULT", "PRIVATE", "FOLLOWERS" or "PUBLIC") - specify privacy of workout. If not set or set to DEFAULT then Suunto App user’s default privacy setting will be used.

You’ll get response like this:

{ 
  "id": "5e84cc54558f8b5f86061cc7", 
  "url": "https://suunto.blob.core.windows.net/fit/5e84cc54558f8b5f86131cc7?sv=2019-02-02&se=2020-04-02T05%3A16%3A04Z&sr=b&sp=racwd&sig=YefUFHzmy8tebjftYwsvUap8fGAOB7u452Kj2e3Ico%3D", 
  "headers": { "x-ms-blob-type": "BlockBlob" }, 
  "method": "PUT", 
  "description": "Some Description", 
  "comment": "Some Comment",
  "dataType": "FIT",
  "curlString": "curl -i -X PUT -T '/path/to/your/file' -H 'x-ms-blob-type: BlockBlob' 'https://suunto.blob.core.windows.net/fit/5e84cc54558f8b5f86131cc7?sv=2019-02-02&se=2020-04-02T05%3A16%3A04Z&sr=b&sp=racwd&sig=YeiFk5Hzmy8tebjftYxktUap8fGAOB6u452Kj2e3Ico%3D'" 
}

3. Upload file

Response from 3. contains url, method and additional headers you should use to make actual workout file upload.

We also generate stub curlString to demonstrate how to make upload request. Please use it to test API, do not use it in your application.

curl -i -X PUT -T '/Users/username/fit/someworkout.fit' -H 'x-ms-blob-type: BlockBlob' \
'https://suunto.blob.core.windows.net/fit/5e84cc54558f8b5f86131cc7?sv=2019-02-02&se=2020-04-02T05%3A16%3A04Z&sr=b&sp=racwd&sig=YeiFk5Hzmy8tebjftYxktUap8fGAOB6u452Kj2e3Ico%3D'

Output:

HTTP/1.1 100 Continue 
HTTP/1.1 201 Created 
Content-Length: 0 
Content-MD5: +jk3UdJ2XarxuJJdhco4Bw== 
Last-Modified: Wed, 01 Apr 2020 17:16:32 GMT 
ETag: "0x8D7D6606C9AD032" 
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0 
x-ms-request-id: fb0f71e7-a01e-0054-6c49-08ba78000000 
x-ms-version: 2019-02-02 
x-ms-content-crc64: 5Vq0tPNNN8E= 
x-ms-request-server-encrypted: true 
Date: Wed, 01 Apr 2020 17:16:31 GMT

HTTP response code 201 here means file was uploaded successfully.

Currently only FIT file format is supported.

Please note that while any valid FIT activity file can be uploaded, Suunto App currently supports showing only limited number of data fields from externally imported files. Please consult FIT file supported data documentation for more information about supported format.

4. Check status

Request:

curl -X GET \
"https://cloudapi.suunto.com/v2/upload/<upload id>" \
-H "Authorization: <your access token>" \
-H "Ocp-Apim-Subscription-Key: <your subscription key>"

Response:

{ 
  "id": "5e8a25493f9dd9080218bb52", 
  "name": "", 
  "description": "some description", 
  "dataType": "FIT", 
  "status": "PROCESSED", 
  "message": "", 
  "workoutKey": "5dc917eca6957b82c492027c", 
  "webUrl": "https://www.suunto.com/move/username/5dc917eca6957b82c492027c"
}

Available statuses:

/** Upload created, but no actual data has been received yet */ 
NEW, 

/** Data received */
ACCEPTED, 

/** Upload processed, new workout has been created */ 
PROCESSED, 

/** Error during upload processing */ 
ERROR

If status is PROCESSED then workoutKey will contain id of workout you can use to access it via other API endpoints

If status is ERROR then message may contain additional information.

6. Review results

If enabled user will receive notification about new workout available on his mobile device and can open it: