> ## 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 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

There are two ways to authenticate, and every endpoint says which it accepts.

**An API key**, for your own server calling the API as itself. Send it in the `apikey` header:

```bash theme={null}
apikey: YOUR_API_KEY
```

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

**Login with Cyclemate**, for an app acting on behalf of a signed-in rider. The rider approves your app once and you send their access token as a bearer token:

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

Requests then count against the rider's own rate limit and are attributed to your app. The flow, the button and the token endpoints are on the [Login with Cyclemate](https://docs.cyclemate.club/api-reference/oauth.md) page.

### 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](https://cyclemate.club/for-developers) to request API access
2. We issue an API key for your application
3. Include the key in the `apikey` header on every request

To act for riders instead, [register your app for Login with Cyclemate](https://docs.cyclemate.club/api-reference/oauth.md#register-your-app).

### Example request

```bash theme={null}
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](https://cyclemate.club/for-developers).

### 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:

```json theme={null}
{
  "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](https://cyclemate.club/for-developers) if you need higher rate limits for your application

## Available APIs

> [card] [Routing](https://docs.cyclemate.club/api-reference/routing/overview.md)
>
> How SuperSafe routing works, and which endpoint to reach for

> [card] [Directions](https://docs.cyclemate.club/api-reference/routing/directions.md)
>
> Turn-by-turn directions with safety-first bike routing

> [card] [Multi-Modal Routing](https://docs.cyclemate.club/api-reference/routing/multimodal.md)
>
> Multi-modal routing with bike-share integration

> [card] [Explain SuperSafe](https://docs.cyclemate.club/api-reference/routing/explain-supersafe.md)
>
> One sentence explaining why a SuperSafe route differs from the direct route

> [card] [Custom routes](https://docs.cyclemate.club/api-reference/custom-routes/overview.md)
>
> Create, edit and share custom routes and group rides, with images

> [card] [Contributions](https://docs.cyclemate.club/api-reference/reports/overview.md)
>
> 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`.

```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/v2/` | POST | Turn-by-turn directions | API key or Login with Cyclemate |
| `/multi-modal/v2/` | POST | Multi-modal bike-share routing | API key or Login with Cyclemate |
| `/explain-supersafe/` | POST | One-sentence explanation of a SuperSafe route | API key or Login with Cyclemate |
| `/reports/` | POST | Submit a road or infrastructure report | API key or Login with Cyclemate |
| `/reports/{id}/` | GET | Processing status + outcome summary of a report | API key or Login with Cyclemate |
| `/custom-routes/` | GET, POST | Your custom routes; create one | Login with Cyclemate |
| `/custom-routes/{id}/` | GET, PATCH, DELETE | Read, edit or delete a custom route | Login with Cyclemate |
| `/custom-routes/{id}/images/` | POST | Add an image to a custom route | Login with Cyclemate |
| `/custom-routes/{id}/images/{image_id}/` | DELETE | Remove an image | Login with Cyclemate |

## Support

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.