Bike Navigation SDK

Bike Navigation/Directions SDK

Welcome to Cyclemate API

Cyclemate provides 4 public APIs for bike routing, event discovery, and bike-share availability. These APIs are designed to help developers build cycling-focused applications with rich routing capabilities and real-time bike availability data.

Authentication

Auth0 authentication required. All API requests must include a valid Auth0 bearer token in the Authorization header:

Authorization: Bearer YOUR_AUTH0_ACCESS_TOKEN

Getting an Auth0 Token

To integrate the Cyclemate API into your application, you’ll need API credentials and Auth0 application setup. Simply signing up for a Cyclemate account won’t provide the necessary authentication for third-party applications.

For third-party developers:

1. Contact our team to request API access
2. We’ll provide you with Auth0 application credentials (Client ID and Client Secret)
3. Implement Auth0 authentication in your application
4. Include the Auth0 access token in the Authorization header for all API requests

Token Format

curl https://api.cyclemate.com/events/nearby/?latitude=40.7589&longitude=-73.9851 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Rate Limiting

To ensure fair usage and maintain service quality for all users, we offer the following rate limit plans:

Plan	Requests per Minute	Requests per Hour	Requests per Day	Pricing
Free	10	100	1,000	Free
Enterprise	Custom	Custom	Custom	Contact us

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1699920000

• X-RateLimit-Limit: Maximum requests allowed per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets

Exceeding Rate Limits

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "details": "You have exceeded the maximum number of requests per minute. Please try again later.",
  "retry_after": 45
}

The retry_after field indicates how many seconds to wait before making another request.

Best Practices

• Cache responses when possible to reduce API calls
• Implement exponential backoff when receiving 429 responses
• Monitor rate limit headers to avoid hitting limits
• Batch requests when feasible
• Contact us if you need higher rate limits for your application

Public APIs

Nearby Events

Find nearby cycling events and leisure routes

Nearby Bikes

Real-time bike-share availability (docked and dockless)

Directions

Turn-by-turn directions with super-safe bike routing

Multi-Modal Routing

Multi-modal routing with bike-share integration

Response Format

All API endpoints return JSON responses with the following general structure:

Success Response:

{
  "data": {},
  "metadata": {}
}

Error Response:

{
  "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
/events/nearby/	GET	Find nearby events and leisure routes	✅ Yes (Auth0)
/bikes/nearby/	GET	Real-time bike-share availability	✅ Yes (Auth0)
/directions/	POST	Turn-by-turn directions	✅ Yes (Auth0)
/multi-modal/	POST	Multi-modal bike-share routing	✅ Yes (Auth0)

Support

For questions, issues, or feature requests, please contact our team.