Frequently Asked Questions
Getting access to the Suunto Cloud API & Api agreement
Can I get the access to the Suunto API Zone?
This depends on what you are working with. We can provide access to companies/organizations that are building tools/apps/services for commercial & non-commercial usage. However we do not provide this for personal use.
Where do i get access to Suunto Cloud API and the Suunto Api zone?
You can request to get access to suunto partner program by filling out the application from in the Suunto web site.
Where do I sign the API agreement?
The Suunto partner program application has a section on, which topics you are interested of working with Suunto. If you select Suunto Cloud API you will be provided the API agreement. This you need to sign, Same time with the API agreement signature you can provide the developers.
Where does the developers get the access to API zone?
In the Suunto partner program application, you are asked to provide the developers who would need to have the access. Ensure your team members are provided in this webform
How fast do i get the response?
If you have been accepted to the Suunto partner program, you should get the response in within two weeks.
I got information that we have been accepted, but I haven’t received invitation to API zone, what should i do?
Please ensure that you have checked the spam box also ask if you colleagues have got the invite or not. Based on this send an email to partners@suunto.com. We will then contact you and ensure your team gets the needed credentials.
We are a software development company, which is implementing an integration to Suunto Cloud API. How should we start?
Please ask your client company to submit the partner program application, so that they can sign the API Agreement. They can then provide your developers details in order for you to do the integration implementation.
Suunto Cloud API contents
What content can I get from the Suunto Cloud API?
You can get workouts and daily activities.
What data does the daily activities contain?
This contains daily steps and calories.
What data does the workouts contain?
The workouts are stored with Suunto watches and depend of the model. These can contain GPS tracks, heartrate samples, lap data. You can see the device capabilities from this document.
What contents can I push to Suunto Cloud API?
You can push routes and workouts.
What are routes?
The routes are GPX files which have route location data enriched with waypoints. The routes are shown in Suunto App and can be then synched to Suunto watches for navigation.
What does the workout push mean?
You can push the workouts in FIT file format for the users account. These are then shown in similar manner as data tracked with Suunto devices.
Is there sleep data available?
The Suunto Cloud API doesn’t yet support the sleep data fetch/push. This data is being tracked and stored with Suunto devise, but its not yet available from Suunto Cloud API.
Is there POIs available?
The Suunto Cloud API doesn’t yet support the point of interests. These are used in Suunto watches for navigation, but not yet supported by the Suunto Cloud api.
Is there personal data available?
Personal data such as weight data or heartrate zones are not available yet from Suunto Cloud API
How do I know if there is new content available from API?
Once you register to Suunto partner program, you will same time be included to newsletter which we are sending for participants when there are new capabilities available.
Movescount & Movescount API
I had earlier compatibility with Movescount API, what is the relationship between Movescount API and Suunto Cloud API?
There is nothing common with these. Movescount is completely separate system. In order to keep Suunto compatibility in place, please implement the connection with Suunto Cloud API.
What do I say for my Suunto users who are connected with Movescount?
The Movescount API will remain in place so the compatibility can work still in future, however we encourage people to change into Suunto App and therefore the Suunto Cloud API will be the way for Suunto Compatibility.
What is the best way to take the Suunto App into use?
Movescount users are able to transfer their workout history to Suunto App. They can also connect their Suunto watch to Suunto App. The latest Suunto watches Suunto 3, Suunto 5, Suunto 7 are only compatible with Suunto App.
Several Apps
We have several applications which would need to have a Suunto compatibility, how can this be managed?
In the case where you have several different apps /services i.e. testing environment and production environment, or two different branded services, you will need to have two different accounts. One account can have only one app. One account is associated to one email address. In order to run i.e. 10 different connections, provide us 10 different emails addresses.
Authorization flow
Where to start?
Read through the quick start guide. This give in few key steps on how to start the development. https://apizone.suunto.com/how-to-start
Where I can setup the redirect_uri and other application parameters?
You can do this in the OAuth and application settings. It's in your user profile.
Is there any mobile application authentication?
The authorisation process is optimized for mobile use. There is no mobile SDK at the moment.
I don't know how to fill up the Ocp-Apim-Subscription-Key header parameter?
Ocp-Apim-Subscription-Key parameter is required for Cloud API requests but not for OAuth related requests. The subscription key can be found from user profile page.
How can we link both Suunto and our user identities?
As user has authorized you to get his/her data, he will be redirected to the redirect_uri provided. This redirect_uri is given in app settings under your profile. There is an authorization code added to the redirect url. Use the authorization code to obtain JWT token. Request specification can be found here. Save JWT token information. In the the JWT token in the user field you will receive Suunto user name, which you can use later to handle notification about new user activities/workouts.
How to authenticate the request when exchanging authorization code a token?
The endpoint is protected using Basic authentication scheme in the following format:
Authorization: Basic Base64(clientid:clientsecret)
For example, if the OAuth application client id is a992f660-c50d-4bf7-905c-e706e42c9e9d and client secret is EDks3wJPnK6W, the resulting header should be:
Authorization: Basic YTk5MmY2NjAtYzUwZC00YmY3LTkwNWMtZTcwNmU0MmM5ZTlkOkVEa3Mzd0pQbks2Vw==
How to authenticate a request when making calls to the API?
Use the JWT tokens when making requests to APIs on https://cloudapi.suunto.com/ with a header in the following format:
Authorization: Bearer <jwt token>
What is a JWT token?
JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. You can read everything about JWT token from jwt.io.
How can I see what the JWT token contains?
You can debug the tokens in jwt.io. Just place the token into encoded field and see what are the information within the token in the decoded fields
Webhooks - Get the latest workout or daily activity
How can I ensure I get the users workouts immediately after it has been stored to Suunto cloud?
Use the webhook method to get a notification about new workouts. This enables you to fetch the workouts from the API immediately after its stored in Suunto Cloud.
What is a webhook?
Webhooks sometimes are also called reverse APIs. The main reason for these webhooks / notifications is to ensure that you don’t poll the server, but you can keep the data up to date in real time in your system by getting the information when to fetch. As there is new workouts coming in, you get immediately the information and can then fetch the latest workout. This also ensures that we don’t get large volume of these requests but only when these are really needed.
Where do i setup awebhook?
You can setup the webhook in your app oauth settings under your profile in Suunto Apizone In practice you set up the address where we will connect, this should be publicly accessible over the internet (i.e. no local computer addresses).
What happens with the webhook?
Once you register the address where will connect, your app will get a http request each time when there is new workouts synched to the server. Based on this information you should then fetch the workout immediately to keep your system up to date.
What is in the webhook notification?
Suunto partner notification has two parameters passed in the POST request username and workoutid. Username parameter can be used to find appropriate access token (in a JWT token user name stores in the user field). The workoutid parameter can be used to obtain correct FIT file.
How can i ensure I get the users daily activity immediately after it has been stored to Suunto cloud?
There is no webhook / notification model in place for activity data.
What is the best way to ensure I have the up to date information from the user in my system?
Set up the webhook for the workout data.
If you want to get the daily activity i.e. steps please fetch these at the same time as you fetch the workout data. Suunto watches are typically synched to Suunto App at the time when new workout has been created, so when there is new workout in Suunto cloud there is also new steps received.
You can additionally fetch the daily activity for the user i.e. once a day, just in case user has synched their device with Suunto app wihout workouts.
Getting user workouts from the API
When should I use the workout list API?
To get list of the workouts from the past history. I.e. you want to get all the workouts from the user from past month. Use the workoutlist to get the list of the workouts. If you need each workout with more details i.e. GPS data, then fetch each one with FIT files.
When should I use the FIT files?
Fit files has most comprehensive dataset from each workout. Consisting all the sample data, laps and summary value from each exercise. If you app / service needs all the workout data from suunto watches, use the FIT files.
When to use workout as JSON?
If you need workout summary information. Full workout data is available in a FIT File.
Workout data
What are the sports/activity types I can get from the API?
Suunto watches have several different activities user can use them with. You can find the list of the activities available in watches and Suunto App along with their IDs and how they are mapped to FIT files in this document.
What if the FIT file doesn’t have the sport supported?
FIT files several sports that the fit file doesn’t support these are marked with GENERAL id as 0
When does FIT file use "Sub Sport"?
There are some cases where FIT files uses the Sub sports i.e. Indoor rowing is Sport "Fitness equipment" ID 4 with Sub sport "Indoor Rowing" ID 14.
Which activity IDs are being used with workout list and workout as JSON?
The workout list and workout as JSON are using the Suunto App IDs.
What is SuuntoPlus?
SuuntoPlus is a concept which is being used in Suunto watches to create features in agile manner for sport modes. You can find the latest features from suunto.com/suuntoplus. The Suuntoplus data is stored in FIT files as developer fields.
Why doesn’t the workout have GPS track, barometric pressure, cycling power?
The missing data such as GPS track can be missing because the watch doesn’t have this capability. You can see the capabilities of each Suunto device from this document.
The watch has the tracking capability, but I don’t get the data?
Suunto watches can be used in different sports modes. These modes can be provided by Suunto as default or customized by the user him/herself. This makes it possible for example stop GPS tracking or heartrate measurements.
Workout time and time zones
How do I know when the workout has been done (workout JSON)?
In the JSON document returned by workout list endpoint you can find startTime, stopTime and timeOffsetInMinutes attributes.
startTime is an integer in UNIX epoch milliseconds specifying when the workout was started.
stopTimeis an integer in UNIX epoch milliseconds specifying when the workout was stopped.
timeOffsetInMinutes is an integer in minutes specifying the user's local time difference to UTC at the time when the exercise stopped.
How do I know when the workout has been done (FIT file)?
FIT session message start_time -field specifies when the workouts was started.
FIT session message timestamp -field specifies when the workouts was stopped.
FIT activity message local_timestamp field and it's difference to timestamp field in the same message can be used to determine the user's local time difference to UTC at the time when exercise started. See here for details.
Daily activity
What data can I get from daily activity?
You can get steps and calories.
How do I get the latest steps/calories?
The webhook model is in place only for the workouts. This means that when workout is stored you can get notification which indicates there is new data, so you can get this immediately fetched to your service/app. Majority of the Suunto watch owners are actively doing workouts and synching their watches with this information. Once you get the notification from the workout and you are interested of the daily steps/calories, fetch this at the same time. The notification from the workouts mean that the watch has been synched and you have the latest activity data available. If you don’t get workout notification for the user for the whole day, then try to fetch the latest daily activity data i.e. once a day for keeping up to date. You can also create interaction in your app/service, which ensures that data is uptodate. For example, by providing “synch” button or a specific view which does the data fetching if user opens it. Avoid unnecessary polling of the API, so if you do lot of api calls without no new data. Please reconsider your implementation.
Testing
How can I test the calls I'm using?
There is try-it button in the API description pages at ApiZone. You need to provide authorization and Ocp-Apim-Subscription-Key in order to test the API.
How can I test the integration?
There is a possibility to test the integration by using Suunto watch with Suunto App. The development with the API is done with the production system, so you can use the real data from your testers with your app/service.
There is also example FIT files available, which you can use to check on how to your solution is utilizing the fit files in difference scenarios i.e. with swimming data, multisport etc.
Where can I get the FIT files for testing?
You can find them here.
Can I get a product for testing from Suunto?
We are not able to provide a Suunto watches for partner companies, but if you contact us we can provide partner companies a deal for Suunto watches.
What are the limits when testing with developer API?
There developer API has same capabilities as the production API. However, the number of calls you can do with developer API are rate-limited.
Publishing
How can I go public with my service/app?
When you are ready with your implementation, please subscribe to the Production API. We will then connect you for next steps.
How do I publish my service/app?
Please ensure you have all the key contents published in API zone. You can find this from your profile and there form app contents.
How I’m getting my service/app shown in Suunto App?
Once you have finalized your implementation and added all the contents about your app in APIzone. Please subscribe to production. One we accept your subscription, you will be shown in Suunto App.
I need to get my app published in China for Suunto ZH, what should I do?
Please do the development work in Apizone. Once you are ready, contact us. We will then provide you the access to our Chinese API. This is technically the same, just with different address endpoints.
I would like to have my app/service as part of Suunto Valuepack, what can I do?
Suunto Valuepack is combination of offers that Suunto partners are providing for Suunto watch buyer. These offers are better deals that one would normally publicly and are only available with new Suunto watch buyers. Contact us at partners@suunto.com to learn more.
Errors / Issues
I receive an error 500 with description "internal server error" when using the workout API, what does this mean and what can I do?
Common issues with this is that you haven’t provided right parameter as a workout key, when you trying to fetch a workout. Workout key format: hexadecimal string, key length - 12 bytes.
I received an error 401 with unauthorized message "bad client credentials", what could be the cause?
Common issues are users using the Movescount credentials, these do not work. User needs to use the Suunto App credentials. Ensure that your authorization header is correct, read more from authorization flow section.
It seems like there was downtime on the weekend and today the API seems to respond slowly, can I see the status somewhere?
Currently we don’t have a view where to find status for different API endpoint We are looking into this. You can expect a larger data volume on weekends as people are more active and doing more workouts. Our goal is to provide the API that functions well also in busy times, but you should also prepare for higher loads during these times. There is also spikes for example in start of the year, this is based on people just getting more active.