Stridee
Stridee Platform Docs

Routes

Send a route to your athlete's device as a course to follow, and know whether it landed.

A route is the other thing you can put on a watch: not what to do, but where. You send the GPX, TCX or FIT file, and we put it on your user's device as a course they can navigate.

post /v1/routes
Reference

Create a route and push it to your user's device.

The route is a GPX, TCX or FIT file. Its own name, description and sport are used unless you send them. A track over 10,000 points is thinned to fit, and an elevation profile with gaps is dropped rather than refused.

Stored, then pushed, then answered for — so pushes is what actually happened. Distance and elevation gain are computed from the track.

Garmin receives it as a Course, which needs the athlete to have granted Course Import; without it the push comes back failed with reason not_permitted and the route is still stored.

Body parameters
filestringRequired

The route: a GPX, TCX or FIT file, standard base64, up to 10 MB before encoding. The format is read from the content.

user_idstring · uuidRequired

The athlete, by our id for them.

descriptionstring

Defaults to the file's own (GPX <desc>, a TCX course's <Notes>).

namestring

What the athlete sees on the device. Defaults to the name in the file; required when the file has none.

providerstring

Which provider to push to. Omit to push to every connected provider that takes routes.

sportRouteSport

Defaults to the sport the file names, when it is one of these. Neither, and the device shows the course as "other".

Possible enum values
runningtrail_runningwalkinghikingcyclingroad_cyclingmountain_bikinggravel_cycling

You get back the route, with the name and sport we read from the file, the distance and climb we computed from it, and one entry per provider that was tried:

Everything Workouts says about the push holds here too: the call is synchronous, so pushes is what actually happened, and you only get a non-2xx when nothing could have worked.

POST /v1/routes
{
  "user_id": "4c9a7e15-6d3b-42f8-91c0-8e5b2a7d04f6",
  "file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPGdweCB2ZXJzaW9uPSIxLjEi…"
}
JSON
{
  "id": "e2a47c19-3b8d-4f05-9a61-d7c3e80b5f24",
  "user_id": "4c9a7e15-6d3b-42f8-91c0-8e5b2a7d04f6",
  "name": "Lakeside loop",
  "sport": "running",
  "distance": 12430.2,
  "elevation_gain": 86.0,
  "points": [ "…" ],
  "pushes": [
    { "provider": "garmin", "status": "synced", "external_id": "318840271" }
  ]
}

The file

file is the route file's bytes, base64-encoded (standard alphabet; line breaks are ignored). The body stays JSON, so it is signed like every other call.

  • GPX, TCX or FIT, up to 10 MB before encoding. We tell them apart by content, so there is no format field. Every route planner exports at least one of them. If you only have coordinates, write a GPX: a <trk> with one <trkpt lat lon> per point is enough.
  • The file holds the route's details, and we use them: the name (GPX <name>, a TCX course's <Name>, a FIT course's name), the description (GPX <desc>, a TCX course's <Notes>) and the sport. A FIT or TCX activity has no name in it, and neither do some GPX exports. Send name for those or you get a 422.
  • We repair what we can without guessing. A track over 10,000 points, which is Garmin's limit on a course, is thinned evenly to fit. An elevation profile with gaps or impossible values is dropped whole, and the route goes without elevation. A description over 2,000 characters is cut to fit. Anything else, such as a file with fewer than two points, is a 422 that names what is wrong.
  • distance and elevation_gain are computed by us from the track, so the number on the watch always matches the line on the map.

Overriding the file

Everything besides file is optional, and anything you send replaces what is in the file. Send sport when you know it: files have no standard sport vocabulary, so we recognise the common ones (Komoot's touring_bicycle is cycling) and leave the rest out.

Which providers get it

Only Garmin takes routes today, as a Course. Omit provider and it goes to Garmin if your user has it connected; naming any other provider is a 422.

Garmin needs the athlete to have granted Course Import. That is a separate switch from Workout Import on Garmin's consent screen, so an athlete who can receive your workouts may still refuse your routes. Without it the push comes back failed with reason not_permitted, and the route is still stored. When they reconnect with Course Import on, a PATCH pushes it again.

What each status means

status
syncedOn the device. external_id is Garmin's courseId.
unsupportedThis provider cannot take this route. Terminal; retrying changes nothing.
failedIt did not land. reason says why, and whether retrying can help.

The reason codes are the same as a workout's: not_permitted, not_connected, unsupported and provider_error. See Why a push did not land. There is no pending for a route, because a Garmin course either lands or it does not.

Editing and reading back

PATCH /v1/routes/{id} takes the whole route: a file, and any overrides. An override you leave out falls back to the new file's, not to the old route's. DELETE /v1/routes/{id} removes the course from Garmin, then from us, and answers 204 even if Garmin refuses.

GET /v1/routes/{id} returns the route with its points: the track as we read it from the file, at most 10,000 of them. The listing leaves them out to keep a page small.

lat and lng are degrees, WGS 84. elevation is metres above sea level, on every point or on none.

One point
{ "lat": 47.36667, "lng": 8.55, "elevation": 408 }

Rate limit

Route pushes share the 60 per minute device-push ceiling with workouts. It is one budget, because the provider limits us as one budget. See Rate limits.

Something wrong or missing on this page? Tell us in Discord. Need something the API doesn’t do yet? Request it on the roadmap.