Cyclemate for Developers

Cyclemate platform gives developers access to Cyclemate safe cycling route planner, as well as the ability to contribute directly to the algorithm.

Welcome

Cyclemate for Developers offers access to the Cyclemate safe cycling route planner, as well as the ability to contribute directly to the algorithm.

Authentication

An API key is required. All API requests must send your key in the apikey header:

apikey: YOUR_API_KEY

The key goes in apikey, not Authorization. A key sent as a bearer token is rejected with a 401.

Getting an API key

API access is granted per application. Signing up for a Cyclemate account on its own does not provision a key for third-party use.

For third-party developers:

1. Contact us to request API access
2. We issue an API key for your application
3. Include the key in the apikey header on every request

Example request

curl -X POST https://api.cyclemate.club/directions/v2/ \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"coordinates": [[-73.9851, 40.7589], [-73.9712, 40.7614]], "profile": "cycling"}'

Rate limiting

Requests are rate-limited to prevent abuse. If your application needs higher limits, contact us.

Exceeding rate limits

If you exceed your rate limit, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating the number of seconds until the current window closes, and a matching field in the body:

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

The retry_after_seconds field indicates how many seconds to wait before making another request. Clients should honor Retry-After.

Best practices

• Cache responses when possible to reduce API calls
• Implement exponential backoff when receiving 429 responses
• Contact us if you need higher rate limits for your application

Available APIs

Routing

How SuperSafe routing works, and which endpoint to reach for

Directions

Turn-by-turn directions with safety-first bike routing

Multi-Modal Routing

Multi-modal routing with bike-share integration

Explain SuperSafe

One sentence explaining why a SuperSafe route differs from the direct route

Contributions

Send reports and data feeds that feed the routing algorithm and safe cycling maps

Response format

All endpoints return JSON. Each endpoint documents its own success response shape on its reference page.

Errors follow a consistent envelope: an error message, plus an optional details field with additional context and, where applicable, a machine-readable code.

{
  "error": "Error message",
  "details": "Additional error details"
}

Coordinate format

All coordinates in the API use the standard [longitude, latitude] format (GeoJSON standard), unless otherwise specified.

• Longitude: -180 to 180 (East-West position)
• Latitude: -90 to 90 (North-South position)

API overview

Endpoint	Method	Description	Auth Required
/directions/v2/	POST	Turn-by-turn directions	✅ Yes (API key)
/multi-modal/v2/	POST	Multi-modal bike-share routing	✅ Yes (API key)
/explain-supersafe/	POST	One-sentence explanation of a SuperSafe route	✅ Yes (API key)
/reports/	POST	Submit a road or infrastructure report	✅ Yes (API key)
/reports/{id}/	GET	Processing status + outcome summary of a report	✅ Yes (API key)

Support

For questions, issues, or feature requests, please contact us.