Route API
Suunto watches navigation features
Suunto watches have various navigation related functionalities:
Route navigation
Route navigation displays the route and an arrow representing user's current location and direction. Depending on the watch model, planned route's altitude profile and user current position in it can be displayed also.
The user is alerted if the user leaves the route or when he arrives on a special waypoint on the route.
The Route navigation that is being used Suunto watches can be compared to track navigation in GPX documentation. Suunto route navigation and GPX document track navigation refer to a mode where location points create an exact path to follow. The GPX documentation refers route navigation as set of GPS locations where navigation is from point to point. Suunto watches behave same way if its a path or set of individual GPS points.
See here for an example of route navigation (with Suunto 5):
Suunto 5 manual - routes
POI navigation
POI navigation displays direction and distance to a point of interest chosen by the user.
See here for an example of POI navigation (with Suunto 5):
Suunto 5 manual - Points of Interest
The POIs can be created in the watch and are not supported by the Suunto Cloud API.
Map
Map view displays a map and the user's current location.
See here for an example of maps (with Suunto 7):
Suunto 5 manual - Maps
The map is currently only available in Suunto 7 and is not supported by the Suunto Cloud API.
Suunto API features
Suunto Route API enables importing routes in GPX format which the user can choose to use in watch for route navigation and exporting routes user created in Suunto App to partner services
GPX Format
GPX, or GPS Exchange Format, is an XML schema designed as a common GPS data format for software applications. It can be used to describe waypoints, tracks, and routes:
https://www.topografix.com/gpx/1/1/
See below for examples and details on what GPX features Suunto Cloud supports.
GPX examples
The example GPX files are available here:
GPX example files
example-route.gpx
Description:
GPX route (rte -element)
Separate waypoints (wpt -elements)
Route name in metadata
Optional single link in metadata. If available - will be used in Suunto App to provide back link to the route on the partner website or deep-link in the partner app
Notice that the coordinates of a wpt match coordinates of a rtept.
<?xml version="1.0" encoding="UTF-8" standalone="no"?><gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd" creator="Some GPX creator" version="1.1"><metadata><name>Example GPX with route and waypoints</name><link href="https://www.suunto-partner-x.com/routes/123"/></metadata><wpt lat="51.498457" lon="-0.117296"><name>Begin</name><desc>Auto-generated</desc><type>Begin</type></wpt><wpt lat="51.500830" lon="-0.119996"><name>Thames</name><type>River</type> </wpt><wpt lat="51.500864" lon="-0.122035"><type>Sight</type></wpt><wpt lat="51.501012" lon="-0.124601"><name>Big Ben</name><type>Building</type></wpt><wpt lat="51.501021" lon="-0.126423"><name>Sir Winston Churchill Statue</name><type>Waypoint</type></wpt><wpt lat="51.501031" lon="-0.127297"><name>End</name><desc>Auto-generated</desc><type>End</type></wpt><rte><rtept lat="51.498457" lon="-0.117296" /><rtept lat="51.500518" lon="-0.116587" /><rtept lat="51.500830" lon="-0.119996" /><rtept lat="51.500864" lon="-0.122035" /><rtept lat="51.501012" lon="-0.124601" /><rtept lat="51.501021" lon="-0.126423" /><rtept lat="51.501031" lon="-0.127297" /></rte></gpx>
example-track.gpx
Description:
GPX track (trk -element)
Separate waypoints (wpt -elements)
Route name in metadata
Notice that the coordinates of a wpt match coordinates of a trkpt.
<?xml version="1.0" encoding="UTF-8" standalone="no"?><gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd" creator="Some GPX creator" version="1.1"><metadata><name>Example GPX with track and waypoints</name></metadata><wpt lat="51.498457" lon="-0.117296"><name>Begin</name><desc>Auto-generated</desc><type>Begin</type></wpt><wpt lat="51.500830" lon="-0.119996"><name>Thames</name><type>River</type></wpt><wpt lat="51.500864" lon="-0.122035"><type>Sight</type></wpt><wpt lat="51.501012" lon="-0.124601"><name>Big Ben</name><type>Building</type></wpt><wpt lat="51.501021" lon="-0.126423"><name>Sir Winston Churchill Statue</name><type>Waypoint</type></wpt><wpt lat="51.501031" lon="-0.127297"><name>End</name><desc>Auto-generated</desc><type>End</type></wpt><trk><trkseg><trkpt lat="51.498457" lon="-0.117296" /><trkpt lat="51.500518" lon="-0.116587" /><trkpt lat="51.500830" lon="-0.119996" /><trkpt lat="51.500864" lon="-0.122035" /><trkpt lat="51.501012" lon="-0.124601" /><trkpt lat="51.501021" lon="-0.126423" /><trkpt lat="51.501031" lon="-0.127297" /></trkseg></trk></gpx>
example-track-detailed-points.gpx
Description:
GPX track (trk -element)
Track points with elevation, name, type
Route name in trk
The name and/or type in track/route points are an alternative way to the separate wpt -elements for importing waypoints.
<?xml version="1.0" encoding="UTF-8" standalone="no"?><gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd" creator="Some GPX creator" version="1.1"><trk><name>Example GPX with track and detailed points</name><trkseg><trkpt lat="51.498457" lon="-0.117296"><elevation>9</elevation><name>Begin</name><desc>Auto-generated</desc><type>Begin</type></trkpt><trkpt lat="51.500518" lon="-0.116587"><elevation>17</elevation></trkpt><trkpt lat="51.500830" lon="-0.119996"><elevation>7</elevation><name>Thames</name><type>River</type></trkpt><trkpt lat="51.500864" lon="-0.122035"><elevation>4</elevation><type>Sight</type></trkpt><trkpt lat="51.501012" lon="-0.124601"><elevation>18</elevation><name>Big Ben</name><type>Building</type></trkpt><trkpt lat="51.501021" lon="-0.126423"><elevation>17</elevation><name>Sir Winston Churchill Statue</name><type>Waypoint</type></trkpt><trkpt lat="51.501031" lon="-0.127297"><elevation>18</elevation><name>End</name><desc>Auto-generated</desc><type>End</type></trkpt></trkseg></trk></gpx>
Route features
Route name
Route names are shown in Suunto watch as a list where user can choose the route to navigate. Other details such as the route distance may be shown on the list also.
The name is determined from one of these GPX elements, ordered by priority:
rte.name or tkr.name
rte.description or tkr.description
metadata.name
metadata.description
If the name is still not found the name defaults to 'Unnamed route'.
When the name is displayed in Suunto watch, the name may be truncated and incompatible characters removed depending on watch model.
Route activities
List of suitable activities for the route. The activities are shown in Suunto app inside route details.
The activities are determined from query string parameter activities used in POST. The value of the parameter should be a list of comma separated integers where the integers is a valid Suunto activity ID. See Suuntoapp ID -column in this document:
Activities.pdf
If list of activities is not given, the default, 1 (running) is used.
The GPX file content has no effect on the activities.
Route points
The route points determine the coordinates to follow when navigating the route in watch.
The route points can be given in GPX trk or rte -elements.
If a single GPX file has multiple trk or rte -elements, each one is imported as a separate route.
The elements may have a name or desc which determines the route name. See "Route name".
The following data is imported from rtept or trkpt -elements:
latitude
longitude
elevation
name (*)
type (*)
* If the element has name or type, a waypoint will be generated. See Waypoints for details.
Waypoints
During the navigation user is alerted when coming in close proximity of the waypoint. Normally being used to identify specific locations, crossroads, camping sites etc.
Waypoints are generated from:
wpt -elements that have same coordinates as some rtept or trkpt -element.
rtept and trkpt -elements that have name and/or type.
The data imported from above mentioned elements are:
name
type
latitude
longitude
elevation
An unnamed waypoint is created if name is missing but a type exists.
A waypoint with type Waypoint is created if type is missing but a name exists.
The type of waypoint determines the icon shown in Suunto watches. The type can be one of (case-insensitive):
Begin
Building
Cafe
Camp
Camping
Car
Cave
Cliff
Coast
Crossroads
Emergency
End
Food
Forest
Geocache
Hill
Home
Hostel
Hotel
Info
Lake
Lodging
Meadow
Mountain
Parking
Peak
Restaurant
River
Road
Rock
Sight
Trail
Valley
Water
Waterfall
Waypoint
If the type is not any of the above, the default, Waypoint is used.
When the waypoint name is displayed on Suunto watch, it may be truncated and incompatible characters removed depending on watch model.
Route Export API usage
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. Get list of user's routes
curl -X GET "https://cloudapi.suunto.com/v2/route" \
-H "Authorization: <your access token> \
-H "Ocp-Apim-Subscription-Key: <your subscription key>"
Response is a list with routes info, sample:
[
{
"id": "604bcfc20a76e57785370afe",
"description": "Kerava - Sipoo",
"visibility": "PRIVATE",
"activityIds": [ 3 ],
"startPoint": { "altitude": 61, "latitude": 60.39826, "longitude": 25.13782 },
"centerPoint": { "altitude": 37, "latitude": 60.350983, "longitude": 25.15516 },
"endPoint": { "altitude": 45, "latitude": 60.314384, "longitude": 25.113018 },
"created": 1615581137000,
"averageSpeed": 2.2222223,
"totalDistance": 13696,
"modified": 1640418238351,
"watchEnabled": true,
"turnWaypointsEnabled": false
},
...
]
To find list of query parameters consult apizone spec.
Note: We currently do not impose any rate limits on the Routes Listing API but we prohibit polling. If you need to monitor routes updates you shall subscribe to notifications using WebHook (see below).
3. Get Route as GPX file
To get actual route with all waypoints in GPX format
curl -X GET "https://cloudapi.suunto.com/v2/route/{id}/export" \
-H "Accept: application/gpx+xml" \
-H "Authorization: <your access token> \
-H "Ocp-Apim-Subscription-Key: <your subscription key>"where {id} is id of route you got from listing response or via webhook.
4. Routes Updates Notification WebHook
To subscribe for routes updates notifications you should set "Route Notification Url" in developer portal. Contact support if you're not able to do that. When user create new or modify route the URL will be called back from us. Sample request body:
{
"username": "sampleuser",
"route": {
"id": "604bcfc20a76e57785370afe",
"description": "Kerava - Sipoo",
"visibility": "PRIVATE",
"activityIds": [ 3 ],
"startPoint": { "altitude": 61, "latitude": 60.39826, "longitude": 25.13782 },
"centerPoint": { "altitude": 37, "latitude": 60.350983, "longitude": 25.15516 },
"endPoint": { "altitude": 45, "latitude": 60.314384, "longitude": 25.113018 },
"created": 1615581137000,
"averageSpeed": 2.2222223,
"totalDistance": 13696,
"modified": 1640418238351,
"watchEnabled": true,
"turnWaypointsEnabled": false
}
}using this data (and JWT tokens you have) you shall be able to request route as GPX file