DEVELOPER REFERENCE · v1

A packet. Not a model dump.

Wind at native heights with provenance on every number, and a deterministic decision against the limits you pass. The language model never produces these values. Missing data is returned as missing, never as zero.

Authentication

Create a key in Account → API keys (Pro, Ops and Enterprise). Keys look like wa_live_…, are shown once, and can be revoked at any time. Send the key as a bearer token. CORS is open, but keep keys server-side.

Authorization: Bearer wa_live_<32 base64url characters>

GET /api/v1/wind

Seven days of hourly wind for a point. Speeds in mph, directions in degrees the wind blows from. Gust is the model 10 m gust; there is no derived gust aloft. Times are site-local wall clock in location.timezone.

Param	Type	Notes
lat	number	−90 … 90, required
lon	number	−180 … 180, required

curl -H "Authorization: Bearer wa_live_YOUR_KEY" \
  "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"

RESPONSE EXCERPT

{
  "location": { "latitude": 52.3387, "longitude": -7.6553, "elevationM": 175, "timezone": "Europe/Dublin" },
  "current": {
    "time": "2026-10-03T16:00",          // site-local wall clock
    "speedMph": 5.1, "gustMph": 11, "directionDeg": 204,   // 10 m, direction FROM
    "agreementScore": 78, "agreementCount": 3,
    "heights": {
      "h80":  { "speedMph": 8.6, "directionDeg": 200 },
      "h120": { "speedMph": 8.9, "directionDeg": 200 },
      "h180": { "speedMph": 8.4, "directionDeg": 200 }
    }
  },
  "hourly": [ /* 168 hours, same shape */ ],
  "provenance": {
    "kind": "forecast", "source": "Open-Meteo modelled Best Match",
    "models": ["ICON", "GFS", "ECMWF IFS"], "heightsM": [10, 80, 120, 180],
    "modelRuns": [{ "model": "ecmwf_ifs025", "runInitialisedAt": "2026-10-03T06:00:00.000Z", ... }],
    "coverage": { "requestedHours": 168, "returnedHours": 168, "droppedIncompleteHours": 0 }
  }
}

GET /api/v1/decision

The deterministic decision for the current hour plus the candidate windows in the forecast where your limits hold. The engine is the same code the instrument runs; the agent only explains its output.

Param	Type	Notes
lat, lon	number	required
mode	enum	golf · crane · spray · marine · drone · motorsport · events (required)
maxGustMph	number	default 25 — set it from your own document
minWindMph	number	default 3
maxWindMph	number	default 10
bearingDeg	number	0 … 360, default 90 (route/hole bearing for cross/headwind modes)

curl -H "Authorization: Bearer wa_live_YOUR_KEY" \
  "https://thewindagent.com/api/v1/decision?lat=51.834&lon=-8.322&mode=crane&maxGustMph=27"

DECISION PACKET SHAPE

{
  "mode": "crane",
  "config": { "maxGustMph": 27, "minWindMph": 3, "maxWindMph": 10, "bearingDeg": 90 },
  "timezone": "Europe/Dublin",
  "current": {
    "tone": "good" | "watch" | "stop",
    "verdict": "…", "score": 0-100,
    "summary": "…", "recommendation": "…", "threshold": "…",
    "drivers": ["…"]
  },
  "candidateWindows": [
    { "start": "2026-10-04T07:00", "end": "2026-10-04T13:00", "hours": 6 }   // site-local, end exclusive
  ],
  "provenance": {
    "decisionEngine": "The Wind Agent deterministic rules (analyzeImpact)",
    "windowsNote": "Windows are site-local times; end is exclusive. Modelled forecast, not an on-site observation.",
    …forecast provenance
  }
}

Ensemble exceedance (p10 / p50 / p90 / pExceed with member counts per model) is served to the instrument from GFS, ECMWF IFS ENS and ICON-EPS members. Probabilities are raw member fractions, not calibrated; hours with fewer than 10 members return pExceed: null, insufficient: true. Models are never silently substituted. Ensemble on the public v1 API is not yet exposed.

Rate limits

Plan	Calls / UTC day	Keys
Free	—	No API access
Pro	1,000	5
Ops	10,000	5
Enterprise	100,000	5

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the cap you get 429 with Retry-After.

Errors

400	Invalid coordinates, mode or thresholds
401	Missing, malformed or revoked key
403	Plan does not include API access
429	Daily cap reached
502	Forecast source unavailable — retry; we never return stale data as fresh

Attribution

Show “Wind data: The Wind Agent” with the upstream sources wherever you display values: Open-Meteo · ECMWF IFS/ENS · NOAA GFS/GEFS · DWD ICON · ERA5 (Copernicus) · aviationweather.gov METAR · NOAA NDBC · OpenFreeMap/OpenStreetMap. Open-Meteo data is CC BY 4.0. Label values as modelled forecasts — planning support, not on-site measurement — and never present them as a safety clearance.

Get a key Plans