# Documentation

How KOMpass works, in plain language

## Why some segments are missing from the map

Segments only appear when you zoom in to **zoom level 10 or higher** (roughly city-district scale). At lower zoom levels the map shows no segments: there would simply be too many to display usefully.

Even at zoom 10+ the map shows up to **1 000 segments at a time**. In very dense areas not every segment may be visible. Try zooming in further to narrow the area.

KOMpass only knows about segments that **have been ridden by connected users**. When a connected athlete finishes a ride, Strava notifies KOMpass and the segments from that activity are added to the database. If a segment you expect to see is missing, it may simply not have been ridden by any connected user yet.

## How wind data is collected

Wind conditions are fetched automatically based on your map location and updated as you move around. Data is sourced from **WeatherAPI.com** and refreshed roughly every hour.

**Wind forecasts** let you plan ahead: free users see the next 3 hours, Pro extends the lookahead to 72 hours.

Wind readings reflect conditions at the nearest weather station, which may be kilometres away. Valleys, forests, and urban canyons can create local conditions that differ from the reported wind.

## How the effective tailwind is calculated

Each segment shows an **effective tailwind speed**: the wind component aligned with the segment's direction, in km/h (or mph, if you've switched units). Tailwind is positive, headwind is negative.

The figure is the projection of the wind vector onto the segment bearing: only the part of the wind that pushes you along (or against) the segment counts. A strong crosswind that blows exactly perpendicular to the segment reads 0.

effective\_tailwind = wind\_speed × cos((wind\_direction + 180°) − segment\_bearing)

Wind direction is meteorological (the direction the wind is blowing *from*), so it's flipped 180° to the direction it's blowing *towards* before comparing it to the segment's bearing.

- +12: a 12 km/h tailwind pushing you along the segment
- 0: calm air, *or* a pure crosswind (wind blowing 90° to the segment)
- \-7: a 7 km/h headwind working against you

Example: a 20 km/h wind blowing at 60° to the segment direction projects to **20 × cos(60°) = +10 km/h** of effective tailwind. The same 20 km/h wind blowing straight at you (180°) reads **−20 km/h**.

Segment colours on the map follow the same number: red for strong headwind, yellow around zero, green for strong tailwind. The colour ramp is anchored at ±25 km/h.

The power analysis page uses the same raw wind data but applies an additional terrain shielding factor to model boundary-layer effects when estimating effort.

## Segment filters

The filter panel appears when you are zoomed in to level 10 or higher. The following filters are available:

- **Distance**: slider from 0 to 7 km. The upper end ("7+") means no upper cap; use it to see all long segments.
- **Elevation type** buckets segments into:
    - Flat: average grade < 2% and elevation gain < 50 m
    - Hilly: grade ≥ 2% or gain ≥ 50 m
    - Climb: grade ≥ 5% or gain ≥ 200 m
- **Aligned with wind**: toggle that hides segments below a minimum effective tailwind. The threshold defaults to **8 km/h** and can be adjusted with the sub-slider. Disabled when no wind data is available.
- **Exclude circular segments**: hides loop segments whose start and end points are less than 5% of the segment length apart.
- **Show only watchlist segments**: limits the map to the segments on your watchlist. Only available when you are logged in.

## Map styles & layers

Use the map style switcher (bottom-right of the map) to change the base map and overlay layers.

**Base map styles** (all available on every tier):

- Streets (Standard): default
- Dark
- Light
- Satellite: aerial imagery
- Hybrid: satellite + road labels
- Winter: high-contrast topographic style

**Layer toggles:**

- Wind particle animation: shows animated wind direction and relative speed; free
- Tailwind colours on segments PRO: colours each segment red→yellow→green by its effective tailwind
- 3D terrain: raises the map into a 3D hillshade view

## Dashboard

The Dashboard (`/dashboard`, available from the sidebar once your Strava account is connected) is the home base for tracking wind opportunities on the segments you care about.

**Right now**, always available:

- Athlete header with profile + current location
- Current wind reading at your location
- "Best now": the single Watchlist segment with the most favourable wind right now
- "Now opportunities": a short list of currently-favourable Watchlist segments
- Mini wind map preview

**Next 72 hours PRO**:

- "Best window": the single best upcoming wind window across your Watchlist
- Forecast wind chart with numbered markers for the top opportunities
- Ranked list of top forecast wind windows

Free users see the real segment and wind magnitude for every window: only the precise timing and verdict are locked behind a Pro tap. All forecast cards are powered by your **Watchlist**. They stay empty until you add segments to it.

## KOM Finder

KOM Finder is a search mode that narrows the segments around you to the KOMs within *your* reach. It does not use the wind; once you have a shortlist, the wind readings and power analysis tell you when to go. With a rider profile set, a *Suggested for you* preset fills the filters in from your FTP and weight. Open it from the sidebar or the toggle on the map.

**Filters:**

- **Search area**: radius around your current location (1–15 km), or the current map viewport (Pro only)
- **Length**: segment distance range
- **Max KOM speed**: filters out segments where the KOM is moving so fast it's effectively unreachable
- **Popularity**: based on the segment's effort count (hidden gems, moderately known, popular)
- **Surface**: paved or unpaved
- **Terrain**: flat, hilly, or climb
- **KOM proximity**: only segments you have ridden where your best time is within a chosen percentage of the KOM (free down to 50%, tighter stops on Pro)

Segments you have ridden carry a badge with your gap to the KOM; on mobile the list is ordered by that gap, easiest first. The selected segment is highlighted on the map together with the search radius.

**Free tier:** full result list in radius mode, KOM proximity at 50% or Any. **Pro:** viewport mode and the tighter proximity stops (down to 5%).

## Watchlist

The Watchlist is your personal list of segments KOMpass actively monitors for you. It powers the Dashboard forecast cards and is the pool that wind alerts are checked against.

Add a segment to your Watchlist from its details panel on the map. Manage entries from the Segments page: each row has a bell icon to open per-segment alert settings PRO and a trash icon to remove.

**Free and Pro:** unlimited Watchlist slots. Pro additionally unlocks per-segment custom alert thresholds (the bell icon on each row).

## Power analysis

The **Segments** page provides a physics-based model that estimates whether you can beat the KOM on a segment given current wind conditions.

**FTP and body weight are required** to run an analysis. You'll be prompted to enter them on first use. They're saved to your profile and reused on every subsequent run.

**Inputs you provide:**

- FTP (Functional Threshold Power) in watts
- Body weight in kg (or lb)

**The model estimates:**

- The power needed to match the KOM time, accounting for the segment's gradient, distance, and current wind
- How much power you can realistically sustain for that duration based on your FTP
- The resulting time gap and a feasibility percentage

Advanced settings (bike weight, drivetrain efficiency, riding position, and terrain sheltering) are available to fine-tune the estimates to your setup.

**Required wind to beat the KOM**

Once a segment is analysed, KOMpass works the model backwards to answer: *what wind do I actually need to take this KOM?* Three outcomes are possible:

- **Already faster**: your fitness alone beats the KOM time, no wind help required.
- **Realistic**: KOMpass shows the minimum effective tailwind (in km/h or mph) that would close the gap.
- **Unrealistic**: even a perfect tailwind isn't enough; the KOM is out of reach at your current FTP/weight.

When the result is "Realistic" and the segment is on your Watchlist, a one-click button creates a wind alert at exactly the minimum tailwind needed PRO.

**Free tier:** the full analysis (power curve, pacing plan, required-wind, and advanced settings) for up to **3 unique segments per calendar month**. Re-opening a segment you've already analysed this month doesn't count again. **Pro:** unlimited segments, plus custom per-segment alert thresholds from the required-wind result.

## Surface & popularity

Each segment carries two extra attributes used by the KOM Finder filters and shown in the segment details panel:

- **Surface type**: paved, unpaved, or unknown. Inferred from OpenStreetMap data and cached for several weeks. Unknown is shown when OSM has no clear surface tag for the road the segment runs on.
- **Effort count**: the number of attempts logged on Strava. Drives the KOM Finder popularity slider, letting you choose between hidden gems and well-trafficked classics.

## Wind alerts

KOMpass can alert you when segments on your **Watchlist** have favourable wind conditions, configured on the **Alerts** page. Alerts are delivered by **push notification** where you've enabled it, falling back to **email** when no device is reachable. You'll get an alert on one channel, not both.

**Free tier:** one daily check covering current conditions on your Watchlist segments. **Pro PRO**: up to 72 h of forecast lookahead, custom per-segment thresholds, quiet hours, skip-forecast slots, and minimum-time-between-alerts controls.

**How alerts work:**

- Alerts are checked regularly throughout the day against every segment on your Watchlist.
- Only segments whose forecast effective tailwind meets your **threshold** (default 12 km/h, range 0–35 km/h) trigger an alert.
- You can choose to be alerted for current conditions only, or look ahead up to **72 hours** to get advance notice of upcoming tailwinds.
- A **minimum time between alerts** setting (default 6 h) prevents repeated alerts during a prolonged tailwind period.
- **Quiet hours**: define a time window (e.g. 22:00–07:00) during which no alerts are sent, regardless of conditions.
- **Skip forecast slots**: forecast hours inside this window are excluded from the check entirely, so a great predicted tailwind at 03:00 won't trigger an alert even if it falls inside your lookahead range.

Quiet hours suppress the alert itself; skip forecast slots filter out the forecast hours before scoring. They work independently and can be combined.

You won't receive duplicate alerts for the same conditions on the same segment.

## Use it in Claude

You can ask **Claude**, or any AI assistant that supports MCP connectors, where and when the wind is behind you: “Where’s a tailwind near Girona this weekend?”, “When is the wind best on my segments?” or “Watch segment 22179925 for me.” The assistant gets the same numbers the app shows.

**Connect it in Claude**

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Give it a name (for example “Tailwind KOMpass”) and paste the URL below. You can also copy it from **Settings → Account**.
3. Claude opens a Tailwind KOMpass page that names the assistant and what it may do. Choose **Allow**, then approve on Strava.
4. Ask away. Claude picks the right tool itself.

`https://api.tailwindkompass.com/functions/v1/mcp/rider`

Once connected, the assistant can find tailwind segments near any place, read the wind on any segment, and work with your own data: your watchlist, when the wind is best on your segments and what it would do to your PR, watching and unwatching segments, and your alert threshold.

A signed-in assistant can only reach your watchlist and alert threshold: it can’t change your profile, payment or account. Watching a segment through it works like watching it in the app, so arming your first alert can start the **7-day Pro trial**. Free riders see how strong each window is; when it opens and the PR verdict are Pro PRO, just like on the Dashboard. Free riders can also ask about their own segments (watchlist and tailwind windows) **20 times a month**; questions about any place or segment, and watching segments or setting your threshold, don’t count. Pro has no limit.

To cut an assistant off, open **Settings → Account → Connected assistants** and choose **Disconnect**. Disconnecting Strava or deleting your account removes every assistant too.

No Strava account? There is a public connector for any place, without signing in. [See Developers](https://tailwindkompass.com/developers#mcp).

## Billing & plans

Tailwind KOMpass offers a free tier and **Pro** three ways: **€4.99 a month**, **€29 a year** or **€79 once** ($5.99, $35 or $90). Cancel a subscription any time from Settings; Pro then runs to the end of the period you paid for. Every rider also gets a **7-day full-Pro trial** when they arm their first tailwind alert, no payment required.

| Feature | Free | Pro (from €4.99 / month) |
| --- | --- | --- |
| Segment map & effective tailwind | ✓ | ✓ |
| Base map styles | All 6 styles + 3D terrain | All 6 styles + 3D terrain |
| Tailwind colours on segments | – | ✓ |
| Wind forecast | 3 hours | 72 hours |
| Dashboard 72 h forecast | – | ✓ |
| Watchlist slots | Unlimited | Unlimited |
| KOM Finder | Radius mode only | Radius + viewport mode |
| KOM proximity filter | Within 50% | Down to 5% |
| Power analysis (full detail) | 3 segments / month | Unlimited |
| Required-wind analysis | Within the 3-segment cap | ✓ Unlimited |
| Custom per-segment alert thresholds | – | ✓ |
| GPX / FIT exports | Unlimited | Unlimited |
| Wind alerts | Push or email, current conditions only | ✓ (up to 72 h forecast, full controls) |
| Claude & AI assistants (how) | Tailwind near any place, unlimited; your own segments 20 / month | Unlimited, with window times and PR verdicts |
| Free Pro trial (arm your first alert) | 7 days, full Pro | Already included |

Payment is handled by **Polar**. After purchase you receive immediate Pro access, no account setup required beyond your existing Strava connection.

## Frequently asked questions

### Do I need a Strava account to use Tailwind KOMpass?

You can browse the map and see effective-tailwind readings for each segment without logging in. However, to see your starred segments, run power analysis, or set up tailwind alerts, you need to connect your Strava account.

### Why does a windy segment show 0 km/h?

The number on each segment is the effective tailwind: the wind component aligned with the segment. A pure crosswind (blowing exactly 90° across the segment) reads 0 km/h no matter how strong it is. Only the part of the wind that pushes you along (or against) the segment direction counts.

### Why is wind data sometimes inaccurate?

Wind data comes from WeatherAPI.com and represents conditions at a nearby weather station, not exactly on the segment. Local terrain (valleys, forests, buildings) can create micro-climates that differ from the reported wind. The effective-tailwind figure is a planning tool, not a guarantee.

### What is the difference between starring a segment on Strava and adding it to my Watchlist?

Strava stars are a Strava-side bookmark. The KOMpass Watchlist is the list KOMpass actively monitors. It powers your Dashboard forecast cards and your wind alerts. Add a segment to your Watchlist from the segment details panel; remove it from the Segments page.

### Can I get alerts for segments that are not on my Watchlist?

No, alerts only fire for segments on your Watchlist. Add a segment from its details panel and it will be included on the next alert check.

### What is the difference between free and Pro KOM Finder?

Free users get the full list of matching segments in the radius-around-me search, with the KOM-proximity filter at 50% or Any. Pro additionally unlocks viewport mode, which searches the current map area instead of a radius around your location, and the tighter proximity stops down to 5%.

### What is different about Pro power analysis?

Free users get the full analysis (power curve, pacing plan, required-wind, and advanced settings) on up to 3 unique segments per calendar month (re-opening an already-analysed segment is free). Pro removes that cap, gives unlimited segments, and adds custom per-segment alert thresholds based on the required-wind result.

### How do I cancel my Pro subscription?

Open Settings → Account and choose Manage subscription. Cancelling keeps Pro until the end of the month or year you paid for, then you are back on Free. Lifetime Pro is a one-time purchase, so there is nothing to cancel.

### How do I try Pro for free?

Arming your first tailwind alert starts a 7-day full-Pro trial, no payment required. When the trial ends you can keep Pro monthly, yearly or with a one-time Lifetime purchase.

### Where do I report a bug or send feedback?

Use the "Feedback & Bugs" button in the sidebar (or mobile menu). This sends a message directly to the developer. You can also reach out on X at @thom\_hartogg.

### Not all segments I see on Strava appear on the map. Why?

KOMpass only shows segments that have been ridden by connected users. When a Strava athlete who has linked their account completes a ride, KOMpass receives a webhook from Strava and stores the segments from that activity. If a segment is missing, it most likely hasn't been ridden by any connected user yet.

Something missing? Send it through Feedback and bugs in the sidebar.

---

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