# Tailwind KOMpass API for developers

## Overview

The Tailwind KOMpass Public API is a free, keyless, read-only JSON API. It exposes the signed-tailwind formula Tailwind KOMpass uses to rank Strava segments, a bearing helper, and the current Free and Pro plan facts. It is meant for AI agents, scripts and apps that need to answer “how much does this wind help on this road?” with the same numbers the app shows.

Base URL: `https://api.tailwindkompass.com/functions/v1/public-api`
OpenAPI 3.1 description: [https://tailwindkompass.com/openapi.json](https://tailwindkompass.com/openapi.json) (version 1.1.0)

## Endpoints

- `GET /v1/tailwind` · `calculateTailwind`: Signed tailwind along a segment.
- `GET /v1/bearing` · `calculateBearing`: Initial bearing between two points.
- `GET /v1/plans` · `listPlans`: Free and Pro plan facts.
- `GET /health` · `getHealth`: Service health.
- `GET /openapi.json` · `getOpenApiSpec`: This OpenAPI document.

## Calculate tailwind on a segment

Pass the wind speed (km/h), the direction the wind comes from (degrees), and either the segment’s bearing or its start and end coordinates. Positive results are tailwind, negative results are headwind.

```
curl "https://api.tailwindkompass.com/functions/v1/public-api/v1/tailwind?wind_speed_kmh=20&wind_direction_deg=250&segment_bearing_deg=80"
```

```
{
  "signed_tailwind_kmh": 19.7,
  "crosswind_kmh": 3.5,
  "effect": "tailwind",
  "segment_bearing_deg": 80,
  "wind_speed_kmh": 20,
  "wind_direction_deg": 250,
  "formula": "signed = wind_speed_kmh * cos((wind_direction_deg + 180) - segment_bearing_deg)"
}
```

## Get a segment bearing

Returns the initial great-circle bearing from a start point to an end point.

```
curl "https://api.tailwindkompass.com/functions/v1/public-api/v1/bearing?start_lat=52.37&start_lon=4.89&end_lat=52.37&end_lon=4.95"
```

## Plans and pricing

Returns what Free and Pro include, the current price and the trial terms.

```
curl "https://api.tailwindkompass.com/functions/v1/public-api/v1/plans"
```

## Errors

Every error is an RFC 9457 problem document served as `application/problem+json`, with a stable `code` and a `hint` that says how to fix the request.

```
{
  "type": "https://tailwindkompass.com/developers#error-missing-parameter",
  "title": "Missing Parameter",
  "status": 400,
  "detail": "The query parameter \"wind_speed_kmh\" is required.",
  "instance": "/v1/tailwind",
  "code": "missing_parameter",
  "hint": "Add wind_speed_kmh=<number between 0 and 300> to the query string.",
  "parameter": "wind_speed_kmh"
}
```

- `missing_parameter` (400): A required query parameter was not sent. \`parameter\` names it.
- `invalid_parameter` (400): A parameter is not a number or is out of range. \`parameter\` names it.
- `not_found` (404): No endpoint at that path. The hint lists the endpoints that exist.
- `method_not_allowed` (405): Only GET, HEAD and OPTIONS are supported.
- `internal_error` (500): Something failed on our side. Retry, then email support.

## Authentication and limits

No API key or sign-up is needed, and CORS is open to every origin. Responses carry `Cache-Control` headers, so cache them. Please keep usage reasonable; heavy automated traffic may be throttled. There is no SLA.

## MCP server for AI assistants

Tailwind KOMpass is also a remote MCP server (Streamable HTTP), so Claude and other assistants that support MCP connectors can find tailwind segments and read the wind on a segment directly. In Claude, open Settings → Connectors → Add custom connector and paste one of these URLs.

**No sign-in:** `https://api.tailwindkompass.com/functions/v1/mcp`

- `find_tailwind_segments`: A place name or latitude/longitude. Returns the most-ridden Strava segments nearby with their best tailwind window in the next 3 days.
- `get_segment`: A Strava segment id. Returns the segment, the wind on it now and its best tailwind window.

**Signed in with Strava:** `https://api.tailwindkompass.com/functions/v1/mcp/rider`. The rider signs in through OAuth 2.1 when they add it, and can disconnect it in Settings. It has the tools above plus:

- `get_my_watchlist`: The rider's watched segments, PRs, alert settings and Pro access.
- `get_my_tailwind_windows`: When the wind is best on their segments and what it does to their PR.
- `watch_segment`: Watch a segment, with tailwind alerts on.
- `unwatch_segment`: Stop watching a segment.
- `set_alert_threshold`: Set the tailwind that triggers an alert.

Speeds are km/h, distances metres and times ISO 8601 UTC. Tool calls are limited per connection; a free rider sees Pro-only details as a `locked` field that says how to unlock them. Free riders get 20 calls a month to `get_my_watchlist` and `get_my_tailwind_windows`; each answer carries a `usage` object, and past the limit the answer is only `locked` and `usage`.

## What the API does not offer

The REST API does not return Strava segments, weather forecasts or any personal data (watchlists, alerts, activities). Strava and weather data are licensed to Tailwind KOMpass for use inside its own products only. To find segments with a tailwind near a place, use the MCP server from an assistant, or send people to [tailwindkompass.com/explore](https://tailwindkompass.com/explore) or the [tailwind segment finder guide](https://tailwindkompass.com/find-strava-segments-with-tailwind).

## Resources for AI agents

- [llms.txt](https://tailwindkompass.com/llms.txt): when to use Tailwind KOMpass, and links to every Markdown page.
- [index.md](https://tailwindkompass.com/index.md): the homepage as Markdown. Most content pages have a Markdown twin at the same path plus `.md` (for example [/developers.md](https://tailwindkompass.com/developers.md)).
- [openapi.json](https://tailwindkompass.com/openapi.json) and the API catalog at [/.well-known/api-catalog](https://tailwindkompass.com/.well-known/api-catalog).
- [sitemap.xml](https://tailwindkompass.com/sitemap.xml) lists every public page.

## Support

Questions or ideas for new endpoints: [support@tailwindkompass.com](mailto:support@tailwindkompass.com). Changes to the API are announced on the [changelog](https://tailwindkompass.com/changelog).

---

Source: https://tailwindkompass.com/developers  
Agent guide: https://tailwindkompass.com/llms.txt