Working with Guides in Mobile App
This guide describes the steps necessary to upload Suuntoplus Guide to Suunto App using Cloud API.
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 to use later.
Prepare Suuntoplus Guide File
Create a SuuntoPlus Guide file by creating a ZIP with 2 files.
guide.json:
{
"name": "Pyramid interval",
"description": "Hard session which impacts an-aerobic threshold pace",
"shortDescription": "Hard session",
"localDate": "2021-05-28",
"type": "sequence",
"activities": [
3
],
"usage": "workout",
"owner": "CoachingPlatform",
"url": "https://www.coachingplatform.com/planwebsitetoreadmore/123456789",
"externalId": "123456789",
"steps": [
{
"type": "fields",
"trigger": {
"type": "stepDuration",
"value": 600
},
"title": "10 min warmup",
"fields": [
{
"type": "targetHeartRate",
"value": 111,
"min": 104,
"max": 148
},
{
"type": "heartRate"
},
{
"type": "power"
},
{
"type": "stepDurationCountdown",
"value": 600
}
]
},
{
"type": "notification",
"createManualLap": true,
"fields": [
{
"type": "text",
"value": "Interval #1 5min @ 90%"
}
]
},
{
"type": "fields",
"trigger": {
"type": "stepDuration",
"value": 300
},
"fields": [
{
"type": "targetHeartRate",
"value": 150,
"min": 145,
"max": 155
},
{
"type": "heartRate",
"window": "manualLap",
"aggregate": "average"
},
{
"type": "power"
},
{
"type": "stepDurationCountdown",
"value": 300
}
]
},
{
"type": "notification",
"fields": [
{
"type": "text",
"value": "Interval set 3x1min / 1min"
}
]
},
{
"type": "repeat",
"times": 3,
"steps": [
{
"type": "fields",
"createManualLap": true,
"trigger": {
"type": "stepDuration",
"value": 60
},
"title": "1 min int",
"fields": [
{
"type": "targetHeartRate",
"value": 180,
"min": 170,
"max": 185
},
{
"type": "heartRate"
},
{
"type": "power"
},
{
"type": "stepDurationCountdown",
"value": 60
}
]
},
{
"type": "notification",
"createManualLap": true,
"fields": [
{
"type": "text",
"value": "Rest"
}
]
},
{
"type": "fields",
"trigger": {
"type": "stepDuration",
"value": 60
},
"title": "1 min rest",
"fields": [
{
"type": "targetHeartRate",
"value": 140,
"min": 130,
"max": 145
},
{
"type": "heartRate"
},
{
"type": "power"
},
{
"type": "cadence"
},
{
"type": "stepDurationCountdown",
"value": 60
}
]
}
]
},
{
"type": "fields",
"createManualLap": true,
"trigger": {
"type": "stepDuration",
"value": 600
},
"title": "Cooldown",
"fields": [
{
"type": "targetHeartRate",
"value": 140,
"min": 130,
"max": 145
},
{
"type": "heartRate",
"window": "manualLap",
"aggregate": "average"
},
{
"type": "power"
},
{
"type": "stepDurationCountdown",
"value": 600
}
]
},
{
"type": "fields",
"title": "Good Job"
}
]
}icon.png:
300x300 PNG image, should not contain any private data (may be accessible via public link).
Here's an example how the above described ZIP file should look like:
More detailed specification of guide JSON is provided in SuuntoPlus Guide Description -page.
IMPORTANT NOTICE:
The owner -field in the guide.json should match your application name in OAuth settings (described in Suunto Cloud API quick start).
Create Suuntoplus Guide
You can create Suuntoplus Guide using the following command:
❯ curl -L -X POST "https://cloudapi.suunto.com/v2/guides/files" \ -H "Authorization: AUTH_KEY_HERE" \ -H "Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY" \ -H "Content-Type: application/zip" \ --data-binary "@/Path/to/guide.zip"
Response:
201 Created Content-Type: application/json { "error": null, "payload": { "id": "oxrgorwo", "username": "john1234", "modificationTime": 1634031291729, "fileModificationTime": 1634031291729, "name": "Pyramid interval", "description": "Hard session which impacts an-aerobic threshold pace", "shortDescription": "Hard session", "owner": "CoachingPlatform", "url": "https://www.coachingplatform.com/planwebsitetoreadmore/123456789", "iconUrl": "https://suuntoplusplugins.blob.core.windows.net/guide-icons/b930640f855f4d3432b8b331735e7762.png", "type": "sequence", "activities": [ 3 ], "localDate": "2021-05-28", "usage": "workout", "pinned": false, "externalId": "123456789" }, "metadata": { "ts": "1634031291785" } }
After that if you reload list of guides Suunto App version which supports Suuntoplus Guides, you should see your uploaded Guide and sync to watch if there is a compatible one.
If the guide is invalid response is:
400 Bad Request Content-Type: application/json { "error": { "description": "Invalid step type: 'notfication'" }, "payload": null, "metadata": { "ts": "1621925931041" } }
If the guide has an externalId and user has another guide with the same externalId the request with fail with response like this:
409 Conflict Content-Type: application/json { "error": { "description": "Conflict" }, "payload": null, "metadata": { "ts": "1621925931041" } }
Additional Guide API operations
List Guides
You can list user’s guides. Only guides created by your will be returned.
curl --location --request GET \ "https://cloudapi.suunto.com/v2/guides/items" \ -H "Authorization: AUTH_KEY_HERE" \ -H "Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY"
Response:
200 OK Content-Type: application/json { "error": null, "payload": [{ "id": "oxrgorwo", "username": "john1234", "modificationTime": 1634031291729, "fileModificationTime": 1634031291729, "name": "Pyramid interval", "description": "Hard session which impacts an-aerobic threshold pace", "shortDescription": "Hard session", "owner": "CoachingPlatform", "url": "https://www.coachingplatform.com/planwebsitetoreadmore/123456789", "iconUrl": "https://suuntoplusplugins.blob.core.windows.net/guide-icons/b930640f855f4d3432b8b331735e7762.png", "type": "sequence", "activities": [ 3 ], "localDate": "2021-05-28", "usage": "workout", "pinned": true, "externalId": "123456789" }, { "id": "kfusvysl", "username": "john1234", "modificationTime": 1621903258750, "fileModificationTime": 1621903258750, "name": "CI, hill", "description": "BT: Hill Cruise Intervals. Climb a 6 minute hill (4-6% grade), 5 times in heart rate 4-5a zones. Stay seated. Smooth pedaling. Higher gear than usual. 60-70 rpm.", "shortDescription": "Hill Cruise Intervals", "owner": "CoachingPlatform", "url": "https://www.coachingplatform.com/planwebsitetoreadmore/234567890", "iconUrl": "https://suuntoplusplugins.blob.core.windows.net/guides-images/f5970352382cc3add3862e78b35bbb4a.png", "type": "sequence", "activities": [ 2 ], "localDate": "2021-05-25", "usage": "workout", "pinned": false, "externalId": "234567890" }, { "id": "vy5600g9", "username": "john1234", "modificationTime": 1621903289710, "fileModificationTime": 1621903289710, "name": "HIM intervals (2h+)", "description": "BT: HIM intervals. Warm up 20 minutes. Then complete 4 x 20 minute intervals at HR zone 3 (5 minute recoveries). Aero position. Refuel as you will do in race.", "shortDescription": "HIM intervals", "owner": "CoachingPlatform", "url": "https://www.coachingplatform.com/planwebsitetoreadmore/345678901", "iconUrl": "https://suuntoplusplugins.blob.core.windows.net/guides-images/f5970352382cc3add3862e78b35bbb4a.png", "type": "sequence", "activities": [ 2 ], "localDate": "2021-05-26", "usage": "workout", "pinned": false, "externalId": "345678901" } ], "metadata": { "ts": "1621925931041" } }
The guides are sorted by fileModificationTime descending.
Request parameters
offset (Optional) Default value: 0
limit (Optional) Default value: 50 Limits the number of returned guides
fileSince (Optional) Epoch time in milliseconds. If set the endpoint returns only guides with fileModificationTime is equal or greater than the parameter value.
Update Guide File
It’s possible to update guide file (content).
This call will update only guide content (instructions), but not certain guide metadata such as pinned, username, id.
curl -X PUT \ "https://cloudapi.suunto.com/v2/guides/files/oxrgorwo" \ -H "Content-Type: application/zip" \ -H "Authorization: AUTH_KEY_HERE" \ -H "Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY" \ --data-binary '@/Path/to/guide.zip'
Response:
200 OK Content-Type: application/json { "error": null, "payload": { "id": "oxrgorwo", "username": "john1234", "modificationTime": 1634087654321, "fileModificationTime": 1634087654321, "name": "Pyramid interval", "description": "Hard session which impacts an-aerobic threshold pace", "shortDescription": "Hard session", "owner": "CoachingPlatform", "url": "https://www.coachingplatform.com/planwebsitetoreadmore/123456789", "iconUrl": "https://suuntoplusplugins.blob.core.windows.net/guide-icons/b930640f855f4d3432b8b331735e7762.png", "type": "sequence", "activities": [ 3 ], "localDate": "2021-05-28", "usage": "workout", "pinned": false, "externalId": "123456789" }, "metadata": { "ts": "1634031291785" } }
fileModificationTime and modificationTime properties in Guide metadata are updated when file updated.
If the guide is invalid the response is:
400 Bad Request Content-Type: application/json { "error": { "description": "Invalid step type: 'notfication'" }, "payload": null, "metadata": { "ts": "1621925931041" } }
If the guide does not exists, belongs to someone else or was updated by a different partner who created it, response is:
404 Not Found
If the guide has an externalId and user has another guide with the same externalId the request with fail with response like this:
409 Conflict Content-Type: application/json { "error": { "description": "Conflict" }, "payload": null, "metadata": { "ts": "1621925931041" } }
Delete Guide
You can delete guide created by you
curl -X DELETE \ 'https://cloudapi.suunto.com/v2/guides/files/oxrgorwo' \ -H "Authorization: AUTH_KEY_HERE" \ -H "Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY"
Response:
200 OK
If the guide does not exists, belongs to other user or created by other partner the response is:
404 Not Found
Download Guide File
You can download guide file created by you
curl -X GET \ "https://cloudapi.suunto.com/v2/guides/files/oxrgorwo" \ -H "Authorization: AUTH_KEY_HERE" \ -H "Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY" \ --output guide.zip
Response:
200 OK Content-Type: application/zip Content-Disposition: attachment; filename="oxrgorwo-guide.zip"
Returns a zip file in body.
If the guide does not exists, belongs to someone else or is requested by different partner who created it, response is:
404 Not Found
Working with Guides in Mobile App
If you have a Suunto App version which supports Suuntoplus Guides and Suunto watch with firmware which supports guide.
Open the app, click on the watch icon:
Select SuuntoPlus guides in the list:
And you can see your uploaded Guide in the list:
All UIs in the document are work in progress and subject to change.
Then you can upload guide to the watch. Check “Pin to watch”, go back to previous screen and press “Sync now”.
Working with Guides on the watch
On the watch go to Exercises and select proper activity type (Running for the sample above):
Then press down button to open options:
Select SuuntoPlus (middle button or tap):
In the list scroll down to the button, you’ll the guide you just uploaded. Select it by pressing middle button:
Now your guide is selected in options:
Go back to start screen (press up button) and start exercise (middle button):
Now exercise started, scroll all screens (using middle button) and you finally see the UI which represents the first step of your guide:
