api.weather.gov represents the public face of the next generation of data services from the National Weather Service. It offers public access to a wide range of essential weather data, in a 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 and external customers. We’re doing this to help eliminate some internal redundancies, giving you and our own forecasters and developers a one-stop shop for vital data.
Our current documentation is located at https://www.weather.gov/documentation/services-web-api. Over time we will also 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).
You’ll need to know the latitude and longitude of the location in decimal degrees. (If you want to get really geospatially technical, your location should be a WGS 84 or EPSG 4326 coordinate.)
Once you know the latitude and longitude, it’s an easy three-step process from there. You can follow along in your browser with the links below:
propertiesobject, and inside that, find the
forecastproperty. You’ll find another URL there.
forecastHourlyproperty. For our example it’s https://api.weather.gov/gridpoints/LWX/96,70/forecast/hourly
We’re still working on documentation for the JSON that API returns, but we think it’s pretty easy to understand if you just look at it. If you need more reference, the forecast JSON very closely aligns with the information you’d see on a web page on forecast.weather.gov. If you still have questions, please see our Reporting Issues page for how to ask.
Not directly. You’ll need to turn that location into a latitude/longitude pair as described earlier. This is called geocoding.
Our API does not offer a geocoding service. There are many free and paid API services available for this. Here are a few:
Yes. Part of the API’s design is to improve efficiency and reduce data redundancy. National Weather Service forecasts are issued on a 2.5km grid. The /points request is to translate your position to the grid square that it’s in. A lot of different points will resolve to the same grid, and we can share that same data with many different users in the same area.
The point mappings don’t change very often, so you can cache the result of the /points request to avoid doing it repeatedly. (Also see the next question.)
The API is designed from the ground up to always provide current data as well as properly support HTTP caching. We send back Cache-Control headers to advise how long to hold on to a response, and Last-Modified headers so you can validate if 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 query parameters 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 it longer than it should, please let us know.
Make sure your program is including a
User-Agent header in your request. We recommend setting the value to something
that 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, please let us know.
Depending on what service you’re using, the data may already be available via the API.
You can follow the directions from earlier on how to get a forecast. On the third
step, you can request the DWML instead of the JSON forecast by adding an
Accept header with the value
application/vnd.noaa.dwml+xml to your request. (You’ll need to consult the documentation for your program’s HTTP
library 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 focus for support going forward.
The API won’t support the existing JSON format, but take a look at the new JSON format as described earlier. We think you’ll agree that it’s much simpler to use in your application.
You can continue to use the existing legacy services on
forecast.weather.gov, but we encourage you to move to the API
when you can. We have more resources dedicated to supporting the API and much of our future development will be focused
Please give us some feedback on what you’re using, so we can evaluate it for future inclusion into the API, or point you to the best place to get the information.