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. “PT2H” means a 2 hour interval. So the temperature (-6.111 C) 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.

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

  1. 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.

  2. 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

  3. 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?

  4. 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,

  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. 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!

  7. 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?

Leave a Reply

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