api.weather.gov: General FAQs (2024)

General FAQs

What’s the API?

api.weather.gov represents the public face of the next generation of data services from theNational Weather Service. It offers public access to a wide range of essential weather data, ina way that modern web developers expect: a REST-style, JSON-based web service.

The API is also being built to provide a powerful and modern platform for data dissemination for both internal andexternal customers. We’re doing this to help eliminate some internal redundancies, giving you and our own forecastersand developers a one-stop shop for vital data.

I’m new to this. How do I use the API?

Our current documentation is located at https://www.weather.gov/documentation/services-web-api. Over time we willalso be offering this information here as well.

We also provide a service definition in OpenAPI v3.0 (previously known as Swagger)format. You can access this file at https://api.weather.gov/openapi.json (in JSON format)or https://api.weather.gov/openapi.yaml (in YAML format).

Much of the data returned from the API is in GeoJSON (RFC 7946) format. Certain endpoints alsooffer useful alternative formats, such asOASIS Common Alerting Protocol (CAP) XML for alertsdata.

How do I get a forecast for a location from the API?

You’ll need to know the latitude and longitude of the location in decimal degrees. (If you want to get reallygeospatially technical, your location should be a WGS 84 or EPSG 4326 coordinate.)

For our example here, we’ll use the Washington Monument in Washington, D.C. It’s located at 38.8894 latitude,-77.0352 longitude.
Please note that, for efficiency purposes, the API doesn’t support more than four decimal places of precision incoordinates. If you send a more precise coordinate, you’ll receive an error giving you the closest proper coordinate.Four decimal places is about 30 feet (10 meters) over most of the United States, so that should still be closeenough!

Once you know the latitude and longitude, it’s an easy three-step process from there. You can follow along in yourbrowser with the links below:

Retrieve the metadata for your location from https://api.weather.gov/points/{lat},{lon}.
- For our example the URL will be https://api.weather.gov/points/38.8894,-77.0352
You’ll get back a JSON document. Inside the document, find the properties object, and inside that, find theforecast property. You’ll find another URL there.
- For our example this gives us https://api.weather.gov/gridpoints/LWX/96,70/forecast
- You can also get the hour-by-hour forecast from the forecastHourly property. For our example it’shttps://api.weather.gov/gridpoints/LWX/96,70/forecast/hourly
Retrieve that URL. You’ll get a JSON document containing the forecast for that location. There you go!

We’re still working on documentation for the JSON that API returns, but we think it’s pretty easy to understand if youjust look at it. If you need more reference, the forecast JSON very closely aligns with the information you’d see on aweb page on forecast.weather.gov. If you still have questions, please see our Reporting Issues pagefor how to ask.

I have an address, city name, or zip code location. Can I request data for this location via the API?

Not directly. You’ll need to turn that location into a latitude/longitude pair as described earlier. This is calledgeocoding.

Our API does not offer a geocoding service. There are many free and paid API services available for this. Here are afew:

Do I really have to do two requests?

Yes. Part of the API’s design is to improve efficiency and reduce data redundancy. National Weather Service forecastsare issued on a 2.5km grid. The /points request is to translate your position to the grid square that it’s in. A lot ofdifferent points will resolve to the same grid, and we can share that same data with many different users in the samearea.

The point mappings don’t change very often, so you can cache the result of the /points request to avoid doing itrepeatedly. (Also see the next question.)

How do I know I’m getting the latest data? Do I need to use “cache busting” methods?

The API is designed from the ground up to always provide current data as well as properly support HTTP caching. We sendback Cache-Control headers to advise how long to hold on to a response, and Last-Modified headers so you can validateif the data has changed later. Many clients will automatically make use of these headers with a bit of configuration.

Please don’t use cache busting techniques like random numbers in the query string. Requests like this with queryparameters that aren’t recognized by the API will return a 400 (Bad Request) response.

If you do run into a case where you believe the API is not giving you the latest data, or advising you to cache itlonger than it should, please let us know.

I’m getting a 403 (Forbidden/Access Denied) error from the API.

Make sure your program is including a User-Agent header in your request. We recommend setting the value to somethingthat identifies your application and includes a contact email. This helps us contact you if we notice unusual behavior,such as your program consuming a high amount of resources.

In the future we will replace the User-Agent requirement with a more typical API key system.

If you’re including the User-Agent header and are still having problems, pleaselet us know.

I already use some of the NWS web services on forecast.weather.gov. How can I switch my application to use the API?

Depending on what service you’re using, the data may already be available via the API.

I use the Digital Weather Markup Language service on forecast.weather.gov.

You can follow the directions from earlier on how to get a forecast. On the thirdstep, you can request the DWML instead of the JSON forecast by adding an Accept header with the valueapplication/vnd.noaa.dwml+xml to your request. (You’ll need to consult the documentation for your program’s HTTPlibrary on how to add a request header.)

We would encourage you to change your application to use the new JSON forecast format, as this will be our main focusfor support going forward.

I use the JSON service on forecast.weather.gov.

The API won’t support the existing JSON format, but take a look at the new JSON formatas described earlier. We think you’ll agree that it’s much simpler to use in yourapplication.

I’m not able to switch to using the API just yet.

You can continue to use the existing legacy services on forecast.weather.gov, but we encourage you to move to the APIwhen you can. We have more resources dedicated to supporting the API and much of our future development will be focusedhere.

I’m using a service that isn’t described here.

Please give us some feedback on what you’re using, so we can evaluate it for futureinclusion into the API, or point you to the best place to get the information.

General FAQs
Information about specific endpoints
- Gridpoints
Reporting Issues