Overview
Get comprehensive routing options that integrate bike-share availability. Returns multiple route alternatives including:
- Personal Bike: Direct cycling route
- Docked Bike-Share: Walk to station → cycle → walk to destination
- Dockless Bike-Share: Walk to bike → cycle to destination (per provider)
Authentication
This endpoint requires Auth0 authentication. Include your access token in the Authorization header:
Authorization: Bearer YOUR_AUTH0_ACCESS_TOKEN
Request Body
Starting point as [longitude, latitude]
Ending point as [longitude, latitude]
Enable super-safe bike routing for cycling segments
Optional event ID. If provided and event has a route, includes event route as final cycling segment.
Optional destination ID for enriched destination information in response
Optional name for the destination (used if destination_id not provided)
Response
Returns an array of route alternatives, each containing a sequence of steps:
Array of route alternative objects
Route name (e.g., “My bike”, “Citi Bike”, “Lime”)
Route type:
Personal - Using your own bikeGBFS - Station-based bike-share (e.g., Citi Bike)TFL - Transport for London bike-shareDockless - Free-floating bike-share (e.g., Lime, Spin)
Array of route step objects
Step type: walking or cycling
Mapbox-compatible route object with geometry, distance, duration, and turn-by-turn instructions
Whether this step can be rerouted (false for event routes)
Event information (if event_id was provided)
Destination information (if destination_id or name was provided)
Request Example
Basic Multi-modal Route
curl -X POST "https://api.cyclemate.com/multi-modal/" \
-H "Authorization: Bearer YOUR_AUTH0_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"origin": [-73.9851, 40.7589],
"destination": [-73.9712, 40.7614]
}'
const response = await fetch('https://api.cyclemate.com/multi-modal/', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_AUTH0_ACCESS_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
origin: [-73.9851, 40.7589],
destination: [-73.9712, 40.7614],
}),
});
const routes = await response.json();
console.log(`Found ${routes.length} route alternatives`);
With Super-Safe Routing and Event
const response = await fetch('https://api.cyclemate.com/multi-modal/', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_AUTH0_ACCESS_TOKEN',
'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,
}),
});
const routes = await response.json();
import requests
url = "https://api.cyclemate.com/multi-modal/"
headers = {
"Authorization": "Bearer YOUR_AUTH0_ACCESS_TOKEN"
}
data = {
"origin": [-73.9851, 40.7589],
"destination": [-73.9712, 40.7614],
"supersafe": True,
"event_id": 123
}
response = requests.post(url, headers=headers, json=data)
routes = response.json()
Response Example
[
{
"name": "My bike",
"type": "Personal",
"route": [
{
"step": 1,
"type": "cycling",
"route": {
"routes": [{
"distance": 1523.4,
"duration": 365.2,
"geometry": {
"type": "LineString",
"coordinates": [[-73.9851, 40.7589], [-73.9712, 40.7614]]
},
"legs": [...]
}],
"waypoints": [...],
"code": "Ok"
}
}
],
"destination": {
"name": "Central Park",
"latitude": 40.7614,
"longitude": -73.9712
}
},
{
"name": "Citi Bike",
"type": "GBFS",
"route": [
{
"step": 1,
"type": "walking",
"route": {
"routes": [{
"distance": 245.8,
"duration": 180.0,
"geometry": {...}
}]
}
},
{
"step": 2,
"type": "cycling",
"route": {
"routes": [{
"distance": 1200.5,
"duration": 288.0,
"geometry": {...}
}]
}
},
{
"step": 3,
"type": "walking",
"route": {
"routes": [{
"distance": 150.2,
"duration": 110.0,
"geometry": {...}
}]
}
}
],
"destination": {
"name": "Central Park",
"latitude": 40.7614,
"longitude": -73.9712
}
},
{
"name": "Lime",
"type": "Dockless",
"route": [
{
"step": 1,
"type": "walking",
"route": {...}
},
{
"step": 2,
"type": "cycling",
"route": {...}
}
],
"destination": {
"name": "Central Park",
"latitude": 40.7614,
"longitude": -73.9712
}
}
]
Route Types Explained
Personal Bike Route
- Direct cycling route from origin to destination
- No walking segments unless event route is involved
- Always appears first in results
Docked Bike-Share Route (GBFS/TFL)
- Step 1: Walk from origin to nearest station with bikes available
- Step 2: Cycle from origin station to destination station
- Step 3: Walk from destination station to final destination
- Only included if suitable stations are found within 1.5km
Dockless Bike-Share Route
- Step 1: Walk from origin to nearest available bike
- Step 2: Cycle from bike location to destination
- One route per provider (Lime, Spin, etc.)
- Only included if bikes are found within 1.5km
Event Integration
When event_id is provided and the event has a defined route:
- All cycling segments route to the event’s starting point
- An additional non-reroutable cycling step is added for the event route
- Event details are included in each route alternative
- Final walking segment (for docked bike-share) goes to nearest station to event endpoint
Notes
- Routes are automatically filtered to remove alternatives >3x slower than the personal bike route
- Bike availability is fetched in real-time from GBFS feeds and provider APIs
- Distance calculations use the Haversine formula
- Walking speed assumed: 1.4 m/s (5 km/h)
- Cycling speed assumed: 4.17 m/s (15 km/h)
- Maximum bike search radius: 1500 meters
- Results are ordered: Personal, Docked bike-share, Dockless bike-share
Error Responses
Invalid coordinates{
"error": "origin and destination must be [lon, lat] arrays"
}
No viable routes found{
"error": "No viable bike-share route found"
}
Server error{
"error": "Error message",
"details": "Additional details"
}
- Typical response time: 800-1500ms
- Bike availability queries: ~100-200ms
- Routing segments computed in parallel
- Results cached when possible
