Safe Bike Directions API

Get turn-by-turn directions with optional super-safe bike routing

POST /directions/

Safe Bike Directions API

cURL

curl --request POST \
  --url https://api.example.com/directions/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "coordinates": [
    {}
  ],
  "profile": "<string>",
  "supersafe": true,
  "bearing": 123,
  "departure_time": "<string>",
  "options": {
    "geometries": "<string>",
    "overview": "<string>",
    "steps": true,
    "alternatives": true
  }
}
'

200

{
  "400": {},
  "429": {},
  "503": {},
  "routes": [
    {
      "distance": 123,
      "duration": 123,
      "geometry": {},
      "legs": [
        {
          "distance": 123,
          "duration": 123,
          "steps": [
            {
              "distance": 123,
              "duration": 123,
              "name": "<string>",
              "maneuver": {},
              "exits": "<string>",
              "geometry": {},
              "lit": true,
              "voiceInstructions": [
                {}
              ],
              "bannerInstructions": [
                {}
              ]
            }
          ]
        }
      ]
    }
  ],
  "waypoints": [
    {}
  ],
  "code": "<string>",
  "search_id": {},
  "edge_ids": {},
  "graph_version": {},
  "subtitle": {},
  "disruptions": [
    {}
  ],
  "metadata": {
    "routing_engine": "<string>",
    "profile": "<string>",
    "waypoint_count": 123,
    "nighttime": true
  }
}

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 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 — see Rate Limits.

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

bearing · number

Optional constraint on the direction of travel as the route leaves the start point, in degrees [0, 360) (0 = north, 90 = east). Primarily useful for mid-ride reroutes: pass the user’s current heading so the new route doesn’t begin with a near-U-turn.

All road segments within ~80m of the start point whose direction of travel is outside the server-configured tolerance (default ±45°) of bearing are treated as non-traversable in that direction only. Bidirectional roads with a legal direction remain traversable on their matching side. One-way roads are naturally dropped if their only legal direction is out of range.

If the constraint leaves no traversable path out of the start bubble, the request returns NoRoute — in that case the client should retry without bearing. Fractional degrees are accepted and rounded to the nearest integer server-side. Cycling profile only.

Example: 90 (traveling east).

departure_time · string

Optional wall-clock departure time the rider plans to leave, as "YYYY-MM-DDTHH:mm" with no timezone offset (e.g. "2026-06-03T21:00"). The server interprets it in the route city’s timezone to decide day/night routing — when the picked time lands in the dark window (30 minutes after sunset to 30 minutes before sunrise) and the city has street-lighting data (London today), cycling routes use the lit-street-preferring nighttime costs (see metadata.nighttime). Omit to time the route to now. An unparseable value returns 400. Affects cycling only; walking ignores it, and cities without lighting data never go nighttime.

The departure time also drives time-based avoidances: operators can mark a road as avoided on a recurring weekly window (e.g. a Saturday street market or a school street at drop-off) or a one-time date range (e.g. a festival closure from 15 Jan 2027 09:00 to 16:00 — one-time windows may span multiple days and cross midnight). When the departure falls inside such a window, cycling routes — both SuperSafe and Direct — route around the road; outside the window (or once a one-time window has passed) the road routes normally. Walking is unaffected, and these windows never change the map’s safety coloring (routing-time only).

Example: "2026-06-03T21:00" (9 PM local at the route).

options · object

Additional routing options (applied when not using supersafe)

Show Options Object

geometries · string · default: "geojson"

Format of returned geometry: geojson or polyline

overview · string · default: "full"

Level of detail: full, simplified, or false

steps · boolean · default: "true"

Include turn-by-turn instructions

alternatives · boolean · default: "false"

Return alternative routes

Response

routes · array

Array of route objects

Show Route Object

distance · number

Total route distance in meters

duration · number

Estimated travel time in seconds

geometry · object

Route geometry as GeoJSON LineString

legs · array

Array of leg objects (one per waypoint pair)

Show Leg Object

distance · number

Leg distance in meters

duration · number

Leg duration in seconds

steps · array

Turn-by-turn instructions

Show Step Object

distance · number

Length of the road travelled after this step’s maneuver, in metres — i.e. the length of geometry.coordinates, the road you end up on once the turn is complete (not the road leading into it).

Consequence for UIs: to show “in X metres, ”, use the previous step’s distance (the road you’re on until this turn), not this step’s own. Using the step’s own distance shows the length of the road you end up on after the turn, which is almost always wrong.

duration · number

Step duration in seconds, derived from distance at the profile’s target speed (cycling 15 km/h, walking 5 km/h).

name · string

Street name after the maneuver (i.e. the name of the road whose length is distance).

maneuver · object

Turn instruction.

• type: "Start", "Turn", "Continue", "roundabout", "U-turn", or end-sentinel for the last step.
• modifier: "left", "right", "straight", "sharp left", etc. On a "roundabout" step it’s the exit direction (approach heading vs exit heading), so the arrow points roughly the way the rider leaves.
• instruction: pre-rendered string, e.g. "Turn left on East 1st Street". A roundabout reads "At the roundabout, take the third exit" (the road taken is named by the following step). The final step is always "Arrive at destination".
• location: [lon, lat] where the maneuver happens — equal to geometry.coordinates[0].
• bearing_before: inbound heading approaching the maneuver, in degrees — the heading at the end of the previous step’s geometry. On a curved approach this differs from the previous step’s bearing_after; do not assume they are equal.
• bearing_after: outbound heading leaving the maneuver, in degrees — the heading at the start of this step’s geometry.

exits · string

For a "roundabout" maneuver, the exit to take as a 1-based number string (e.g. "3" for the third exit) — equal to the number of roundabout edges the route traverses, since the circular way is split at each connecting road. Empty string ("") on every non-roundabout step.

geometry · object

Step geometry as GeoJSON LineString. coordinates[0] is the maneuver location; the total geodesic length equals distance (within ~2%). A roundabout step’s geometry is the whole arc travelled around the circle.

lit · boolean

Whether this step’s road is lit, from OpenStreetMap lighting (ways.lit — TRUE only when the way has explicit lit=yes-style tagging). Like cycle_routes, a multi-edge step reflects its first edge. Present on cycling steps; clients use it to highlight the lit portions of a route and compute a ”% Lit” figure. Coverage is approximate (London only today).

voiceInstructions · array

Mapbox-style spoken cues for this step’s maneuver, ordered far → near. Each entry:

• distanceAlongGeometry: distance remaining to the maneuver, in metres, at which to speak the cue. Values decrease through the array (the largest fires first/earliest); each is ≤ the approach length (the previous step’s distance). The smallest is an imminent “act now” cue at ~40 m (~7 s of lead at cycling speed). The largest is an entry heads-up placed ~25 m into the approach (approach − 25), so the next turn is only announced once the rider has cleared the junction they just turned through. Long steps get several cues (e.g. a 1-mile approach → ~1575 m / 1000 m / 400 m / 120 m / 40 m); short steps get one.
• announcement: the spoken text — the maneuver instruction, unit-agnostic (no distance baked in). The client prepends a localized "In <distance>, …" prefix for the non-imminent cues per the rider’s imperial/metric setting. A merged compound step’s announcement already reads "Turn left, then turn right on B", so stacked audio needs no extra assembly.

The arrive step carries no voice cues (the client owns the final “You have arrived”).

bannerInstructions · array

Mapbox-style visual banner for this step (one entry today).

• distanceAlongGeometry: the approach length over which the banner applies.
• primary: the maneuver to display — { text, components: [{ text, type }], type, modifier }. components splits the text into "text" and "road-name" fragments. For a merged compound step, primary is the first turn (so the big arrow is the first turn, not the combined text).
• sub (optional): the stacked “then” preview — the maneuver that follows quickly after this one (same shape as primary, with modifier). Present only on merged compound (“X, then Y”) steps; drives the Google-Maps-style “Then ↰ <road>” sub-row. Absent on ordinary steps.

waypoints · array

Snapped waypoint locations

code · string

Response code: Ok on success

search_id · number | null

Identifier of the analytics row written for this request (helloapp_route_search.id). Pass this back when persisting a route to helloapp_routehistory.route_search_id so the search → ride funnel can be computed. May be null if the server failed to persist the analytics row; in that case the route is still valid — analytics writes are best-effort.

edge_ids · number[] | null

Ordered list of the internal graph edge ids (ways.id) this route traverses, in travel order. Cycling responses populate it; walking responses leave it null. The event editor concatenates edge_ids across a multi-stop route’s segments and persists them on the event (helloapp_event.edges_router_ids) so event-edge generation rebuilds the route’s edges with a cheap id lookup instead of re-snapping the polyline. Opaque to API consumers — only meaningful together with graph_version.

graph_version · string | null

The graph version (ways.version) that edge_ids belong to. Stamped alongside the ids so they can be detected as stale after a graph rebuild reassigns edge ids. null on walking responses.

subtitle · string | null

"Prefers well-lit roads" when the route was computed on the nighttime cost network (a cycling request that landed in the dark window — see metadata.nighttime), null otherwise. Walking routes never set this.

disruptions · array

Temporary road disruptions — one-time graph_time_overrides windows (manual curator entries plus the TfL Road Disruptions and DfT Street Manager roadworks feeds) — that are active at the departure time or open within the next 60 minutes, and whose pin lies within ~150 m of this route’s cycling geometry. Absent (not empty) when none are nearby, and never present on walking responses. One entry per works site, pinned at the centroid of the affected ways.

Entries have the exact same shape and semantics as the per-option disruptions field on /multi-modal/ — see Multi-Modal Routing for the field-by-field reference (id, source, status, severity, location, and the city-local window fields). status: "upcoming" windows do not influence routing, so an upcoming pin can sit directly on the route.

metadata · object

Routing metadata

routing_engine · string

Identifier of the routing engine that produced the route. Always network_router.

profile · string

Routing profile used

waypoint_count · number

Number of waypoints

nighttime · boolean

Whether the route was computed on the nighttime cost network, which prefers lit streets (streets with no OpenStreetMap lighting data, or tagged unlit, are penalised). Set for cycling requests in a city that has street-lighting data (London today) that land in the dark window — from 30 minutes after sunset until 30 minutes before sunrise at the route origin (the city’s local night, derived from the origin coordinates). Always false for walking, and always false in cities without lighting data (their nighttime costs equal the base cost, so there’s no lit-road preference to surface).

Request Example

Standard Cycling Route

cURL

curl -X POST "https://api.cyclemate.com/directions/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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_API_KEY',
    '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`);

Reroute With Current Heading

Use bearings when recomputing a route mid-ride so the new route leaves the user’s location in their current direction of travel rather than asking them to U-turn:

JavaScript

const response = await fetch('https://api.cyclemate.com/directions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    coordinates: [currentLocation, destination],
    profile: 'cycling',
    supersafe: true,
    bearing: currentHeadingDegrees,
  }),
});

Super-Safe Bike Route

JavaScript

const response = await fetch('https://api.cyclemate.com/directions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    '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_API_KEY"
}
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",
  "search_id": 1234,
  "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"
}

400 · object

Cross-city or out-of-coverage routing. Includes search_id so the failed search can still be joined back to a future ride from a different attempt (the analytics row is written with status='cross_route_not_supported').

{
  "error": "Cross-city routing is not supported",
  "code": "CROSS_CITY_ROUTE",
  "search_id": 1235
}

429 · object

Rate limit exceeded. Includes a Retry-After response header with the number of seconds until the current window closes.

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

503 · object

Service unavailable

{
  "error": "Routing service temporarily unavailable",
  "details": "Request timed out"
}

Rate Limits

Requests are rate-limited. Authenticated requests (valid user session) are allowed a higher rate than anonymous requests.

When the limit is exceeded, the response is 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait before retrying, and a matching retry_after_seconds field in the body. Clients should honor Retry-After.

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