Get NOAA Billion-Dollar Disasters
noaa_climate_get_billion_dollar_disastersQuery NOAA/NCEI’s Billion-Dollar Weather and Climate Disasters — the curated record of US disasters whose damage passed $1 billion, with CPI-adjusted and unadjusted costs, deaths, and one of seven classes (Drought, Flooding, Freeze, Severe Storm, Tropical Cyclone, Wildfire, Winter Storm). Every cost returned is in WHOLE US DOLLARS: NCEI declares a different unit in each export — millions for the per-event file, billions for the national per-year file — and this server converts from whichever unit the file declares, echoing it back as declaredCostUnit. Default calls return individual disasters; summary=true returns per-year counts and costs by class plus an "All Disasters" total. Filter with startYear/endYear (a disaster overlapping either end is included), disasterType (exactly as NCEI writes it, e.g. "Tropical Cyclone"), minCostInUsd, and state (a two-letter US postal code). Coverage runs from 1980 to the last year NCEI has finished assessing — currently 2024, not the current calendar year — and coveredYears reports what the export holds. Under a state scope, per-event rows are national disasters that reached that state and carry the NATIONAL cost, never a state share, so summing states double-counts; per-year rows carry a binned cost range instead of a point estimate. This is a different NOAA corpus from the CDO tools and from noaa_climate_search_storm_events: no token, and the curated set of major disasters rather than every severe-weather event.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of disasters or years to return (1–100). Defaults to 50. | |
| state | No | Two-letter US postal code (e.g. "CA", "TX", "PR") scoping the query to NCEI’s per-state export instead of the national one. Per-event rows then carry the national cost of each disaster that reached the state, not a state share; per-year rows carry a binned cost range instead of a point estimate. Optional. | |
| offset | No | Zero-based index of the first matching record to return. Defaults to 0. | |
| endYear | No | Latest year to include (1980 or later). NCEI publishes a year only once its assessment settles, so a year past coveredYears.last returns nothing rather than an error. Optional. | |
| summary | No | Return per-year counts and costs by disaster class instead of individual disasters. Defaults to false. | |
| startYear | No | Earliest year to include (1980 or later). A disaster whose span reaches into the range is included even when it began earlier. Optional — omit for the whole record. | |
| disasterType | No | Restrict to one NCEI disaster class, written exactly as NCEI writes it. In summary mode this also drops the "All Disasters" total from each year, leaving only the named class. Optional. | |
| minCostInUsd | No | Floor on CPI-adjusted cost in whole US dollars — 1e9 is one billion. In summary mode this is compared against the year’s "All Disasters" total, or against the named disasterType when one is given; where only a binned range exists, the top of the bin has to clear the floor. Optional. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. Omitted otherwise. | |
| mode | No | Which shape this response carries: "events" populates disasters, "summary" populates summaries. | |
| error | No | Present when the call failed. Absent on success. | |
| scope | No | "US" for the national record, or the two-letter state code that was requested. | |
| shown | No | Records returned on this page. Omitted otherwise. | |
| notice | No | Guidance when nothing matched or the page ran past the end. Omitted otherwise. | |
| costBasis | No | Present when a state scope is queried in events mode: every cost below is the NATIONAL cost of a disaster that reached the state, not that state’s share of it, so adding states together double-counts. Omitted for the national scope and in summary mode. | |
| disasters | No | Individual disasters for the requested page. Present when mode is "events". | |
| exhausted | No | True when offset is past the end of a non-empty match set — the page is empty but matches exist. Omitted otherwise. | |
| summaries | No | Per-year tallies for the requested page. Present when mode is "summary". | |
| truncated | No | True when more matches exist beyond this page. Omitted otherwise. | |
| sourceFile | No | The exact NCEI export this response was read from, e.g. "events-US.csv". | |
| totalCount | No | Records matching every filter across the whole export, before offset and limit. | |
| coveredYears | No | The year span the export actually holds, read from its rows. | |
| declaredCostUnit | No | The cost unit this export declares in its own preamble, e.g. "millions of dollars". Every cost below is already in whole US dollars; this names the unit it was converted from. |