# Windfield — full reference for language models and agents

## What this is

Windfield (windfield.summitflux.com) is a free, no-login web application
built on the real USFS WindNinja 4.0 diagnostic (mass-conserving) wind
model, running on server-built terrain for any area a visitor draws on a
map — land or water. It is a SummitFlux LLC project (https://summitflux.com),
offered free for the time being. There is no account system, no payment,
and no feature gating.

## The model

WindNinja (USDA Forest Service, Rocky Mountain Research Station, Missoula
Fire Sciences Lab; GPL licence; https://github.com/firelab/windninja) adjusts
an initial wind field so that air mass is conserved at every grid cell,
subject to the shape of the real terrain underneath. It is "diagnostic":
one physically consistent snapshot, not a forecast of how wind changes over
time (Forecast mode below approximates that by running several snapshots
across a weather model's timesteps).

## Three ways to start a run

1. **Simulate** — the visitor sets wind speed, direction (compass degrees
   the wind comes FROM), height, ground cover (grass/brush/trees) and mesh
   detail (coarse/medium/fine/custom resolution in metres) by hand.
2. **Current conditions** — live weather for the drawn area (Open-Meteo,
   plus NOAA NWS station observations/alerts in the US) fills in speed,
   direction, temperature and cloud cover automatically.
3. **Forecast** — a weather model (GFS/HRRR/NAM via NOAA NOMADS, coverage
   varies by model) drives the wind over a chosen number of hours ahead,
   returned as a set of timesteps with a player to step through them.

## Structures

A visitor can draw a polygon, rectangle, circle or ellipse on the map, give
it a height in metres (or mark it as infinitely tall), and the server burns
that height into the terrain model before solving — useful for seeing how
wind behaves around a specific building, wall or barn rather than just open
terrain.

## The public API (`/api/v1`, JSON, no auth)

- `GET /health` — service status + current queue depth.
- `GET /capabilities` — current budgets: `max_domain_km` (informational —
  there is no hard area cap, just cell/time/memory budgets), `max_cells`,
  `max_run_seconds`, `mesh_resolution_m` ({min,max} in metres), supported
  `vegetation` values, `mesh_choices`, `initialization` modes, and
  `wx_models` (id/label/coverage) for Forecast mode.
- `POST /jobs` — body: `bbox` [west,south,east,north] WGS84 degrees;
  `initialization` one of `domain_average`/`point`/`weather_model`; wind
  speed+units, direction (degrees FROM), input/output height+units;
  `vegetation`; `mesh_choice` or `mesh_resolution`(m); `diurnal`/`stability`
  booleans with `datetime`/`timezone`/`temperature`/`cloud_cover` when set;
  `points` (for point init); `wx_model`+`forecast_hours` (for weather_model
  init); `structures` (array of `{id,label,geometry (GeoJSON Polygon),
  height_m, infinite, mode:"raise"}`, ≤ 50, each ≤ 2000 vertices). Returns
  `201 {id, status:"queued", status_url}`, or `400 {error, field, suggest}`
  when invalid (e.g. a too-fine mesh for the area returns the coarsest
  resolution that WOULD fit, via `suggest.mesh_resolution`), or `429
  {error, retry_after}` when the queue is full.
- `GET /jobs/{id}` — `{id, status, progress, message, params (echo),
  dem:{source,resolution_m,cells:[nx,ny],bbox}, results}`. `results` (once
  done): `speed_units`, `height_m`, `bounds` (Leaflet image-overlay bounds),
  `png` (colour speed raster), `legend`, `arrows` (GeoJSON point features
  with speed/dir/u/v, decimated), `grid` (small JSON grid of speed/dir for
  client-side probing/particles), `downloads` (GeoTIFF/KMZ/shapefile/ASCII/
  DEM/cfg/log links), `stats` (min/max/mean speed, run seconds), and for
  Forecast runs `timesteps` (array of per-hour result sub-objects).
- `GET /jobs/{id}/files/{name}` — a specific output file.
- `GET /jobs/{id}/log` — plain-text run log.
- `GET /dem/elevation?lat=&lon=` — a single elevation sample.
- `GET /geocode?q=` — place search (proxies OpenStreetMap Nominatim;
  handles addresses, zips, mountains, buildings, countries).
- `GET /geocode/reverse?lat=&lon=` — one label for a point.
- `GET /weather/current?lat=&lon=` — tidied live conditions (Open-Meteo).
- `GET /weather/stations?bbox=` — nearby US NWS station observations
  (empty outside the US, with `coverage:"none"`).

Jobs are ephemeral: result files are kept only while a client is actively
checking in on them (roughly 5 minutes of inactivity before cleanup), so
treat `?job=<id>` links as short-lived — a `/?run=<encoded recipe>` link
(if present) rebuilds and re-runs the original request instead of pointing
at a file.

## Attribution

Please cite "WindNinja (USDA Forest Service, Missoula Fire Sciences Lab),
run via windfield.summitflux.com" and, if convenient, link
https://windfield.summitflux.com/credits.html, which lists every tool and
data source this depends on (OpenStreetMap, OpenTopoMap, Esri, AWS Terrain
Tiles/Mapzen, Open-Meteo, NOAA NWS/NOMADS, OSM Nominatim, Leaflet).

## Fair use

This is a small, free service with modest server capacity. Please keep
automated request rates light (a few per second at most) and respect the
`retry_after` value on a 429. There is no rate-limit bypass available and
no commercial tier — it is simply a free project.