> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyclemate.club/llms.txt
> Use this file to discover all available pages before exploring further.

# Cyclemate Bike Routing API

> Safe turn-by-turn cycling directions and multi-modal bike-share routing for developers — authentication, rate limits, and response format.

## Welcome to Cyclemate API

Cyclemate provides **2 public APIs** for bike routing. These APIs are designed to help developers build cycling-focused applications with rich routing capabilities and bike-share integration.

## Authentication

**An API key is required.** All API requests must include your key as a bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Getting an API key

API access is granted per application — signing up for a Cyclemate account on its own doesn't provision a key for third-party use.

**For third-party developers:**

1. [Contact our team](https://cyclemate.club/for-developers) to request API access
2. We'll issue you an API key
3. Include the key in the `Authorization` header on every request

### Example request

```bash theme={null}
curl -X POST https://api.cyclemate.com/directions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": [-73.9851, 40.7589], "destination": [-73.9712, 40.7614]}'
```

## Rate Limiting

Requests are rate-limited to keep the service fast and fair for everyone. Authenticated requests are allowed a higher rate than anonymous ones. If you need higher limits for your application, [contact us](https://cyclemate.club/for-developers).

Each response includes an `X-RateLimit-Remaining` header so you can track your remaining budget for the current window.

### Exceeding Rate Limits

If you exceed your rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "details": "Too many requests. 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
* Batch requests when feasible
* [Contact us](https://cyclemate.club/for-developers) if you need higher rate limits for your application

## Public APIs

<CardGroup cols={2}>
  <Card title="Directions" icon="route" href="/api-reference/routing/directions">
    Turn-by-turn directions with super-safe bike routing
  </Card>

  <Card title="Multi-Modal Routing" icon="route" href="/api-reference/routing/multimodal">
    Multi-modal routing with bike-share integration
  </Card>
</CardGroup>

## Response Format

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

**Success Response:**

```json theme={null}
{
  "data": {},
  "metadata": {}
}
```

**Error Response:**

```json theme={null}
{
  "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/`  | POST   | Turn-by-turn directions        | ✅ Yes (API key) |
| `/multi-modal/` | POST   | Multi-modal bike-share routing | ✅ Yes (API key) |

## Support

For questions, issues, or feature requests, please [contact our team](https://cyclemate.club/for-developers).