---
title: "Get NWS climate-record events as GeoJSON."
method: GET
path: "/v1/record-events"
tags: ["Storms"]
---

# Get NWS climate-record events as GeoJSON.

`GET /v1/record-events`

## Request

- Base URL: `https://api.smarterweather.com`
- URL: `https://api.smarterweather.com/v1/record-events`
- Auth: HTTP bearer

Returns a GeoJSON `FeatureCollection` of NWS climate-record
events (record high / low temperatures, daily precipitation
records, etc.) within the requested time window. Each feature's
`properties` bag carries at minimum `valid_time` plus the
event-type-specific payload from the data pipeline. As with
`/v1/storm-reports`, additional `properties` keys may appear
without a sw-api release.

### Time window

Three selectors choose the window:

1. `date=YYYY-MM-DD` — single-day window
2. `start=...&end=...` — explicit RFC3339 window (both required
   together)
3. `hours=N` — rolling lookback, applied from 1 to 720 (30 days).

If several are set, `date` wins, then `start`+`end`, then
`hours`; every selector that is set must still be well formed.
With none, the last 24 hours.

### Filters

- `wfo` — 3-letter NWS Weather Forecast Office identifier.
- `type` — alphabetic record-event code (2-16 characters, e.g.
  `high`, `low`, `precip`, `snow`).

### Caching

Successful responses carry `Cache-Control: public, max-age=60,
stale-while-revalidate=60`.

### Auth

Standard sw-api Bearer auth applies.

## Query parameters

- `hours` integer
- `date` string
- `start` string, date-time
- `end` string, date-time
- `wfo` string
- `type` string

## Response `200`

GeoJSON FeatureCollection. Empty `features` array when no
record events match the window + filters.

## Other responses

- `400`: Bad request.
- `401`: Missing or invalid API key. Carries a `WWW-Authenticate` challenge and a `next_steps` extension. `recommended` is `device_flow`: the object is a complete no-install mint recipe.
- `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension.
- `429`: Rate limit exceeded. Carries a `next_steps` extension (`recommended: upgrade`, plus `pricing` and `usage`) telling the caller how to lift the limit.
- `500`: Internal server error.
- `502`: Bad gateway. The service received an invalid response from an upstream data source. Transient; clients should retry with backoff.
- `503`: Service unavailable. An upstream dependency is unavailable or shedding load (type `service-unavailable`). Transient; retry with backoff and honor any `Retry-After` header.
- `504`: Gateway timeout. An upstream data source did not respond within the service's budget.

---

[API](https://skmtc.dev/smarterweather/apis/smarter-weather-api.md) · [All operations](https://skmtc.dev/smarterweather/apis/smarter-weather-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smarterweather/apis/smarter-weather-api/revisions/520d55a696e4?raw)