National Weather Service (NWS) new API

Here is what I have learned so far about working with this new NWS API.  The input I use is the locations lat and lng. The output I want is weather data (temp, preceip, cloud cover, etc…) for that location in a grid, hour by hour. I have included links to run or download a one page PHP working example, you will find those below the code snippets.

National Weather Service API Streaming Setup

To stream anything from you must first set the stream header to include the Accept, Version and User-Agent. If you do not set the header the stream will return empty. NWS asks that you include your website and email address in the User-Agent so the they can contact you if need be.

$UserAgent = "YOURWEBSITE (";
// HTTP stream options:
$opts = array(
 'header'=>"Accept: application/geo+json;version=1\r\n" .
 "User-agent: $UserAgent\r\n"
$context = stream_context_create($opts);

After the header is set you can stream the /points/lat,lng endpoint into a json object and pull forecastGridData, which is the /gridpoints/office/x/y endpoint. If you do not need a detailed gridded forecast take a look at the /points/lat,lng/forecast/ or /points/lat,lng/forecast/hourly in the documentation.

$lat = 43.0204;
$lng = -71.6002;
$pointMetaUrl = "$lat,$lng";
$pointMetaFile = file_get_contents($pointMetaUrl, false, $context);
$pointMetaArray = json_decode($pointMetaFile, true);
$forecastGridData = $pointMetaArray["properties"]["forecastGridData"];

Now stream the detailed gridded forecast using the forecastGridData /gridpoints/office/x/y endpoint. Then start pulling the data you want.

$gridDataFile = file_get_contents($forecastGridData, false, $context);
$gridDataArray = json_decode($gridDataFile, true);
$temp = $gridDataArray["properties"]["temperature"]["values"];

Here is the code above in one file you can run or download:

Run Code Example  Download Code Example (raw)

Each weather element is returned as an array of arrays, including a time and value (e.g. temperature). The value may span more than one hour.  validTime is formatted as  ISO 8601, with a PHP  DateInterval suffix, like: “PT2H”. “PT2H” is a 2 hour interval, “PT3H” is 3 hours, “PT4H” is 4 hours, and so on. So the temperature (-6.111 C) in the example below “…T08:00:00+00:00/PT2H” covers 2 hours (8AM, 9AM GMT).

"values": [
                    "validTime": "2017-02-17T08:00:00+00:00/PT2H",
                    "value": -6.1111111111111

Published by


Kimball is a website designer and developer in Goffstown, NH.

25 comments on:
“National Weather Service (NWS) new API”

  1. I am trying to decode the “validTime” field in the NOAA forecast file for my zone. It currently shows: “validTimes”: “2021-03-09T06:00:00+00:00/P7DT19H”. What is the meaning of “P7DT19H”? I was expecting something like “PT8H”. Thanks!

  2. Fantastic! Have been looking for an “open” weather api and it looks like this is the one I want. WU is closed and the others don’t give me a clear “forecast” like this does. My goal is a Raspberry Pi kitchen weather station and this makes it possible (but parsing the return with JS in Node Red will be an uphill slog for me). Thanks for putting this out there.

    1. 1) I would get the lat,lng for the location I wanted with Google Maps or some other service or API.

      2) Then look up that location in the weather API, using the lat,lon:,-97.0892

      3) In the response above you will see an “hourly” forecast URI to access the current weather forecast which includes the icon/image. “hourly” URI example:,80/forecast/hourly

      The hourly forecast current icons/images look like this:

      1. Thank you so much! That helped clear things up! I have it working now. This post might become very popular now that WU has made big changes to their API Keys.

  3. Great information. Thank you! I must be missing something, and I hope you can point me in the right direction. When I’m pulling latest observation data, the temps come up in Celsius. Is there a way to pull temp data in Fahrenheit?

  4. Thanks so much for this! It really helped point me in the right direction! Figured I would leave a friendly comment for those that use cURL.

    $lat_long = $lat . ‘,’ . $long;
    $noaa_url = ‘ . $lat_long;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
    ‘Accept: application/geo+json;version=1’,
    ‘User-agent: YOURWEBSITE (’
    curl_setopt($ch, CURLOPT_URL, $noaa_url);

    $result = curl_exec($ch);
    $result = json_decode($result, true);

    Thanks again! This really was a huge time saver!

  5. I have a silly question. What language are you using? It looks like JS but I have never seen that many $ sine basic in the early 1980’s. I am not a JS expert. I generally write a few lines and then spend a few hours looking up errors. Tremors are not helping much either 🙂

  6. I’m looking for the definition of the terms used by the NWS API to help understand the context for terms like: map, grid, current, forecast etc. related to data returned from requests.

    For example, what is the definition for a grid? How is a grid define by the NWS? What is the size of a grid? Is the grid dynamic? There are many grid systems used by maps, such as: USNG, UTC, MGRS etc.

    Is there a link to a NWS page that contains term definitions and examples of API requests? I understand the NWS is using JSON-LD, but still, there should be more documentation, yes?

    Thanks you,

  7. In the past I could get a forecast by zip code by using “”

    Is there still a way to get the forecast by zip code with the new api? I have tried something like this but it has not worked.

  8. Thanks for this. When trying to retrieve the forecast for a given lat, lon pair, I am getting this error message:

    “The requested forecast grid was issued 2018-02-20T14:04:39+00:00 and has expired”

    Any idea of what’s going on?

  9. Can you explain Noaa’s point in adding php DateInterval to validTime?
    Could it mean for example PT2H – for this hour and next the value is the same?

    1. Yes, exactly. Below is a sample of temperatures pulled from,21

      In the sample you will see:
      [validTime] => 2017-10-25T07:00:00+00:00/PT2H covers 2 hours (7AM, 8AM)
      [validTime] => 2017-10-25T09:00:00+00:00/PT3H covers 3 hours (9AM, 10AM, 11AM)
      [validTime] => 2017-10-25T12:00:00+00:00/PT1H covers 1 hour (12PM)

      "temperature": {
      "sourceUnit": "F",
      "uom": "unit:degC",
      "values": [
      "validTime": "2017-10-25T07:00:00+00:00/PT2H",
      "value": 16.666666666667
      "validTime": "2017-10-25T09:00:00+00:00/PT3H",
      "value": 16.111111111111
      "validTime": "2017-10-25T12:00:00+00:00/PT1H",
      "value": 17.222222222222

  10. I’m trying to do this same thing in VBA, but all I’m getting is “Method Not Allowed” responses when I try to POST or PUT:

    Dim xmlhttp As Object
    ‘Set xmlhttp = CreateObject(“WinHttp.WinHttpRequest.5.1”)
    Set xmlhttp = CreateObject(“MSXML2.serverXMLHTTP”)
    xmlhttp.Open “GET”, “”
    ‘xmlhttp.Open “PUT”, “”, False
    xmlhttp.setRequestHeader “Accept”, “application/vnd.noaa.dwml+xml;version=1”
    xmlhttp.setRequestHeader “User-Agent”, “OCSCSailing

    ‘xmlhttp.Open “GET”, “”
    ‘ Send Request.
    ‘And we get this response
    MsgBox xmlhttp.responseText

    1. Not sure but perhaps the issue is you are calling for a format the endpoint does not support. application/vnd.noaa.dwml is only available at /points/{point}/forecast.

      The available formats are listed on the API Reference tab.

Leave a Reply

Your email address will not be published. Required fields are marked *