Get multiple directions

curl -X POST "https://api.cyclemate.club/multi-modal/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
  }'

const response = await fetch('https://api.cyclemate.club/multi-modal/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin: [-73.9851, 40.7589],
    destination: [-73.9712, 40.7614],
  }),
});

const { search_id, routes } = await response.json();
console.log(`Found ${routes.length} route alternatives (search_id=${search_id})`);

import requests

url = "https://api.cyclemate.club/multi-modal/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
}

response = requests.post(url, headers=headers, json=data)
routes = response.json()

{
  "search_id": "4df7451e-e393-4a8d-8402-7842772a380e",
  "routes": [
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": true,
      "nighttime": false,
      "label": "SuperSafe™",
      "subtitle": null,
      "route": [
        {
          "step": 1,
          "type": "cycling",
          "startLabel": "Start route",
          "endLabel": "End",
          "route": {
            "code": "Ok",
            "routes": [
              {
                "distance": 3241.5,
                "duration": 777.3,
                "weight": 1.4,
                "weight_name": "bicycle",
                "elevation_gain": 12,
                "elevation_loss": 8,
                "geometry": { "type": "LineString", "coordinates": ["…"] },
                "legs": ["…"]
              }
            ],
            "waypoints": [
              { "distance": 0, "name": "", "location": [-118.240115, 34.049835] },
              { "distance": 0, "name": "", "location": [-118.260088, 34.069913] }
            ],
            "uuid": null
          }
        }
      ],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": false,
      "nighttime": false,
      "label": "Direct",
      "subtitle": null,
      "route": ["…"],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "Metro Bike Share",
      "type": "GBFS",
      "supersafe": true,
      "nighttime": false,
      "label": null,
      "subtitle": null,
      "has_live_availability": true,
      "route": [
        { "step": 1, "type": "walking", "endLabel": "7 bikes", "route": ["…"] },
        { "step": 2, "type": "cycling", "endLabel": "10 docks", "route": ["…"] },
        { "step": 3, "type": "walking", "endLabel": "End", "route": ["…"] }
      ],
      "destination": null,
      "pricing": {
        "currency": "USD",
        "unlock_fee": 1.75,
        "per_min_rate": null,
        "per_min_interval": null,
        "per_km_rate": null,
        "per_km_interval": null,
        "description": "$1.75 every 30 minutes."
      },
      "rental_uris": {
        "android": null,
        "ios": null,
        "logo": "https://auth.cyclemate.club/storage/v1/object/public/logos/metro_bike.png"
      }
    }
  ],
  "destination_parking": null
}

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 42
}

curl -X POST "https://api.cyclemate.club/multi-modal/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
  }'

const response = await fetch('https://api.cyclemate.club/multi-modal/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin: [-73.9851, 40.7589],
    destination: [-73.9712, 40.7614],
  }),
});

const { search_id, routes } = await response.json();
console.log(`Found ${routes.length} route alternatives (search_id=${search_id})`);

import requests

url = "https://api.cyclemate.club/multi-modal/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
}

response = requests.post(url, headers=headers, json=data)
routes = response.json()

{
  "search_id": "4df7451e-e393-4a8d-8402-7842772a380e",
  "routes": [
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": true,
      "nighttime": false,
      "label": "SuperSafe™",
      "subtitle": null,
      "route": [
        {
          "step": 1,
          "type": "cycling",
          "startLabel": "Start route",
          "endLabel": "End",
          "route": {
            "code": "Ok",
            "routes": [
              {
                "distance": 3241.5,
                "duration": 777.3,
                "weight": 1.4,
                "weight_name": "bicycle",
                "elevation_gain": 12,
                "elevation_loss": 8,
                "geometry": { "type": "LineString", "coordinates": ["…"] },
                "legs": ["…"]
              }
            ],
            "waypoints": [
              { "distance": 0, "name": "", "location": [-118.240115, 34.049835] },
              { "distance": 0, "name": "", "location": [-118.260088, 34.069913] }
            ],
            "uuid": null
          }
        }
      ],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": false,
      "nighttime": false,
      "label": "Direct",
      "subtitle": null,
      "route": ["…"],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "Metro Bike Share",
      "type": "GBFS",
      "supersafe": true,
      "nighttime": false,
      "label": null,
      "subtitle": null,
      "has_live_availability": true,
      "route": [
        { "step": 1, "type": "walking", "endLabel": "7 bikes", "route": ["…"] },
        { "step": 2, "type": "cycling", "endLabel": "10 docks", "route": ["…"] },
        { "step": 3, "type": "walking", "endLabel": "End", "route": ["…"] }
      ],
      "destination": null,
      "pricing": {
        "currency": "USD",
        "unlock_fee": 1.75,
        "per_min_rate": null,
        "per_min_interval": null,
        "per_km_rate": null,
        "per_km_interval": null,
        "description": "$1.75 every 30 minutes."
      },
      "rental_uris": {
        "android": null,
        "ios": null,
        "logo": "https://auth.cyclemate.club/storage/v1/object/public/logos/metro_bike.png"
      }
    }
  ],
  "destination_parking": null
}

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 42
}

Overview

Get routing options that integrate live bike-share availability. Returns multiple route alternatives:

Personal bike: direct cycling route
Docked bike-share: walk to station, cycle, then walk to the destination. Pickup and drop-off are always in the same system.
Docked e-bike: the same shape, from the nearest station with an e-bike available. Marked is_electric: true.
Dockless bike-share: walk to the bike, then cycle to the destination. One option per provider.

Behavior:

Alternatives more than 3× slower than the personal bike route are filtered out
Bike availability is fetched in real time from GBFS feeds and provider APIs
Assumed speeds: walking 5 km/h, cycling 15 km/h, e-bike 22 km/h
Maximum bike/station search radius: 1,500 m
Results are ordered Personal (SuperSafe first), then docked, docked e-bike, dockless

Authentication

This endpoint requires an API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

A valid user session is also accepted and grants higher rate limits.

Rate limits

Requests are rate-limited; authenticated requests are allowed a higher rate than anonymous ones. Multi-modal has a stricter limit than directions. On 429, honor the Retry-After header.

Performance

Typical response time: 800–1500 ms
Routing segments are computed in parallel

Request body

array

required

Starting point as [longitude, latitude]

array

required

Ending point as [longitude, latitude]

Optional parameters

boolean

When omitted (recommended), the response includes both supersafe=true and supersafe=false Personal variants, collapsed to one when they are identical, plus other option types once at supersafe=true. Clients can then toggle locally without refetching. When provided, every option type is computed under exactly that regime.

number

Identifier of a saved custom route. When it resolves to a route, that route is appended as a non-reroutable final cycling segment and its details are returned in each option’s event field.

number

Destination ID for enriched destination information in the response

string

Display name for the destination (used if destination_id not provided)

string

Display name for the origin waypoint

string

Planned departure as "YYYY-MM-DDTHH:mm" with no timezone offset, interpreted in the route city’s timezone. Determines night routing (see nighttime) and which temporary road avoidances apply; nearby active or imminent closures are surfaced per option as disruptions. Omit to route for now. Unparseable values return 400.

string

Navigate-to-parking mode: "ebike" (designated rental e-bike bays) or "regular" (cycle racks/stands). The Personal option becomes cycle-to-spot + walk-to-destination, ending at the nearest qualifying spot within 1,500 m of the destination; the spot is returned in parking. If none is found, or the destination borough does not mandate bays for "ebike", the option stays direct with parking: null. Use destination_parking to tell “park anywhere” from “no parking found”. Ignored when a custom route is attached. Other option types are unaffected.

string

Rental e-bike operator (London): "lime" or "forest". Restricts the "ebike" bay search to boroughs the operator serves; when the destination borough isn’t served, the route ends at the nearest bay inside the operator’s area and walks the rest (destination_parking.covered: false).

Response body

Returns an envelope { search_id, routes, destination_parking }.

string

Unique identifier (UUID) for this request. Include it in support enquiries.

object | null

The destination borough’s rental e-bike parking rule. Set only for parking_type: "ebike" requests whose destination falls inside a bounded area (a London borough); otherwise null.

{ "area_name": "Hackney", "ebike_parking_rule": "bay_mandatory" }

ebike_parking_rule: "bay_mandatory" (hires must end in a designated bay) or "free_floating" (park anywhere; render as “park anywhere in area_name”, not an error).
With an operator in the request, also carries operator and covered, indicating whether that operator serves the borough.

array

Array of route alternative objects

Show Route alternative

string

Route name (e.g., “My bike”, “Citi Bike”, “Lime”)

string

Personal, GBFS (station-based bike-share), TFL (Transport for London), or Dockless

boolean

true on the docked e-bike option. Absent otherwise.

boolean

Which SuperSafe regime the route was computed under: true = safety-biased routing, false = shorter/faster.

boolean

Whether this variant was routed on the night network preferring lit streets. Only set in cities with lighting data (London today); otherwise always false. At night, or on rides expected to finish after dark, the Personal option fans out night-first: "SuperSafe™ Night", "Direct · Night", and the standard "SuperSafe™" variant.

string | null

Display label for the route card. Set on Personal variants only: "SuperSafe™", "SuperSafe™ Night", "Direct", or "Direct · Night". null for bikeshare options, where the brand name from name should be displayed instead.

string | null

"Prefers well-lit roads" on night variants, otherwise null.

boolean

deprecated

Deprecated. Docked options only. false when the system publishes no live availability feed, in which case pills use generic pick-up and drop-off copy and clients should warn that availability is not live.

object | null

Pricing for the option’s bike-share system; null on Personal options and when no pricing data is available.

{
  "currency": "USD",
  "unlock_fee": 1.75,
  "per_min_rate": null,
  "per_min_interval": null,
  "per_km_rate": null,
  "per_km_interval": null,
  "description": "$1.75 every 30 minutes."
}

per_min_rate / per_km_rate apply per per_min_interval minutes / per_km_interval kilometres; each pair is null when the system doesn’t charge on that dimension.

object | null

{ android, ios, logo }: the provider’s rental deep links (each may be null) and a hosted logo image URL. null on Personal options.

object | null

Personal options with parking_type set only. The parking spot the route ends at:

{
  "id": 70424,
  "feature_id": "EBP.HCK.lime_dockless_location.98",
  "lat": 51.526292,
  "lon": -0.076975,
  "borough": "Hackney",
  "address": "Calvert Avenue",
  "capacity": 0,
  "ebike_parking": true,
  "distance_meters": 140.86
}

distance_meters is the straight-line distance to the requested destination; capacity is 0 when the source publishes none. null when no spot was returned (see parking_type).

array

Temporary road disruptions active at the departure time or starting within 60 minutes, within ~150 m of this option’s cycling legs. Absent when none apply. One entry per works site.

{
  "id": "street_manager:AB123456789-01",
  "source": "street_manager",
  "status": "active",
  "name": "Albert Bridge Road",
  "notes": "Road closed for street works, Thames Water (utility_repair)",
  "severity": "closed",
  "location": [-0.1663, 51.4776],
  "start_date": "2026-05-22",
  "start_minute": 1195,
  "end_date": "2026-07-29",
  "end_minute": 1260
}

id: stable pin key, identical across options.
source: "manual", "tfl", or "street_manager".
status: "active" (routing detoured around it) or "upcoming" (starts within 60 minutes; does not influence routing).
severity: "closed" or "avoid".
location: [lon, lat] centroid of the affected roads.
start_date, start_minute, end_date, end_minute: the city-local window (YYYY-MM-DD dates, wall-clock minutes of the day), start-inclusive and end-exclusive.

array

The option’s legs in travel order

Show Route step

number

Step number (1-indexed)

string

walking or cycling

object

Route object with geometry, distance, duration, and turn-by-turn instructions. Same shape as a Directions response.

boolean

false on custom-route segments

string

Display pill at the leg’s first coordinate (e.g. "Start route"), when a transition deserves a callout

string

Display pill at the leg’s last coordinate. Docked pickups/dropoffs show live counts ("5 bikes" / "3 e-bikes" / "5 docks"); dockless and personal transitions use "Pick up bike" / "Drop off bike"; a parking destination uses "Park bike"; the final leg ends with "End" unless a more specific label applies. Omitted when the next leg’s startLabel would sit at the same coordinate.

object

Custom route information (when event_id was provided)

object | null

Destination information (when destination_id or name was provided)

curl -X POST "https://api.cyclemate.club/multi-modal/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
  }'

const response = await fetch('https://api.cyclemate.club/multi-modal/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin: [-73.9851, 40.7589],
    destination: [-73.9712, 40.7614],
  }),
});

const { search_id, routes } = await response.json();
console.log(`Found ${routes.length} route alternatives (search_id=${search_id})`);

import requests

url = "https://api.cyclemate.club/multi-modal/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "origin": [-73.9851, 40.7589],
    "destination": [-73.9712, 40.7614]
}

response = requests.post(url, headers=headers, json=data)
routes = response.json()

The response example is captured from a real request. Long arrays in it are abridged with …. Each leg’s inner route object carries the same turn-by-turn shape as a Directions response.

{
  "search_id": "4df7451e-e393-4a8d-8402-7842772a380e",
  "routes": [
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": true,
      "nighttime": false,
      "label": "SuperSafe™",
      "subtitle": null,
      "route": [
        {
          "step": 1,
          "type": "cycling",
          "startLabel": "Start route",
          "endLabel": "End",
          "route": {
            "code": "Ok",
            "routes": [
              {
                "distance": 3241.5,
                "duration": 777.3,
                "weight": 1.4,
                "weight_name": "bicycle",
                "elevation_gain": 12,
                "elevation_loss": 8,
                "geometry": { "type": "LineString", "coordinates": ["…"] },
                "legs": ["…"]
              }
            ],
            "waypoints": [
              { "distance": 0, "name": "", "location": [-118.240115, 34.049835] },
              { "distance": 0, "name": "", "location": [-118.260088, 34.069913] }
            ],
            "uuid": null
          }
        }
      ],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "My bike",
      "type": "Personal",
      "supersafe": false,
      "nighttime": false,
      "label": "Direct",
      "subtitle": null,
      "route": ["…"],
      "destination": null,
      "pricing": null,
      "rental_uris": null
    },
    {
      "name": "Metro Bike Share",
      "type": "GBFS",
      "supersafe": true,
      "nighttime": false,
      "label": null,
      "subtitle": null,
      "has_live_availability": true,
      "route": [
        { "step": 1, "type": "walking", "endLabel": "7 bikes", "route": ["…"] },
        { "step": 2, "type": "cycling", "endLabel": "10 docks", "route": ["…"] },
        { "step": 3, "type": "walking", "endLabel": "End", "route": ["…"] }
      ],
      "destination": null,
      "pricing": {
        "currency": "USD",
        "unlock_fee": 1.75,
        "per_min_rate": null,
        "per_min_interval": null,
        "per_km_rate": null,
        "per_km_interval": null,
        "description": "$1.75 every 30 minutes."
      },
      "rental_uris": {
        "android": null,
        "ios": null,
        "logo": "https://auth.cyclemate.club/storage/v1/object/public/logos/metro_bike.png"
      }
    }
  ],
  "destination_parking": null
}

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 42
}

Variants

With SuperSafe routing and a custom route

JavaScript

const response = await fetch('https://api.cyclemate.club/multi-modal/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin: [-73.9851, 40.7589],
    destination: [-73.9712, 40.7614],
    supersafe: true,
    event_id: 123,
    destination_id: 45,
  }),
});

Route types

Personal bike

Direct cycling route, always first in results
With parking_type set: cycle to the returned parking spot, then walk to the destination

Walk → cycle station-to-station → walk
Included only when suitable stations exist within 1.5 km

Docked e-bike

Same shape, from the nearest station with an e-bike available; cycling legs use the e-bike speed
Marked is_electric: true; name is "{system name} E-bike"

Walk to the nearest available bike → cycle to destination, one option per provider
Included only when a bike exists within 1.5 km

Custom routes

When event_id resolves to a custom route:

All cycling segments route to the custom route’s starting point
A non-reroutable cycling step is appended for the custom route itself
Custom route details are included in each option’s event field
For docked bike-share, the final walking segment goes to the nearest station to the custom route’s endpoint

Step semantics

Each leg’s route.routes[0].legs[0].steps follows the same turn-by-turn shape as the directions endpoint:

step.distance is the length of the road after the maneuver. To render “in X metres, …”, use the previous step’s distance.
step.maneuver.location equals step.geometry.coordinates[0].
The final step of the final leg is always "Arrive at destination".
voiceInstructions and bannerInstructions are generated per leg independently, because every leg ends in its own arrive step.

Error responses

400 Bad request

{
  "error": "origin and destination must be [lon, lat] arrays"
}

Out-of-coverage routing carries a machine-readable code and the request’s search_id:

{
  "error": "Cross-city routing is not supported",
  "code": "CROSS_CITY_ROUTE",
  "search_id": "9b2f2f9e-1d0a-4f4e-9d2e-7c8a53f6f210"
}

401 Unauthorized

{
  "error": "Missing Authorization header"
}

429 Too many requests

Includes a Retry-After header with the seconds until the current window closes:

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 42
}

500 Internal server error

{
  "error": "Error message"
}

Getting started

Routing

Contributions

Get multiple directions

Overview

Authentication

Rate limits

Performance

Request body

Response body

Variants

With SuperSafe routing and a custom route

Route types

Personal bike

Docked e-bike

Custom routes

Step semantics

Error responses

400 Bad request

401 Unauthorized

429 Too many requests

500 Internal server error

​Overview

​Authentication

​Rate limits

​Performance

​Request body

​Response body

​Variants

​With SuperSafe routing and a custom route

​Route types

​Personal bike

​Docked bike-share (GBFS/TFL)

​Docked e-bike

​Dockless bike-share

​Custom routes

​Step semantics

​Error responses

​400 Bad request

​401 Unauthorized

​429 Too many requests

​500 Internal server error

Overview

Authentication

Rate limits

Performance

Request body

Response body

Variants

With SuperSafe routing and a custom route

Route types

Personal bike

Docked bike-share (GBFS/TFL)

Docked e-bike

Dockless bike-share

Custom routes

Step semantics

Error responses

400 Bad request

401 Unauthorized

429 Too many requests

500 Internal server error