Skip to content

Latest commit

 

History

History
142 lines (115 loc) · 5.49 KB

gridpoints.md

File metadata and controls

142 lines (115 loc) · 5.49 KB
Raw

Gridpoint Frequently Asked Questions

What's a gridpoint?

Each National Weather Service forecast office issues numerical forecasts on a 2.5-kilometer grid across their entire forecast area. Each gridpoint is one of these 2.5km squares.

The /gridpoints endpoint in the API gives you access to this raw numerical data.

How do I determine the gridpoint for my location?

You can retrieve the metadata for a given latitude/longitude coordinate with the /points endpoint (https://api.weather.gov/points/{lat},{lon}).

The forecastGridData property will provide a link to the correct gridpoint for that location.

Can I search by city or airport instead?

Please see our FAQ about geocoding.

How is the gridpoint data formatted?

  • The data is presented as a JSON document.
  • The document will contain metadata about the forecast grid, along with multiple layers of data (such as temperature).
  • The layer data is presented as a time series.
    • Much of the data is calculated for each hour of the forecast period, but to conserve bandwidth the API will merge consecutive values that are equal.
    • Each data point will have the following properties:
      • validTime: This is the time interval that the value applies to. The interval is represented in ISO 8601 format.
        • For example, 2019-07-04T18:00:00+00:00/PT3H represents an interval starting on July 4, 2019 at 1800 UTC and continuing for 3 hours (from 1800 to 2100).
      • value: This is the data that applies to that validTime interval.
        • For values that have a unit of measure, such as temperature, the layer will contain a uom property to indicate the unit of all the values in that time series.
        • The value may also be null to indicate there is no applicable data for that interval.

What layer data is available?

Below is a list of layers that the API exposes.

Commonly used layers
  • temperature: Air temperature
  • dewpoint: Dewpoint temperature
  • maxTemperature: High temperature
  • minTemperature: Low temperature
  • relativeHumidity: Relative humidity
  • apparentTemperature: Apparent temperature (heat index or wind chill)
  • heatIndex: Heat index. This is the apparentTemperature data with values filtered out that are below the threshold of the heat index calculation.
  • windChill: Wind chill. This is the apparentTemperature data with values filtered out that are above the threshold of the wind chill calculation.
  • skyCover: Percentage of sky with cloud cover
  • windDirection: Direction of prevailing wind
  • windSpeed: Maximum prevailing wind speed
  • windGust: Maximum wind gust
  • weather: Weather conditions
    • This data is not numeric, but an array.
    • Each array element is a JSON object representing a decoded NDFD GRIB weather string.
  • hazards: Long-duration area watches, warnings, and advisories in effect.
    • This data is not numeric, but an array.
    • Each array element is a JSON object with phenomenon and significance properties. These values correspond to P-VTEC phenomenon and significance codes. For example, FF and A would indicate a Flash Flood Watch.
    • Optionally, the object may include an event_number property. This number will correspond to an issued watch, warning, or advisory product. For example, TO, A, and 267 would indicate Tornado Watch #267.
    • Note that not all forecast offices utilize this layer for all watch/warning/advisory products. It is most typically used for tropical storm and hurricane watches and warnings.
  • probabilityOfPrecipitation: Chance of precipitation
  • quantitativePrecipitation: Amount of liquid precipitation
Other layers
  • iceAccumulation:
  • snowfallAmount:
  • snowLevel:
  • ceilingHeight:
  • visibility:
  • transportWindSpeed:
  • transportWindDirection:
  • mixingHeight:
  • hainesIndex:
  • lightningActivityLevel:
  • twentyFootWindSpeed:
  • twentyFootWindDirection:
  • waveHeight:
  • wavePeriod:
  • waveDirection:
  • primarySwellHeight:
  • primarySwellDirection:
  • secondarySwellHeight:
  • secondarySwellDirection:
  • wavePeriod2:
  • windWaveHeight:
  • dispersionIndex:
  • pressure:
  • probabilityOfTropicalStormWinds:
  • probabilityOfHurricaneWinds:
  • potentialOf15mphWinds:
  • potentialOf25mphWinds:
  • potentialOf35mphWinds:
  • potentialOf45mphWinds:
  • potentialOf20mphWindGusts:
  • potentialOf30mphWindGusts:
  • potentialOf40mphWindGusts:
  • potentialOf50mphWindGusts:
  • potentialOf60mphWindGusts:
  • grasslandFireDangerIndex:
  • probabilityOfThunder:
  • davisStabilityIndex:
  • atmosphericDispersionIndex:
  • lowVisibilityOccurrenceRiskIndex:
  • stability:
  • redFlagThreatIndex:

How can I tell if the grid data has been updated?

The API supports HTTP conditional requests. All gridpoint endpoints will include a Last-Modified header showing the creation time of the grid data we received from the forecast office. You may include this time in the If-Modified-Since header on subsequent requests to determine if the data has been updated. If it has not, you will receive a 304 (Not Modified) response.

If your HTTP client cannot support conditional requests for some reason, this information is also in the updateTime property of the gridpoint data.

I see some really strange values (like temperatures in the thousands).

Please report this as an operational issue.