Introduction
Suunto's data model is narrower than Polar's or Garmin's but deeper in the specific dimension that matters most to outdoor athletes: altitude. If you are building a training app for trail runners, mountain bikers, alpinists, hikers or any athlete whose training involves significant elevation change, Suunto integration provides data capabilities that no other major wearable API matches.
This guide covers the practical integration work: OAuth setup, handling the subscription or polling model for new workout delivery, parsing GPS and altitude data, building altitude-aware training load features, working with Training Effect scores, handling the sport type taxonomy, and structuring a multi-provider backend where Suunto users and Garmin or Polar users produce normalized outputs.
Integration Setup
Register your application at developer.suunto.com. Specify your application name, description and redirect URI. You will receive a client_id and client_secret. These are environment-agnostic in the Suunto developer portal (unlike Samsung which issues separate credentials per environment), so maintain your own environment separation by using different redirect URIs and keeping credentials in environment-specific configuration files.
Implement the OAuth 2.0 authorization code flow. Direct the user to Suunto's authorization endpoint with your client_id, redirect_uri, response_type of code, and the scope parameter. The primary scope for workout data is workout. After authorization, exchange the code for tokens at Suunto's token endpoint.
Persist the user's access token and refresh token in your database. Implement token refresh logic that detects access token expiry (check the expiry timestamp before each request rather than waiting for a 401) and exchanges the refresh token for a new access token. Log all token operations for debugging. Handle permanent authorization failures (where refresh also fails) by marking the user's Suunto connection as inactive and surfacing a reconnect prompt.
Fetching Workout Data
Suunto workout data is fetched through two mechanisms: webhook notifications and polling. For production applications with reliable webhook infrastructure, register your callback URL so Suunto sends a notification when a user syncs a new workout. The notification contains the workout ID. Fetch the full workout details in a subsequent request to the workouts endpoint using that ID.
For polling-based implementations, request the workouts list for a user filtered by a start timestamp. Store the timestamp of the most recently processed workout per user and use it as the cursor for subsequent polling requests. Run polling jobs hourly per user on a schedule. This approach is simpler to operate than webhook-based delivery and sufficient for most training app use cases where near-real-time data delivery is not required.
When fetching a workout, request the full detail including the samples (the time series data for GPS, heart rate, altitude, cadence and speed). The workout summary endpoint provides aggregate metrics. The samples endpoint provides the per-point time series needed for GPS tracks and altitude profiles. For storage efficiency, decide upfront whether you need to store raw sample data or only the computed summaries. Raw sample storage enables reprocessing and visualization features but requires significantly more storage.
Building Altitude-Aware Training Load
A standard training load model based only on heart rate and duration underestimates the effort of uphill and trail workouts. A 90-minute trail run with 800 meters of ascent has a physiological cost that is significantly higher than a 90-minute flat road run at a similar average heart rate, because the muscular demand of climbing is not fully captured in heart rate.
Two approaches for altitude-aware load modeling: the Training Effect approach and the grade-adjusted approach. Training Effect (Aerobic TE and Anaerobic TE from the Suunto API) incorporates the heart rate response to the entire session including the climbing effort, so using Training Effect as your load metric implicitly captures altitude stress through heart rate. This approach works but is opaque to users who want to understand why a session felt hard.
The grade-adjusted approach uses the GPS track and altitude profile to compute grade-adjusted pace (GAP) for each GPS sample. GAP normalizes pace to the equivalent flat-ground pace using a grade factor. Common approximations add roughly 10 seconds per kilometer per percent of grade for uphill segments. Compute the total GAP-adjusted equivalent duration for the session as the training load input. This approach makes the altitude adjustment transparent and auditable.
Track weekly cumulative ascent as a separate metric from distance and duration. A trail runner whose weekly mileage stays constant but whose weekly vertical gain doubles has meaningfully increased their training load even if heart rate data looks similar. Surface weekly vertical as a trend metric in training plan features.
Working With Training Effect Scores
Suunto's Training Effect scores use the Firstbeat Analytics methodology, the same system used by Polar and Garmin. Aerobic Training Effect (1.0-5.0) indicates the session's expected aerobic adaptation stimulus. Anaerobic Training Effect (1.0-5.0) indicates anaerobic adaptation stimulus. Both are available for most run and cycle sport types on supported devices.
The five-level scale maps to: 1 (minor effect), 2 (maintaining fitness), 3 (improving fitness), 4 (highly improving fitness), 5 (overreaching). For coaching features, the useful application is tracking the distribution of Training Effect levels across a training week or month. A periodized training plan for endurance athletes should produce a mix of level 2-3 aerobic sessions (the base work) with occasional level 3-4 sessions and rare level 4-5 sessions.
If Training Effect is not available for a session (because the sport type does not support it, the device does not have the feature, or the user trained without a heart rate source), handle the null gracefully. Fall back to a simpler load estimate based on duration and average heart rate relative to the user's maximum heart rate.
Sport Type Normalization
Suunto's sport type identifiers are string-based (for example trail_running, cycling, swimming_pool, mountain_biking). Map these to your application's internal activity taxonomy. Create a mapping table that associates each Suunto sport type string with your canonical activity category. Handle unmapped sport types by assigning them to a generic activity category rather than dropping the workout.
For multi-provider normalization, create a cross-provider sport type map that aligns Suunto sport types with Garmin, Polar, Samsung and other providers' sport type codes. This is tedious to build but critical for features that analyze training distribution across sport types: a user who trains with both a Suunto watch and a Garmin watch (using different devices for different activities) should have their cycling workouts aggregated regardless of which device recorded them.
The Recovery Gap and Multi-Provider Architecture
Suunto's API does not provide sleep or recovery data. This is a significant gap for building holistic training apps. Trail runners need recovery guidance as much as any other athlete, but Suunto data alone cannot support it. Design your multi-provider architecture to pair Suunto with a recovery-focused provider for users who need both training load tracking and recovery monitoring.
A common pairing is Suunto for training data plus Oura or Whoop for recovery data. The user connects both providers. Training load from Suunto is evaluated against recovery status from the ring or band. For users who only have Suunto connected, surface training load trends without recovery context and recommend adding a recovery provider if they want training recommendations.
Open Wearables
Open Wearables provides Suunto API integration including OAuth management, the subscription and polling model, GPS and altitude data extraction, and normalization to the common multi-provider schema. Altitude-specific fields are preserved as provider extensions alongside normalized workout summaries.
For teams building outdoor sport training applications, Open Wearables provides normalized Suunto data alongside Garmin, Polar, Whoop and other providers through the same pipeline. Self-hosted, MIT licensed, no per-user fees.
FAQ
Can I get historical workouts when a user first connects their Suunto account?
The Suunto API provides access to workouts for a defined lookback window from the time of connection. Check Suunto's current API documentation for the specific backfill window, as it may change. For new users, run a backfill job that fetches all available historical workouts as part of the onboarding flow.
Is GPS data available for all sport types?
GPS data is only available for sport types where GPS recording is enabled and the session was recorded outdoors. Pool swimming, indoor gym sessions, treadmill runs and other indoor activities will not have GPS tracks. Always check for the presence of GPS samples before attempting to display a route map or compute grade-adjusted metrics.
How do I handle users with both Suunto and another provider connected?
Implement deduplication logic based on session start time, duration and sport type. A workout recorded on a Suunto watch and exported to Strava might appear via both a Suunto integration and a Strava integration. Define a canonical source priority per sport type or apply a deduplication rule that prefers the native device provider over aggregators.
Suunto Integration
View the full Suunto integration documentation on Open Wearables.
See Related Articles
Suunto API: Accessing Watch Data for Developers
