Terra's Routes API: Get training routes on your user's watch

Put any route on your user's watch, instantly

TL;DR: The Routes API is launched! It enables you to send a route directly to the user's watch. All you have to do is provide it with one route definition along with up to 10,000 waypoints, after which the route will be sent to their Garmin, COROS, or Wahoo devices through the connections that the users already have. Previously, you had to carry out a separate integration for each brand, using that brand's own file format. And each time a route is updated, a single call is enough to resync the new version to all the devices that have it.

What you can build with the Routes API

You set up a route (this might include between 2 and 10,000 waypoints, eight different sports, and also course points for water, food, summits, danger areas, and so on) and we then send it to the user's connected Garmin, COROS, or Wahoo device. The groups who had requested this service were mainly involved in one of a number of kinds of projects.

The coach will plan the long run for Saturday using a coaching platform, send it to all the members of the roster, and if the course is altered during the week the updated version will be sent to all of the athletes' watches at their next sync.
In order to have the official course on each registered athlete's device before the race starts, as well as to display the aid stations and the climbs, the race and event apps send out a late reroute in the same way.
Creating routes with the aid of AI. When your product can convert "90 minutes, hilly, ends at a bakery" into a course, then that course will be put on the watch so that it can be followed.
The clubs that organise the weekly group rides arrange it so that any member who has connected a device has the ride displayed on their handlebars, turn by turn.

One route object, translated into each device's format

Arrange the route first and then push it to a user who is connected.

# 1. create the route once
POST /v2/routes
{ "name": "Saturday long run", "sport": "running",
  "waypoints": [ { "latitude": 51.507, "longitude": -0.127,
                   "elevation_meters": 11 }, ... ] }

# 2. push it to a connected user
POST /v2/routes/{route_id}/push?user_id=...

The output we produce satisfies the requirements of each platform: JSON for Garmin's training API, a GPX file for COROS, and an encoded FIT file for Wahoo. As the various formats are used at different stages in the sport, each of them records the coordinates and elevation together with the course points in its own manner, and in fact the main part of the current work carried out here is keeping up with the changes to the formats and the firmware. All that is needed to update the information is to make a single call with the cascade flag enabled, which in turn causes the route to be pushed again to all the devices that already have it.

Device behaviour differences to design for

Each platform has its own design decisions and, if you know these before designing the user interface, you'll avoid having to deal with support tickets later on:

The course points are displayed on Garmin, while COROS and Wahoo focus on the track, which is the reason why your water-stop markers show up on some devices but not on others.
When you are using Garmin and one of the waypoints does not have an elevation value, the route will be provided without a profile and the device will then use its own terrain data to calculate the elevation (this method is better than using a profile that includes missing values).
On COROS the routes are processed on the device itself, so a route that you delete through the API will still be available on the device until the user decides to remove it.
The push call means that the platform has accepted the route and it appears on the watch when it synchronises next.

Worth wiring into your UI: you should delay the "it's on your device" message until the device has actually synchronised; all the push call does is confirm that the platform has accepted the route, while delivery doesn't take place until the next sync of the device.

The behaviours contained in the terra-routes agent skill are also applicable in this case, so if an AI coding agent is used to set up the integration it will inherit the edge cases together with the endpoints.

Why routes on the watch drive retention

Route planning is one of the most effective engagement loops in fitness software, and you do not have to take our word for that. Komoot was able to build up a user base of 45 million thanks to its "plan a route once, then follow it anywhere" feature. It is not necessary to have a full route planner in order to benefit from this kind of loop; the loop in fact exists as soon as any routes that the product creates or curates are on the user's device!

How to start pushing routes

The full schema and the per-device support matrix are available in the Routes API reference, and route push is carried out via the partner relationships that we hold with each platform, including the Garmin, COROS and Wahoo connections which your users currently have.

Terra's Routes API: Get training routes on your user's watch

What you can build with the Routes API

The coach will plan the long run for Saturday using a coaching platform, send it to all the members of the roster, and if the course is altered during the week the updated version will be sent to all of the athletes' watches at their next sync.

In order to have the official course on each registered athlete's device before the race starts, as well as to display the aid stations and the climbs, the race and event apps send out a late reroute in the same way.

Creating routes with the aid of AI. When your product can convert "90 minutes, hilly, ends at a bakery" into a course, then that course will be put on the watch so that it can be followed.

The clubs that organise the weekly group rides arrange it so that any member who has connected a device has the ride displayed on their handlebars, turn by turn.

One route object, translated into each device's format

Arrange the route first and then push it to a user who is connected.

# 1. create the route once POST /v2/routes { "name": "Saturday long run", "sport": "running", "waypoints": [ { "latitude": 51.507, "longitude": -0.127, "elevation_meters": 11 }, ... ] }

# 2. push it to a connected user POST /v2/routes/{route_id}/push?user_id=...

Device behaviour differences to design for

Each platform has its own design decisions and, if you know these before designing the user interface, you'll avoid having to deal with support tickets later on:

The course points are displayed on Garmin, while COROS and Wahoo focus on the track, which is the reason why your water-stop markers show up on some devices but not on others.

When you are using Garmin and one of the waypoints does not have an elevation value, the route will be provided without a profile and the device will then use its own terrain data to calculate the elevation (this method is better than using a profile that includes missing values).

On COROS the routes are processed on the device itself, so a route that you delete through the API will still be available on the device until the user decides to remove it.

The push call means that the platform has accepted the route and it appears on the watch when it synchronises next.

Why routes on the watch drive retention