The corridor endpoint: a forecast that moves with you
A point forecast is one place at one time. A cross-country flight is a moving point. /v1/corridor samples along a track with the forecast hour advancing as you fly it.
Every other endpoint on the API answers a question about a fixed place. `/v1/site` is one point at one hour; `/v1/forecast` is one point all day; `/v1/grid` is many points at one hour. None of them quite fit the question a cross-country pilot is actually asking, which is: what will the air be doing along my route, at the time I get to each bit of it? A 14:00 forecast at launch is the wrong forecast for the goal you reach at 17:00. That mismatch is what the corridor endpoint exists to fix.
`/v1/corridor` is a POST. You give it a launch point (`launch_lat`, `launch_lon`), a `bearing_deg` for the direction of travel, a `max_distance_km`, and a `sample_spacing_km`. It samples the forecast fields at intervals along that line and hands them back as an ordered list. On its own, that is already a cleaner way to look at a planned leg than firing a dozen point requests and stitching them together.
The part that makes it different is time-aware mode. Set `time_aware: true` and add a `launch_time` and a `ground_speed_kmh`, and the endpoint stops returning one snapshot along the line. Instead, for each sample point it works out when you would actually arrive - distance divided by ground speed - and returns the forecast valid at that hour, advancing through the forecast hours, and into the next day if the flight is long enough. Each sample carries its own `estimated_arrival`. So the value for the point 60 km out is the forecast for when you are predicted to be there, not for the moment you pressed the button.
Why a bearing and a distance rather than an arbitrary track of waypoints? Because v1 keeps it simple, and a task leg is roughly a straight line anyway. For a task with turnpoints, you call the endpoint once per leg, each with its own bearing and its own launch time carried forward from where the previous leg ended. It is a small amount of stitching, and it keeps the request shape easy to reason about.
The corridor pairs especially well with the convergence fields. A long XC leg that runs down a convergence line is exactly the case where the line matters, and a time-aware corridor along it tells you whether the line is still going to be there - and still converging - by the hour you reach the far end. Reading `wstar_ms`, `cloudbase_agl_ft` and `horizontal_convergence_s1` along the corridor is most of a glide-or-not decision.
The honest limits: it is a straight-line corridor on a single bearing, the underlying grid is 4 km so it is the shape of the air rather than the exact thermal, and the arrival times are only as accurate as the ground speed you feed it - real XC speed varies leg to leg. Used with that in mind, it is the closest thing the API has to a forecast that flies the task with you. It is available on every tier, the free tier included, gated only by the resolutions your key can access; full request schema is in the API reference.