User GuideDeveloper DocsAPI Reference
EndpointsRoutes

Get route by ID or share token

Returns the route. `ref` is either a numeric route ID (owners see any visibility; non-owners only public, so sequential IDs can't be walked to discover unlisted routes) or a 32-hex share token (serves public and unlisted to anyone with the link). Private routes return 404 to non-owners. Owners authenticate with a cookie session or any PAT.

GET
/routes/{ref}

Path Parameters

ref*string

Route ID or 32-hex share token

Response Body

Route retrieved successfully

application/json
  1. response
id*number
name*string
description?string
activity?string
Value in"run""cycle""walk"
visibility*string
Value in"private""unlisted""public"
tags*array<string>
favourite*boolean

Whether the owner marked this route as a favourite

waypoints*array<>
geometry?array<string>

Routed polyline as an array of [lng, lat] coordinate pairs

distance?number

Distance in meters

duration?number

Duration in seconds

elevationGain?number

Elevation gain in meters

startAddress?string
endAddress?string
placeCity?string

Derived Place city (CONTEXT.md 'Place'). Server-derived, never user-edited.

placeRegion?string

Derived Place region.

placeCountryCode?string

Derived Place ISO 3166-1 alpha-2 country code.

routingPreferences?

Inputs that produced this route's geometry. Null for legacy / GPX-imported routes.

provenance*string

How this route was produced.

Value in"valhalla""mapbox-legacy""gpx-import""generation"
shareToken*string

Unguessable 32-hex handle for share links. Unlisted routes are only reachable anonymously via this token.

user*
createdAt*string
updatedAt*string
curl -X GET 'https://api.routess.com/routes/string'
{  "id": 0,  "name": "string",  "description": "string",  "activity": "run",  "visibility": "private",  "tags": [    "string"  ],  "favourite": true,  "waypoints": [    {      "coord": [        -74.006,        40.7128      ],      "type": "routed",      "name": "string",      "timestamp": "string"    }  ],  "geometry": [    "string"  ],  "distance": 0,  "duration": 0,  "elevationGain": 0,  "startAddress": "string",  "endAddress": "string",  "placeCity": "string",  "placeRegion": "string",  "placeCountryCode": "string",  "routingPreferences": {    "surfacePreference": "mixed",    "avoidFerries": true,    "avoidHighways": true  },  "provenance": "valhalla",  "shareToken": "9f86d081884c7d659a2feaa0c55ad015",  "user": {    "id": 1,    "name": "Jane Doe",    "handle": "jane-doe",    "avatar": "https://example.com/avatar.jpg",    "idHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"  },  "createdAt": "string",  "updatedAt": "string"}

Download route as GPX

Returns the route as a GPX 1.1 document with a routess-namespaced extension carrying per-waypoint Type. `ref` is a numeric route ID (owner: any visibility; non-owners: public only) or a 32-hex share token (public and unlisted). Private routes return 404 to non-owners. Owners authenticate with a cookie session or any PAT. Unlisted responses carry X-Robots-Tag: noindex.

Update route

Updates a specific route for the authenticated user.