> For the complete documentation index, see [llms.txt](https://api-v2-docs.disasteraware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-v2-docs.disasteraware.com/hazards/requesting-wind.md).

# Requesting Wind Hazards

To request the list of active severe wind hazards please use the route defined here:

{% openapi src="/files/wYQaKpPZEdPb68ZWOF6w" path="/wind" method="get" %}
[openapi.yaml](https://3664004773-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwQ2AvqpbIy1hD3QFTQG%2Fuploads%2Fgit-blob-4fc8ade7ac9fbaa181ac86605d2bddb657fbc964%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% hint style="info" %}
See [Authorizing Requests](/authentication/authorizing-requests.md#get-accesstoken-and-refreshtoken) page to get your accessToken.
{% endhint %}

{% hint style="warning" %}
**This endpoint requires a specific role for wind feed access on your credentials.** It is not enabled by default, and credentials that work against the other hazard endpoints will not necessarily work here.

If your token is valid elsewhere but this endpoint returns `403`, your credentials are missing the required role. Contact your sales contact or <support@disasteraware.com> to have it added, or if you are interested in severe wind data and do not have access today.
{% endhint %}

Wind hazards are DisasterAWARE hazards of type `STORM` with `incident.properties.subType` of `WIND`. Each one is built from the NWS severe thunderstorm warnings carrying a wind tag or a damage threat, the measured gusts, and the wind damage reports that belong to the same storm, so a single hazard carries the warning text, the evidence footprint and the reports together. DisasterAWARE `STORM` and `TORNADO` records are not returned here.

## How the feed works

The endpoint serves a file, not a query result:

* **No parameters** — a `302` redirect to the current gzipped NDJSON file, one hazard per line, with every active wind hazard included. The link is valid for **1 hour**.
* **With parameters** — a `302` to a filtered file, valid for **5 minutes**, plus an `X-Match-Count` header. Zero matches is still a `302`, to an empty file.
* **Freshness headers on every `302`** — `X-Feed`, `X-Generated-At` (when the file was last written) and `X-Heartbeat-At` (the feed's last heartbeat), as ISO 8601 UTC.
* **The file carries the same values as S3 metadata** — `x-amz-meta-generated-at` and `x-amz-meta-heartbeat-at`, plus `x-amz-meta-record-count` on the unfiltered file. This matters because **most HTTP clients discard the first response's headers when they follow a redirect**, so read the freshness from the file's metadata if your client follows the `302` for you.
* **Staleness** — the file is rewritten when something changes, at most every 2 minutes, so polling faster than that gains nothing. The feed publishes a heartbeat to prove it is running; if that heartbeat is more than **15 minutes** old the endpoint returns `503 {"error": "Live feed temporarily unavailable"}` with `Retry-After: 60` rather than serving stale data. A `503` is not routine — it means the feed is not current. Each feed is monitored separately, so a `503` on `/wind` says nothing about `/hail`: a client polling both should handle each response on its own.
* **Scope** — `scope=active` is the default and the only value available. `scope=historical` and `scope=all` return `501` naming the available scopes.

### Polling

Take the `X-Generated-At` value from your last response and pass it back as `updated_since` to receive only the hazards that have changed since then. `updatedAt` changes only when a hazard's content changes, and `version` counts those changes.

### When a hazard leaves the feed

This is an **active-only** feed. A hazard leaves the file on the first write after it ends, and moves to the history archive — which `scope=historical` will serve when it becomes available.

{% hint style="info" %}
A hazard that has disappeared from the file has **ended**; it has not been deleted. Because the file holds only current hazards, a client that needs to detect endings should compare successive files rather than waiting for a final record. Merged hazards also leave: the absorbed hazard ends with `end_basis` of `merged` and `incident.properties.supersededBy` set to the surviving hazard's uuid.
{% endhint %}

## Query Parameters

All parameters are optional, combine with AND, and take comma-separated lists meaning "any of", matched case-insensitively. Anything that works as a `country` value on [`/active-hazards-query`](/hazards/requesting-active-hazards.md) works here, and these endpoints also accept ISO 3166 codes. Timestamps are UTC, as `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SSZ`.

A misspelled parameter or a value outside a closed set returns `400` with the offending parameter, its value, and either `allowed_values`, `allowed_parameters` or `expected_format`. **A bad value is never a silent empty result.**

A `403` means one of three things — no token, an invalid token, or a credential without the required role — and the response is identical in all three cases:

```json
{"Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"}
```

So a `403` cannot be read as "my role is missing". Check the token first, then ask whether the credential carries the required role.

### Wind-specific

| Parameter          | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| **min\_gust\_mph** | `windAssessment.max_measured_gust_mph` at or above this speed.                                     |
| **wind\_basis**    | One or more of `gust_measured`, `damage_reported`, `forecast_only`. See [Wind basis](#wind-basis). |
| **damage\_threat** | One or more of `base`, `considerable`, `destructive`. See [Damage threat](#damage-threat).         |

### Common

| Parameter                                      | Description                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------- |
| **uuid**, **type**, **severity**, **category** | As on [`/active-hazards-query`](/hazards/requesting-active-hazards.md). |

\| **country** | ISO 3166 alpha-2 code, alpha-3 code, or country name. The length decides: two characters is matched as an alpha-2 code, three as an alpha-3 code, and four or more as a case-insensitive substring of `location.admin0`. So `US`, `USA`, `United States` and `United States of America` all match the same records, while `US` never matches Australia because short values are only ever compared as codes. Comma-separated list, any of. | | **state** | State as `TX` or `US-TX`. | | **name**, **comment** | Substring match. | | **started\_at**, **created\_at**, **updated\_at** | On or after the given time. | | **ended\_at** | On or before the given time. | | **updated\_since** | Strictly after the given time. The polling parameter. | | **latitude**, **longitude** | `min,max` range, tested against the hazard's own point. | | **scope** | `active` only; see above. |

## Wind basis

`windAssessment.wind_basis` is never null and says what the hazard rests on:

| `wind_basis`         | Meaning                                                      |
| -------------------- | ------------------------------------------------------------ |
| **gust\_measured**   | A measured gust of 58 mph or more.                           |
| **damage\_reported** | Wind damage reports, or an estimated gust of 58 mph or more. |
| **forecast\_only**   | An NWS warning with no observed evidence yet.                |

Filter on `wind_basis=gust_measured,damage_reported` for hazards with observed evidence, and on `forecast_only` for warnings that have not yet been confirmed on the ground.

## Damage threat

`windAssessment.damage_threat` is the highest NWS damage-threat tag across the linked warnings: `base`, `considerable` or `destructive`.

{% hint style="warning" %}
**`null` means no linked warning carries a damage-threat tag — not that there is no threat.** Treat a null as "not tagged" and fall back to the gust and report evidence rather than reading it as an absence of danger.
{% endhint %}

## The wind record

Standard V2 hazard fields as documented under [Requesting Active Hazards](/hazards/requesting-active-hazards.md#response-fields), with `type` `STORM`, `severity` `WARNING` and `category` `EVENT`. Timestamps are epoch seconds. `latitude`/`longitude` is a point inside the report footprint, or inside the warning when there are no reports yet.

### Geometry

**`alertGeometry`** is a GeoJSON FeatureCollection with one Feature per linked NWS warning, at that warning's current polygon, with `properties` null. A hazard with no warning carries one Feature holding the lowest-level observed outline.

**`exposureAreas`** is a GeoJSON FeatureCollection of where the wind evidence was observed, carrying a single Feature at `properties.exposureLevel` 1 — the footprint of the damage reports and gusts of 58 mph or more. It is literally an empty object when nothing has been observed yet, which is the case for a warning-only hazard:

```json
"exposureAreas": {}
```

Not `null`, and not an empty FeatureCollection — so test for an absent `features` array rather than for a null. Warning-only hazards are common: in live history a little over half the hail records and roughly two thirds of the wind records carry `{}` here. `windAssessment.exposure_levels` describes it.

### `windAssessment`

The summary block: `wind_event_key`, `max_warning_wind_tag_mph`, `damage_threat`, `max_measured_gust_mph`, `max_gust_mph`, `total_damage_reports`, `total_gust_reports`, `total_measured`, `total_reports`, `wind_basis`, `exposure_levels`, `end_basis`, `sources_consulted` (each source with a status of `observed` or `none_observed`), `enhancedAt` and `enhancer`.

### `windDetails`

The evidence behind the summary: `wind_reports`, `warnings` (each linked NWS warning with its VTEC, tags, damage threat, current polygon and every version), and `report_timeline` — 10-minute steps from the first report to the last, carrying cumulative report and damage counts, maximum gusts, and the report footprint each time it changed.

## Lifecycle

A wind hazard stays active until every part of it is finished: its warnings have expired or been cancelled, and wind reports have been quiet for 60 minutes.

While it is active, `endedAt` is a **projection**, `incident.properties.endedAtKind` is `projected`, and `windAssessment.end_basis` is `null`. When it ends, `endedAt` becomes the last part's end time, `endedAtKind` becomes `observed`, and `end_basis` says why:

| `end_basis`          | Meaning                                                                              |
| -------------------- | ------------------------------------------------------------------------------------ |
| **warning\_expired** | The linked warnings expired or were cancelled.                                       |
| **reports\_quiet**   | No wind reports for 60 minutes.                                                      |
| **merged**           | Absorbed into another hazard; `incident.properties.supersededBy` names the survivor. |

The day after, once late reports have arrived, the history record is finalised as a new version. There is no archive of every intermediate version: the active file holds each hazard's current version, and history holds its ended and finalised version.

## Sample

See [Severe Wind Sample](/hazards/hazard-samples/wind-sample.md) for a complete record.