Skip to main content
POST
/
directions
Get Directions
curl --request POST \
  --url https://api.example.com/directions/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "coordinates": [
    {}
  ],
  "profile": "<string>",
  "supersafe": true,
  "options": {
    "geometries": "<string>",
    "overview": "<string>",
    "steps": true,
    "alternatives": true
  }
}
'
{
  "400": {},
  "503": {},
  "routes": [
    {
      "distance": 123,
      "duration": 123,
      "geometry": {},
      "legs": [
        {
          "distance": 123,
          "duration": 123,
          "steps": [
            {
              "distance": 123,
              "duration": 123,
              "name": "<string>",
              "maneuver": {},
              "geometry": {}
            }
          ]
        }
      ]
    }
  ],
  "waypoints": [
    {}
  ],
  "code": "<string>",
  "metadata": {
    "routing_engine": "<string>",
    "profile": "<string>",
    "waypoint_count": 123
  }
}

​
Overview

Get directions between waypoints with support for cycling, walking, and driving profiles. Optionally use the supersafe flag for bike routing on a dedicated cycling network with safety prioritization.

​
Authentication

This endpoint requires Auth0 authentication. Include your access token in the Authorization header: 
Authorization: Bearer YOUR_AUTH0_ACCESS_TOKEN

​
Request Body

​
coordinates
array
required
Array of [longitude, latitude] waypoints. Minimum 2, maximum 25.Example: [[lon1, lat1], [lon2, lat2]]
​
profile
string
default:"cycling"
Routing profile. Options:
  • cycling - Optimized for bicycles
  • walking - Optimized for pedestrians
  • driving - Optimized for cars
  • driving-traffic - Driving with traffic data
​
supersafe
boolean
default:"false"
Enable super-safe bike routing using Cyclemate’s network router. Only applies to cycling profile.When enabled, routes prioritize:
  • Protected bike lanes
  • Low-traffic streets
  • Bike paths and greenways
  • Reduced elevation gain
​
options
object
Additional routing options (passed to Mapbox when not using supersafe)

​
Response

​
routes
array
Array of route objects
​
waypoints
array
Snapped waypoint locations
​
code
string
Response code: Ok on success
​
metadata
object
Routing metadata
​
routing_engine
string
mapbox or network_router (when supersafe is enabled)
​
profile
string
Routing profile used
​
waypoint_count
number
Number of waypoints

​
Request Example

​
Standard Cycling Route

cURL
curl -X POST "https://api.cyclemate.com/directions/" \
  -H "Authorization: Bearer YOUR_AUTH0_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [[-73.9851, 40.7589], [-73.9712, 40.7614]],
    "profile": "cycling",
    "options": {
      "steps": true,
      "overview": "full"
    }
  }'
JavaScript
const response = await fetch('https://api.cyclemate.com/directions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_AUTH0_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    coordinates: [[-73.9851, 40.7589], [-73.9712, 40.7614]],
    profile: 'cycling',
  }),
});

const directions = await response.json();
console.log(`Route distance: ${directions.routes[0].distance}m`);

​
Super-Safe Bike Route

JavaScript
const response = await fetch('https://api.cyclemate.com/directions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_AUTH0_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    coordinates: [[-73.9851, 40.7589], [-73.9712, 40.7614]],
    profile: 'cycling',
    supersafe: true,
  }),
});

const directions = await response.json();
console.log(`Super-safe route: ${directions.routes[0].distance}m`);
Python
import requests

url = "https://api.cyclemate.com/directions/"
headers = {
    "Authorization": "Bearer YOUR_AUTH0_ACCESS_TOKEN"
}
data = {
    "coordinates": [[-73.9851, 40.7589], [-73.9712, 40.7614]],
    "profile": "cycling",
    "supersafe": True
}

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

​
Response Example

{
  "routes": [
    {
      "distance": 1523.4,
      "duration": 365.2,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-73.9851, 40.7589],
          [-73.9845, 40.7595],
          [-73.9712, 40.7614]
        ]
      },
      "legs": [
        {
          "distance": 1523.4,
          "duration": 365.2,
          "steps": [
            {
              "distance": 150.2,
              "duration": 36.0,
              "name": "West 52nd Street",
              "maneuver": {
                "type": "depart",
                "instruction": "Head east on West 52nd Street",
                "bearing_before": 0,
                "bearing_after": 90,
                "location": [-73.9851, 40.7589]
              },
              "geometry": {
                "type": "LineString",
                "coordinates": [
                  [-73.9851, 40.7589],
                  [-73.9845, 40.7589]
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "waypoints": [
    {
      "location": [-73.9851, 40.7589],
      "name": "West 52nd Street"
    },
    {
      "location": [-73.9712, 40.7614],
      "name": "Central Park West"
    }
  ],
  "code": "Ok",
  "metadata": {
    "routing_engine": "network_router",
    "profile": "cycling",
    "waypoint_count": 2
  }
}

​
Super-Safe Routing

When supersafe: true is enabled for cycling routes, the API uses Cyclemate’s proprietary network router that:
  1. Prioritizes Safety: Routes prefer protected bike lanes, bike paths, and low-traffic streets
  2. Local Knowledge: Uses city-specific bike infrastructure data (NYC, LA, SF, Chicago, London)
  3. Elevation Aware: Minimizes elevation gain when possible
  4. Real-time Updates: Incorporates user feedback and recent infrastructure changes

​
Error Responses

​
400
object
Invalid request
{
  "error": "At least 2 coordinates are required"
}
​
400
object
Invalid profile
{
  "error": "Invalid profile. Must be one of: cycling, walking, driving, driving-traffic"
}
​
503
object
Service unavailable
{
  "error": "Mapbox service temporarily unavailable",
  "details": "Request timed out"
}

​
Notes

  • Coordinates must be in [longitude, latitude] format
  • Maximum 25 waypoints per request
  • Super-safe routing is only available in supported cities (NYC, LA, SF Bay Area, Chicago, London)
  • Duration estimates assume average cycling speed of 15 km/h (9.3 mph)
  • Turn-by-turn instructions are in English