---
title: "List recent NWS text products of one type."
method: GET
path: "/v1/text-products"
tags: ["Guidance"]
---

# List recent NWS text products of one type.

`GET /v1/text-products`

## Request

- Base URL: `https://api.smarterweather.com`
- URL: `https://api.smarterweather.com/v1/text-products`
- Auth: HTTP bearer

Returns the newest NWS text products of one type (for example
`AFD` area forecast discussions or `HWO` hazardous weather
outlooks), newest `issued_at` first, with the bulletin text in
`body`. For distilled fields from the same products, use
`GET /v1/weather?include=guidance`.

### Scope

At most one of:

- `lat` + `lon` — products from the office that serves the
  point, or whose area contains it.
- `wfo` — products from one NWS Weather Forecast Office.

With neither, the query is national (for example SPC or WPC
products, narrowed with `awips_id`).

### Filters

- `awips_id` — exact AWIPS identifier (e.g. `AFDLOT`).
- `start` — RFC 3339 instant; only products issued after it.
- `limit` — 1 to 10, default 1. There is no pagination.
- `omit_body` — `true` returns metadata and `properties` with an
  empty `body`.

### Caching

Successful responses carry `Cache-Control: max-age=60,
stale-while-revalidate=60`, `public` for first-party keys and
`private` for partner keys.

### Coverage

With `lat`/`lon`, a point outside the 50 US states and DC returns
`404` `outside-coverage` with `next_steps`; `wfo` and national queries
are not filtered by point.

### Auth

Standard sw-api Bearer auth applies.

## Query parameters

- `product_type` string, required
- `lat` number, double
- `lon` number, double
- `wfo` string
- `awips_id` string
- `start` string, date-time
- `limit` integer
- `omit_body` boolean

## Response `200`

Matching products. `products` is an empty array when nothing matches.

- TextProductsResponse: `GET /v1/text-products` response. `products` is always an array, newest `issued_at` first.
  - `products` TextProduct[], required
    - `id` integer, required
    - `product_type` string, required
    - `wfo` string, nullable, required: Issuing office, or `null` for national-center products.
    - `issued_at` string, date-time, required
    - `expires_at` string, date-time, nullable, required
    - `awips_id` string, nullable, required
    - `wmo_header` string, nullable, required
    - `body` string, required: Bulletin text. Empty when `omit_body=true`.
    - `properties` object, required: Structured fields parsed from the product. Opaque; keys vary by product type and may be added without a sw-api release.

## 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.
- `402`: Trial key free value ended (lifetime cap spent or key clock expired) while the claim window is still open. Carries `next_steps.recommended = claim` and the per-key claim href.
- `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension.
- `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`).
- `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)