How the NWS API thinks

1. Everything starts with `/points`

You cannot ask the API for “the forecast at this latitude and longitude” in one call. You have to walk a short chain, and every newcomer trips on this exactly once:

1
GET /points/39.7456,-97.0892 Ask what covers this spot. The response tells you the forecast office is TOP (Topeka) and the grid square is 32,81.
2
GET /gridpoints/TOP/32,81/forecast Now ask for that grid square’s forecast. This is the readable one — “Tonight: Partly cloudy, low around 54”.
3
GET /gridpoints/TOP/32,81 Or ask for the raw grid instead: dozens of separate variables as time series, without any prose.

The /points response also hands you the forecast zone, the county, the fire weather zone, the nearest radar and the local time zone — so one call bootstraps almost anything else you want to do.

2. WFOs and the forecast grid

The country is divided among 122 Weather Forecast Offices, each known by a three-letter code. Every office maintains a grid over its area with squares roughly 2.5 km on a side, and forecasters edit that grid directly — they paint temperature and wind and cloud cover onto the map. The text forecast you read is generated from the grid, not the other way around.

Grid coordinates are per-office. TOP/32,81 and OUN/32,81 are completely different places. A grid coordinate is meaningless without its office code.

3. Zones, counties and fire zones are different shapes

NWS divides the country several ways at once, and they do not line up:

Public forecast zones — what zone forecasts and many advisories use.
County zones — county-based, used by many warnings.
Fire weather zones — drawn for fire behaviour, often following terrain.
Marine zones — coastal, offshore and high seas waters.

This is why a warning sometimes covers a visibly different area than the forecast for the same town. It is not a bug — they are genuinely different geographies, and a place has an ID in each system.

4. GeoJSON by default, JSON-LD on request

By default responses come back as GeoJSON: each item carries its data plus its shape on the map, ready to drop into a mapping library. Set Accept: application/ld+json and you get JSON-LD instead — the same data with semantic-web context and no geometry. Some endpoints also offer application/vnd.noaa.dwml+xml or plain text.

You will also notice @id, @context and @graph keys. Those are JSON-LD conventions: @graph holds the list of results, and @id is a URL you can fetch directly for the full record.

5. You must send a User-Agent

NWS asks every API client to identify itself with a User-Agent header containing a way to contact you — typically your app’s domain and an email address:

User-Agent: (myweatherapp.example.com, me@example.com)

This is not decoration. Requests without a meaningful User-Agent may be blocked, and it is how NWS reaches you if your client starts misbehaving. There are no API keys and no registration — the header is the whole contract. Be a good citizen: cache responses, respect the Cache-Control headers you get back, and back off when you see a 429.

6. Text products are the hidden library

Underneath the modern JSON sits a much older system: fixed-width text bulletins, each with a three-letter product code, issued by offices and national centres and unchanged in style for decades. There are over 300 codes. The Area Forecast Discussion (AFD) — where a forecaster explains their reasoning in plain prose — is arguably the most interesting thing NWS publishes, and hardly anyone outside the field knows it exists.

Browse the product codes → — or see them in action in the SDM message translator, which reads the ADM and ADA product feeds.