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.

1. Registration and auth

Please consult main Suunto Cloud API quick start to setup application and auth. After that you should have access token and subscription key.

2. Workout Upload Workflow overview

Workout Upload to Suunto Cloud API is multi-stage:

First you have to initialize an upload with required metadata to get upload id and link to upload location in object storage
Upload workout file to the storage
Monitor upload processing status and get a link to workout using id

Illustrated on the diagram:

The following paragraphs will describe these steps in more detail

3. 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'"
}

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

5. 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/ru-ru/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:

Also if allowed status response provides webUrl which can be used to open and view the uploaded workout in browser.