List your routes

The routes you created or co-host, newest first

cURL

curl 'https://api.cyclemate.club/custom-routes/?limit=20' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "routes": [
    {
      "id": "78360cf7-0f4a-48f1-91ca-25e83db44aff",
      "alias": "culver-city-coffee-loop-1792536692813",
      "url": "https://cyclemate.club/explore/los-angeles/routes/culver-city-coffee-loop-1792536692813",
      "name": "Culver City coffee loop",
      "route_mode": "dynamic",
      "route": { "distance_m": 833.5, "duration_s": 200, "polyline": "ycunEbsoqUMu@EU??M?YH{Er…", "stops": ["…"] },
      "route_status": "ready",
      "…": "…"
    }
  ]
}

Overview

Returns the rider’s routes, newest first: the routes they created or co-host, whichever app created them. Each entry is the route without route.geometry; read a route by id for its line.

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.

Authorization: Bearer ACCESS_TOKEN

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.

Query parameters

Optional parameters

limit · integer · default: "20"

1 to 50.

Response body

routes · array

Routes, newest first, in the shape GET /custom-routes/{id}/ returns minus route.geometry.

cURL

curl 'https://api.cyclemate.club/custom-routes/?limit=20' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
  "routes": [
    {
      "id": "78360cf7-0f4a-48f1-91ca-25e83db44aff",
      "alias": "culver-city-coffee-loop-1792536692813",
      "url": "https://cyclemate.club/explore/los-angeles/routes/culver-city-coffee-loop-1792536692813",
      "name": "Culver City coffee loop",
      "route_mode": "dynamic",
      "route": { "distance_m": 833.5, "duration_s": 200, "polyline": "ycunEbsoqUMu@EU??M?YH{Er…", "stops": ["…"] },
      "route_status": "ready",
      "…": "…"
    }
  ]
}

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).

{ "error": "unknown field: colour", "code": "invalid_body" }

401 Unauthorized

Missing or invalid credentials, or an anonymous caller.

{ "error": "Missing user credentials" }

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.

{ "error": "Custom route not found", "code": "not_found" }

405 Method not allowed

{ "error": "Method not allowed", "code": "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".

{ "error": "Daily limit of 10 custom routes reached", "code": "daily_limit", "retry_after_seconds": 3600 }

500 Internal server error

{ "error": "Internal server error", "code": "internal_error" }