Skip to main content

​
Overview

Returns one route. Public and unlisted routes are readable by any signed-in caller; a private route only by its hosts.

​
Authentication

A Login with Cyclemate access token, or a signed-in rider’s session token. Every route belongs to a rider: your app acts for the rider who connected it, and the route is theirs. Your app reaches only the routes it created: a route the rider made in our apps, or through another app, answers 404.
An API key on its own is rejected, as are anonymous requests. To create routes as your organisation, sign up for a Cyclemate account and connect your app to it with Login with Cyclemate.

​
Rate limits

Riders and apps acting for them may make 60 requests a minute; a request that routes between stops counts once per hop. Every rider may create 10 routes in any 24 hours, counted across our apps and every connected app: the eleventh answers 429 with code: "daily_limit" and the seconds until a slot frees.

​
Path parameters

​
string
required
The route’s id.

​
Response body

​
string
The route’s id, a UUID string. Pass it as event_id to POST /multi-modal/v2/ to ride it.
​
string
The route’s link slug, chosen or generated from the name.
​
string
The route’s page on cyclemate.club.
​
string
​
string
​
string
​
string
public, unlisted or private.
​
string
dynamic (we re-plan the line between the stops as roads change) or fixed (the line is kept as given).
​
object
The page theme, when one is set. The same object you send.
​
array
Each { slug, name, emoji }.
​
string
Present on a group ride, with end_time, and max_rsvps and rsvp_questions when set.
​
boolean
With show_safety_colors, show_why_this_route and show_street_by_street: which sections the page shows.
​
string
The city the route is in: london, new_york_city, los_angeles or bay_area.
​
object
The rider who created the route: { name, slug, image_url }. null once that rider has deleted their account.
​
object
distance_m, duration_s, polyline (precision 5), geometry (a GeoJSON LineString; omitted in lists) and stops: the start then every stop in order, each { name, location }, with hidden: true on a shaping point that is not shown as a stop.
​
string
pending while we match the line to the road network (a fixed route) or plan it between the stops (a dynamic route), ready once turn-by-turn steps and the safety summary are stored, unavailable when the line could not be matched or no route exists between the stops. A pending route is already viewable and rideable; poll every few seconds.
​
array
Each { id, url, status, cover }. status is pending until our image check has run, then approved. Hosts see every image with its status; everyone else sees approved images only.
​
string
​
string

​
Variants

​
Polling for the plan

After a create or a route edit, route_status is pending for a few seconds. Poll this endpoint until it reads ready (steps and the safety summary are stored) or unavailable (the line could not be matched, or no route exists between the stops: edit the route to try again).

​
Error responses

Every error body is { "error", "code" }; error is a sentence, code is stable.

​
400 Bad request

Invalid body or query: the message names the field. code is invalid_body, or for a route input outside_coverage (the route starts outside the cities we cover), cross_city (its stops span two cities) or no_route (no cycling route exists between two stops).

​
401 Unauthorized

Missing or invalid credentials, or an anonymous caller.

​
404 Not found

No route with that id that you may see. A private route you do not host, a route you may read but not edit, and a route your app did not create all answer 404, never 403.

​
405 Method not allowed

​
429 Too many requests

The burst limit, with a Retry-After header; or the daily creation cap, which adds code: "daily_limit".

​
500 Internal server error