Route API description

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 Route API enables importing routes in GPX format which the user can choose to use in watch for route navigation.

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:
Suunto Route API - GPX example files

example-route.gpx

Description:
  • GPX route (rte -element)
  • Separate waypoints (wpt -elements)
  • Route name in metadata

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>
  </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 from this document:
Suunto Watches- SuuntoApp- Movescount-FIT-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.