--- title: "Outlook detail for a location and hazard family (SPC, WPC, CPC)." method: GET path: "/v1/outlooks" tags: ["Weather"] --- # Outlook detail for a location and hazard family (SPC, WPC, CPC). `GET /v1/outlooks` ## Request - Base URL: `https://api.smarterweather.com` - URL: `https://api.smarterweather.com/v1/outlooks` - Auth: HTTP bearer Returns everything the Storm Prediction Center says about one outlook day at a point for a hazard family: the risk band, any probabilistic hazards (severe only), whether the location falls in a hatched significant-severe area, and the forecaster's full written discussion. For `hazard=temperature|precipitation` it instead returns the Climate Prediction Center's extended-range outlooks at the point (see "Climate outlooks" below). This is the drill-down behind a risk area on a map. `GET /v1/weather?include=outlooks` already reports the single worst-case risk level at a location; this endpoint expands that into the per-hazard breakdown and the reasoning behind it. ### Hazard families `hazard=severe` (default) returns the convective outlook: categorical risk plus tornado/wind/hail probabilities, with the SWO discussion (`SWODY1`/`SWODY2`/`SWODY3`, or `SWOD48` for days 4-8). `hazard=fire` returns the fire-weather outlook band (`ELEV`/`CRIT`/`EXTM`) and the FWD discussion (`FWDDY1`/ `FWDDY2`, or `FWDD38` for days 3-8), plus a separate `dry_thunderstorm` band (`IDRT`/`SDRT`) when SPC has drawn one -- the two fire criteria are independent, so either can be present without the other. Fire polygons exist for days 1-2 only, so a fire request for day 3+ may return a narrative with no band. `hazard=rain` returns the WPC Excessive Rainfall Outlook band (`MRGL`/`SLGT`/`MDT`/`HIGH`) for days 1-3 and the QPFERD discussion (one PIL; day is selected from `properties.outlook_day`). ### Climate outlooks `hazard=temperature` and `hazard=precipitation` return the CPC outlooks for the 6-10 day, 8-14 day, week 3-4, and monthly periods in `periods`, one entry per period, in that order. Each entry gives the tercile CPC favors (`above`, `below`, `near`, or `equal_chances`) and the probability bin it assigns to that tercile (`probability_min`/`probability_max`, fractional, so `0.4`/`0.5` is 40-50%). `equal_chances` means CPC favors no tercile and carries no bin; it is not the same as `near`. `period` (`610`, `814`, `wk34`, or `monthly`) narrows the answer to one period. `day` does not apply and is ignored. At a covered location, a period with no outlook polygon is omitted (an answer of "no outlook here", not equal chances. `probabilities` is always empty; `day` is always `1` and carries no meaning (each period has its own `valid_start` and `valid_end`). When a 6-10 or 8-14 day period is present, `narrative` carries CPC's prognostic discussion (`PMDMRD`) unless it is more than 72 hours old. This answer keeps one entry per period and leaves out the seasonal (3-month) outlooks; `GET /v1/outlooks/climate` serves every CPC outlook, seasonal leads included, without `day` or `probabilities`. ### Probabilities Days 1 and 2 are issued as separate `tornado`, `wind`, and `hail` products, so `probabilities` holds one entry per hazard. Day 3 and beyond issue a single combined `probabilistic` product and yield one entry. Values are fractional (`0.15` = 15%). Fire and rain outlooks have no probabilistic products; `probabilities` is empty for those hazards. SPC delineates significant severe as its own polygon rather than an attribute of the probability area. Where the two overlap they are reported as a single entry carrying both the probability and `significant: true`, so a 15% hail area with a hatched overlay reads as one hazard rather than two. ### Narrative `narrative` carries the discussion for the requested family and day. It is ingested separately from the outlook polygons, so it may be absent for a few minutes after a new issuance, and it is omitted rather than erroring when unavailable. ### Empty results A location outside every outlook polygon is a valid answer: `200` with an empty `probabilities` array and no `categorical`. Only an upstream failure produces an error. ### Caching Successful responses are cacheable for 5 minutes. SPC reissues the day 1 outlook a handful of times a day. Climate outlook responses are cacheable for 5 minutes as well, although CPC issues them at most daily. ### Coverage A point outside the 50 US states and DC returns `404` `outside-coverage` with `next_steps`. ### Auth Standard sw-api Bearer auth applies. ## Query parameters - `lat` number, double, required - `lon` number, double, required - `day` integer - `hazard` 'severe' | 'fire' | 'rain' | 'temperature' | 'precipitation' - `period` '610' | '814' | 'wk34' | 'monthly' ## Response `200` Outlook detail for the requested day and location. - OutlookDetail: Drill-down detail for one SPC convective outlook day at a location: the categorical risk band, each probabilistic hazard, and the forecaster's written discussion. For the CPC hazards (`temperature`, `precipitation`) it carries `periods` instead. Everything except `day` and `probabilities` is optional. A point can sit inside a categorical polygon with no probabilistic coverage, and the narrative is ingested separately from the polygons so it can lag a fresh issuance. - `day` integer, required: The outlook day this detail describes (1 = today). For the CPC hazards (`temperature`, `precipitation`) it is always `1` and carries no meaning; use each period's `valid_start` and `valid_end`. - `categorical` Outlook: Single SPC convective outlook (or equivalent product) active for the location. - `product_id` string, required: Upstream product identifier (e.g., `spc_otlk_day1`). - `type` string, required: Hazard category (`severe`, `tornado`, `hail`, `wind`, etc.). - `day` integer, required: Day number relative to issuance (1 = today). - `risk` string: Raw risk identifier from the upstream source. - `probability` number, double: Fractional probability (0-1) when the source provides one. - `risk_label` string, required: Human-readable risk label. - `valid` string, date-time, required - `expires` string, date-time, required - `significant` boolean: The location falls inside SPC's hatched significant-severe area for this hazard — tornadoes of EF2+, hail 2 in or larger, or wind gusts of 65 kt or more. SPC ships this as its own polygon, so it is reported here as a flag on the hazard it qualifies rather than as a separate entry. Absent (or `false`) outside the hatched area. - `dry_thunderstorm` Outlook: Single SPC convective outlook (or equivalent product) active for the location. - `product_id` string, required: Upstream product identifier (e.g., `spc_otlk_day1`). - `type` string, required: Hazard category (`severe`, `tornado`, `hail`, `wind`, etc.). - `day` integer, required: Day number relative to issuance (1 = today). - `risk` string: Raw risk identifier from the upstream source. - `probability` number, double: Fractional probability (0-1) when the source provides one. - `risk_label` string, required: Human-readable risk label. - `valid` string, date-time, required - `expires` string, date-time, required - `significant` boolean: The location falls inside SPC's hatched significant-severe area for this hazard — tornadoes of EF2+, hail 2 in or larger, or wind gusts of 65 kt or more. SPC ships this as its own polygon, so it is reported here as a flag on the hazard it qualifies rather than as a separate entry. Absent (or `false`) outside the hatched area. - `probabilities` Outlook[], required: One entry per probabilistic hazard covering the point. Days 1-2 break these out as `tornado`, `wind`, and `hail`; day 3 and beyond issue a single combined `probabilistic` product. Empty when no probabilistic polygon covers the location. Categorical bands never appear here. - `product_id` string, required: Upstream product identifier (e.g., `spc_otlk_day1`). - `type` string, required: Hazard category (`severe`, `tornado`, `hail`, `wind`, etc.). - `day` integer, required: Day number relative to issuance (1 = today). - `risk` string: Raw risk identifier from the upstream source. - `probability` number, double: Fractional probability (0-1) when the source provides one. - `risk_label` string, required: Human-readable risk label. - `valid` string, date-time, required - `expires` string, date-time, required - `significant` boolean: The location falls inside SPC's hatched significant-severe area for this hazard — tornadoes of EF2+, hail 2 in or larger, or wind gusts of 65 kt or more. SPC ships this as its own polygon, so it is reported here as a flag on the hazard it qualifies rather than as a separate entry. Absent (or `false`) outside the hatched area. - `periods` ClimateOutlook[]: CPC climate outlooks at the location for `hazard=temperature|precipitation`, one per period in the order 6-10 day, 8-14 day, week 3-4, monthly. A period with no outlook polygon at the location is omitted. Absent for the other hazards. - `product_id` string, required: Upstream product identifier. - `period` '610' | '814' | 'wk34' | 'monthly' | 'seasonal', required: `610` (6-10 day), `814` (8-14 day), `wk34` (week 3-4), `monthly` (a calendar month), or `seasonal` (a three-month season; see `lead`). `GET /v1/outlooks` returns only the first four, one entry each. `GET /v1/outlooks/climate` can return two `monthly` entries per variable: this month, plus next month from CPC's mid-month seasonal release until the month-end monthly update. Entries are unique by (`period`, `variable`, `valid_start`). - `lead` integer: The seasonal lead, for `period: seasonal` only. CPC issues 13 overlapping three-month outlooks; lead 1 starts the month after issuance and each later lead starts one month later. - `valid_label` string: CPC's name for the outlook window, for `monthly` and `seasonal` entries from `GET /v1/outlooks/climate`: a month (`Oct 2026`) or a three-month season of month initials (`NDJ 2026-2027`). - `variable` 'temperature' | 'precipitation', required - `category` 'above' | 'below' | 'near' | 'equal_chances', required: The favored tercile. `near` means near normal is favored; `equal_chances` means CPC favors no tercile. - `probability_min` number, double: Lower edge of the favored category's probability bin, fractional (`0.4` = 40%). Omitted for `equal_chances`. - `probability_max` number, double: Upper edge of the favored category's probability bin, fractional. Omitted for `equal_chances`. - `label` string: Human-readable category and bin. - `valid_start` string, date-time: Start of the outlook period. - `valid_end` string, date-time: End of the outlook period (exclusive). - `issued_at` string, date-time, required: When CPC issued the outlook. - `narrative` OutlookNarrative: The SPC forecaster's written discussion for an outlook day, as issued in the corresponding SWO text product. - `awips_id` string: AWIPS identifier of the source product — `SWODY1`, `SWODY2`, `SWODY3` for the single-day outlooks, `SWOD48` for days 4-8, `PMDMRD` for the CPC 6-10/8-14 day discussion. - `issued_at` string, date-time - `body` string: Full narrative text as written by the forecaster. - `summary` string: Short generated summary, when one is available. ## Other responses - `400`: Bad request. - `404`: Resource not found: a location that cannot be resolved (unknown ZIP, unrecognised free-text location), no upstream data for the location, or a missing resource. On a route that checks coverage (its description says so), a location outside the 50 US states and DC returns type `https://smarterweather.com/errors/outside-coverage`; that and the location-not-found problem carry `next_steps` (`recommended = coverage`). - `502`: Bad gateway. The service received an invalid response from an upstream data source. Transient; clients should retry with backoff. - `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)