NOAA — National Oceanic and Atmospheric Administration Gridpoints API
The Gridpoints API from NOAA — National Oceanic and Atmospheric Administration — 4 operation(s) for gridpoints.
OpenAPI Specification
openapi: 3.1.2
info:
title: weather.gov Alerts Gridpoints API
description: weather.gov API
version: 3.9.2
servers:
- url: https://api.weather.gov
description: Production server
security:
- userAgent: []
- apiKeyAuth: []
tags:
- name: Gridpoints
paths:
/gridpoints/{wfo}/{x},{y}:
parameters:
- $ref: '#/components/parameters/GridpointWFO'
- $ref: '#/components/parameters/GridpointX'
- $ref: '#/components/parameters/GridpointY'
get:
description: Returns raw numerical forecast data for a 2.5km grid area
operationId: gridpoint
parameters: []
responses:
'200':
description: Gridpoint forecast data
headers:
X-Correlation-Id:
$ref: '#/components/headers/CorrelationId'
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-Server-Id:
$ref: '#/components/headers/ServerId'
content:
application/geo+json:
schema:
$ref: '#/components/schemas/GridpointGeoJson'
application/ld+json:
schema:
$ref: '#/components/schemas/GridpointJsonLd'
default:
$ref: '#/components/responses/Error'
tags:
- Gridpoints
/gridpoints/{wfo}/{x},{y}/forecast:
parameters:
- $ref: '#/components/parameters/GridpointWFO'
- $ref: '#/components/parameters/GridpointX'
- $ref: '#/components/parameters/GridpointY'
get:
description: Returns a textual forecast for a 2.5km grid area
operationId: gridpoint_forecast
parameters:
- $ref: '#/components/parameters/GridpointForecastFeatureFlags'
- $ref: '#/components/parameters/GridpointForecastUnits'
responses:
'200':
$ref: '#/components/responses/Gridpoint12hForecast'
default:
$ref: '#/components/responses/Error'
tags:
- Gridpoints
/gridpoints/{wfo}/{x},{y}/forecast/hourly:
parameters:
- $ref: '#/components/parameters/GridpointWFO'
- $ref: '#/components/parameters/GridpointX'
- $ref: '#/components/parameters/GridpointY'
get:
description: Returns a textual hourly forecast for a 2.5km grid area
operationId: gridpoint_forecast_hourly
parameters:
- $ref: '#/components/parameters/GridpointForecastFeatureFlags'
- $ref: '#/components/parameters/GridpointForecastUnits'
responses:
'200':
$ref: '#/components/responses/GridpointHourlyForecast'
default:
$ref: '#/components/responses/Error'
tags:
- Gridpoints
/gridpoints/{wfo}/{x},{y}/stations:
parameters:
- $ref: '#/components/parameters/GridpointWFO'
- $ref: '#/components/parameters/GridpointX'
- $ref: '#/components/parameters/GridpointY'
- $ref: '#/components/parameters/Limit'
get:
description: Returns a list of observation stations usable for a given 2.5km grid area
operationId: gridpoint_stations
responses:
'200':
$ref: '#/components/responses/ObservationStationCollection'
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Gridpoints
components:
schemas:
GridpointHourlyForecastGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeature'
- type: object
properties:
properties:
$ref: '#/components/schemas/GridpointHourlyForecast'
Gridpoint12hForecast:
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
geometry:
$ref: '#/components/schemas/GeometryString'
units:
$ref: '#/components/schemas/GridpointForecastUnits'
forecastGenerator:
type: string
description: The internal generator class used to create the forecast text (used for NWS debugging).
generatedAt:
type: string
description: The time this forecast data was generated.
format: date-time
updateTime:
type: string
description: The last update time of the data this forecast was generated from.
format: date-time
validTimes:
$ref: '#/components/schemas/ISO8601Interval'
elevation:
$ref: '#/components/schemas/QuantitativeValue'
periods:
type: array
items:
$ref: '#/components/schemas/Gridpoint12hForecastPeriod'
description: An array of forecast periods.
description: A multi-day forecast for a 2.5km grid square.
additionalProperties: false
GridpointHourlyForecastPeriod:
type: object
properties:
number:
minimum: 1
type: integer
description: Sequential period number.
name:
type: string
description: 'A textual identifier for the period. This value will not be present for hourly forecasts.
'
examples:
- Tuesday Night
startTime:
type: string
description: The starting time that this forecast period is valid for.
format: date-time
endTime:
type: string
description: The ending time that this forecast period is valid for.
format: date-time
isDaytime:
type: boolean
description: Indicates whether this period is daytime or nighttime.
temperature:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: integer
description: 'High/low temperature for the period, depending on whether the period is day or night.
This property as an integer value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_temperature_qv" feature flag on the request.
'
temperatureUnit:
enum:
- F
- C
type: string
description: 'The unit of the temperature value (Fahrenheit or Celsius).
This property is deprecated. Future versions will indicate the unit within the quantitative value object for the temperature property. To make use of the future standard format now, set the "forecast_temperature_qv" feature flag on the request.
'
deprecated: true
temperatureTrend:
enum:
- rising
- falling
type:
- string
- 'null'
description: 'If not null, indicates a non-diurnal temperature trend for the period (either rising temperature overnight, or falling temperature during the day)
'
probabilityOfPrecipitation:
$ref: '#/components/schemas/QuantitativeValue'
description: Probability of precipitation for the period.
dewpoint:
$ref: '#/components/schemas/QuantitativeValue'
description: 'Dewpoint. Only provided in hourly forecasts.
'
relativeHumidity:
$ref: '#/components/schemas/QuantitativeValue'
description: 'Relative humidity. Only provided in hourly forecasts.
'
windSpeed:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: string
description: 'Wind speed for the period.
This property as an string value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_wind_speed_qv" feature flag on the request.
'
windGust:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: string
- type: 'null'
description: 'Peak wind gust for the period.
This property as an string value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_wind_speed_qv" feature flag on the request.
'
windDirection:
enum:
- N
- NNE
- NE
- ENE
- E
- ESE
- SE
- SSE
- S
- SSW
- SW
- WSW
- W
- WNW
- NW
- NNW
type: string
description: The prevailing direction of the wind for the period, using a 16-point compass.
icon:
type: string
description: A link to an icon representing the forecast summary.
format: uri
deprecated: true
shortForecast:
type: string
description: A brief textual forecast summary for the period.
detailedForecast:
type: string
description: A detailed textual forecast for the period.
description: 'An object containing forecast information for a specific time period (generally 12-hour or 1-hour).
'
additionalProperties: false
GridpointForecastUnits:
enum:
- us
- si
type: string
description: Denotes the units used in the textual portions of the forecast.
default: us
JsonLdContext:
anyOf:
- type: array
items: {}
- type: object
GeoJsonBoundingBox:
minItems: 4
type: array
items:
type: number
description: A GeoJSON bounding box. Please refer to IETF RFC 7946 for information on the GeoJSON format.
Gridpoint12hForecastPeriod:
type: object
properties:
number:
minimum: 1
type: integer
description: Sequential period number.
name:
type: string
description: 'A textual identifier for the period. This value will not be present for hourly forecasts.
'
examples:
- Tuesday Night
startTime:
type: string
description: The starting time that this forecast period is valid for.
format: date-time
endTime:
type: string
description: The ending time that this forecast period is valid for.
format: date-time
isDaytime:
type: boolean
description: Indicates whether this period is daytime or nighttime.
temperature:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: integer
description: 'High/low temperature for the period, depending on whether the period is day or night.
This property as an integer value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_temperature_qv" feature flag on the request.
'
temperatureUnit:
enum:
- F
- C
type: string
description: 'The unit of the temperature value (Fahrenheit or Celsius).
This property is deprecated. Future versions will indicate the unit within the quantitative value object for the temperature property. To make use of the future standard format now, set the "forecast_temperature_qv" feature flag on the request.
'
deprecated: true
temperatureTrend:
enum:
- rising
- falling
type:
- string
- 'null'
description: 'If not null, indicates a non-diurnal temperature trend for the period (either rising temperature overnight, or falling temperature during the day)
'
probabilityOfPrecipitation:
$ref: '#/components/schemas/QuantitativeValue'
description: Probability of precipitation for the period.
windSpeed:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: string
description: 'Wind speed for the period.
This property as an string value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_wind_speed_qv" feature flag on the request.
'
windGust:
oneOf:
- $ref: '#/components/schemas/QuantitativeValue'
- type: string
- type: 'null'
description: 'Peak wind gust for the period.
This property as an string value is deprecated. Future versions will express this value as a quantitative value object. To make use of the future standard format now, set the "forecast_wind_speed_qv" feature flag on the request.
'
windDirection:
enum:
- N
- NNE
- NE
- ENE
- E
- ESE
- SE
- SSE
- S
- SSW
- SW
- WSW
- W
- WNW
- NW
- NNW
type: string
description: The prevailing direction of the wind for the period, using a 16-point compass.
icon:
type: string
description: A link to an icon representing the forecast summary.
format: uri
deprecated: true
shortForecast:
type: string
description: A brief textual forecast summary for the period.
detailedForecast:
type: string
description: A detailed textual forecast for the period.
description: 'An object containing forecast information for a specific time period (generally 12-hour or 1-hour).
'
additionalProperties: false
GridpointGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeature'
- type: object
properties:
properties:
$ref: '#/components/schemas/Gridpoint'
GeoJsonGeometry:
oneOf:
- title: GeoJSON Point
required:
- type
- coordinates
type: object
properties:
type:
enum:
- Point
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonCoordinate'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON LineString
required:
- type
- coordinates
type: object
properties:
type:
enum:
- LineString
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonLineString'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON Polygon
required:
- type
- coordinates
type: object
properties:
type:
enum:
- Polygon
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonPolygon'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiPoint
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiPoint
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonCoordinate'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiLineString
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiLineString
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonLineString'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiPolygon
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiPolygon
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonPolygon'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- type: 'null'
description: A GeoJSON geometry object. Please refer to IETF RFC 7946 for information on the GeoJSON format.
GeoJsonLineString:
minItems: 2
type: array
items:
$ref: '#/components/schemas/GeoJsonCoordinate'
description: A GeoJSON line string. Please refer to IETF RFC 7946 for information on the GeoJSON format.
Gridpoint12hForecastGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeature'
- type: object
properties:
properties:
$ref: '#/components/schemas/Gridpoint12hForecast'
GeoJsonFeatureCollection:
required:
- type
- features
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
type:
enum:
- FeatureCollection
type: string
features:
type: array
items:
$ref: '#/components/schemas/GeoJsonFeature'
description: A GeoJSON feature collection. Please refer to IETF RFC 7946 for information on the GeoJSON format.
GridpointJsonLd:
$ref: '#/components/schemas/Gridpoint'
GeoJsonFeature:
required:
- type
- geometry
- properties
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
id:
type: string
format: uri
type:
enum:
- Feature
type: string
geometry:
$ref: '#/components/schemas/GeoJsonGeometry'
properties:
type: object
description: A GeoJSON feature. Please refer to IETF RFC 7946 for information on the GeoJSON format.
additionalProperties: false
GridpointHourlyForecast:
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
geometry:
$ref: '#/components/schemas/GeometryString'
units:
$ref: '#/components/schemas/GridpointForecastUnits'
forecastGenerator:
type: string
description: The internal generator class used to create the forecast text (used for NWS debugging).
generatedAt:
type: string
description: The time this forecast data was generated.
format: date-time
updateTime:
type: string
description: The last update time of the data this forecast was generated from.
format: date-time
validTimes:
$ref: '#/components/schemas/ISO8601Interval'
elevation:
$ref: '#/components/schemas/QuantitativeValue'
periods:
type: array
items:
$ref: '#/components/schemas/GridpointHourlyForecastPeriod'
description: An array of forecast periods.
description: An hourly forecast for a 2.5km grid square.
additionalProperties: false
ISO8601Interval:
oneOf:
- pattern: ^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:?\d{2}?)|NOW)\/(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:?\d{2}?)|NOW)$
type: string
examples:
- 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
- pattern: ^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:?\d{2}?)|NOW)\/P(\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
type: string
examples:
- 2007-03-01T13:00:00Z/P1Y2M10DT2H30M
- pattern: ^P(\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?\/(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:?\d{2}?)|NOW)$
type: string
examples:
- P1Y2M10DT2H30M/2008-05-11T15:30:00Z
description: "A time interval in ISO 8601 format. This can be one of:\n\n 1. Start and end time\n 2. Start time and duration\n 3. Duration and end time\nThe string \"NOW\" can also be used in place of a start/end time.\n"
NWSForecastOfficeId:
enum:
- AKQ
- ALY
- BGM
- BOX
- BTV
- BUF
- CAE
- CAR
- CHS
- CLE
- CTP
- GSP
- GYX
- ILM
- ILN
- LWX
- MHX
- OKX
- PBZ
- PHI
- RAH
- RLX
- RNK
- ABQ
- AMA
- BMX
- BRO
- CRP
- EPZ
- EWX
- FFC
- FWD
- HGX
- HUN
- JAN
- JAX
- KEY
- LCH
- LIX
- LUB
- LZK
- MAF
- MEG
- MFL
- MLB
- MOB
- MRX
- OHX
- OUN
- SHV
- SJT
- SJU
- TAE
- TBW
- TSA
- ABR
- APX
- ARX
- BIS
- BOU
- CYS
- DDC
- DLH
- DMX
- DTX
- DVN
- EAX
- FGF
- FSD
- GID
- GJT
- GLD
- GRB
- GRR
- ICT
- ILX
- IND
- IWX
- JKL
- LBF
- LMK
- LOT
- LSX
- MKX
- MPX
- MQT
- OAX
- PAH
- PUB
- RIW
- SGF
- TOP
- UNR
- BOI
- BYZ
- EKA
- FGZ
- GGW
- HNX
- LKN
- LOX
- MFR
- MSO
- MTR
- OTX
- PDT
- PIH
- PQR
- PSR
- REV
- SEW
- SGX
- SLC
- STO
- TFX
- TWC
- VEF
- AER
- AFC
- AFG
- AJK
- ALU
- GUM
- HPA
- HFO
- PPG
- PQE
- PQW
- STU
- NH1
- NH2
- ONA
- ONP
type: string
description: Three-letter identifier for a NWS office.
UnitOfMeasure:
pattern: ^((wmo|uc|wmoUnit|nwsUnit):)?.*$
type: string
description: 'A string denoting a unit of measure, expressed in the format "{unit}" or "{namespace}:{unit}".
Units with the namespace "wmo" or "wmoUnit" are defined in the World Meteorological Organization Codes Registry at http://codes.wmo.int/common/unit and should be canonically resolvable to http://codes.wmo.int/common/unit/{unit}.
Units with the namespace "nwsUnit" are currently custom and do not align to any standard.
Units with no namespace or the namespace "uc" are compliant with the Unified Code for Units of Measure syntax defined at https://unitsofmeasure.org/. This also aligns with recent versions of the Geographic Markup Language (GML) standard, the IWXXM standard, and OGC Observations and Measurements v2.0 (ISO/DIS 19156).
Namespaced units are considered deprecated. We will be aligning API to use the same standards as GML/IWXXM in the future.
'
Gridpoint12hForecastJsonLd:
allOf:
- $ref: '#/components/schemas/Gridpoint12hForecast'
- required:
- '@context'
- geometry
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
geometry:
$ref: '#/components/schemas/GeometryString'
GridpointQuantitativeValueLayer:
required:
- values
type: object
properties:
uom:
$ref: '#/components/schemas/UnitOfMeasure'
values:
type: array
items:
required:
- validTime
- value
type: object
properties:
validTime:
$ref: '#/components/schemas/ISO8601Interval'
value:
type:
- number
- 'null'
additionalProperties: false
description: 'A gridpoint layer consisting of quantitative values (numeric values with associated units of measure).
'
PaginationInfo:
required:
- next
type: object
properties:
next:
type: string
description: A link to the next page of records
format: uri
description: Links for retrieving more data from paged data sets
additionalProperties: false
ObservationStationCollectionJsonLd:
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
'@graph':
type: array
items:
$ref: '#/components/schemas/ObservationStation'
observationStations:
type: array
items:
type: string
format: uri
pagination:
$ref: '#/components/schemas/PaginationInfo'
additionalProperties: false
ObservationStationCollectionGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeatureCollection'
- type: object
properties:
features:
type: array
items:
type: object
properties:
properties:
$ref: '#/components/schemas/ObservationStation'
observationStations:
type: array
items:
type: string
format: uri
pagination:
$ref: '#/components/schemas/PaginationInfo'
GridpointHourlyForecastJsonLd:
allOf:
- $ref: '#/components/schemas/GridpointHourlyForecast'
- required:
- '@context'
- geometry
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
geometry:
$ref: '#/components/schemas/GeometryString'
QuantitativeValue:
type: object
properties:
value:
type:
- number
- 'null'
description: A measured value
maxValue:
type: number
description: The maximum value of a range of measured values
minValue:
type: number
description: The minimum value of a range of measured values
unitCode:
$ref: '#/components/schemas/UnitOfMeasure'
qualityControl:
enum:
- Z
- C
- S
- V
- X
- Q
- G
- B
- T
type: string
description: 'For values in observation records, the quality control flag from the MADIS system. The definitions of these flags can be found at https://madis.ncep.noaa.gov/madis_sfc_qc_notes.shtml
'
description: 'A structured value representing a measurement and its unit of measure. This object is a slightly modified version of the schema.org definition at https://schema.org/QuantitativeValue
'
additionalProperties: false
Gridpoint:
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
geometry:
$ref: '#/components/schemas/GeometryString'
'@id':
type: string
format: uri
'@type':
enum:
- wx:Gridpoint
type: string
updateTime:
type: string
format: date-time
validTimes:
$ref: '#/components/schemas/ISO8601Interval'
elevation:
$ref: '#/components/schemas/QuantitativeValue'
forecastOffice:
type: string
format: uri
gridId:
type: string
gridX:
minimum: 0
type: integer
gridY:
minimum: 0
type: integer
weather:
required:
- values
type: object
properties:
values:
type: array
items:
required:
- validTime
- value
type: object
properties:
validTime:
$ref: '#/components/schemas/ISO8601Interval'
value:
type: array
items:
required:
- coverage
- weather
- intensity
- visibility
- attributes
type: object
properties:
coverage:
enum:
- areas
- brief
- chance
- definite
- few
- frequent
- intermittent
- isolated
- likely
- numerous
- occasional
- patchy
- periods
- scattered
- slight_chance
- widespread
type:
- string
- 'null'
weather:
enum:
- blowing_dust
- blowing_sand
- blowing_snow
- drizzle
- fog
- freezing_fog
- freezing_drizzle
- freezing_rain
- freezing_spray
- frost
- hail
- haze
- ice_crystals
- ice_fog
- rain
- rain_showers
- sleet
- smoke
- snow
- snow_showers
- thunderstorms
- volcanic_ash
- water_spouts
type:
- string
- 'null'
intensity:
enum:
- very_light
- light
- moderate
- heavy
type:
- string
- 'null'
visibility:
$ref: '#/components/schemas/QuantitativeValue'
attributes:
type: array
items:
enum:
- damaging_wind
- dry_thunderstorms
- flooding
- gusty_wind
- heavy_rain
- large_hail
- small_hail
- tornadoes
type: string
description: A value object representing expected weather phenomena.
additionalProperties: false
additionalProperties: false
hazards:
required:
- values
type: object
properties:
values:
type: array
items:
required:
- validTime
- value
type: object
properties:
validTime:
$ref: '#/components/schemas/ISO8601Interval'
value:
type: array
items:
required:
- phenomenon
- significance
- event_number
type: object
properties:
phenomenon:
pattern: ^\w{2}$
type: string
description: 'Hazard code. This value will correspond to a P-VTEC phenomenon code as defined in NWS Directive 10-1703.
'
significance:
pattern: ^\w$
type: string
description: 'Significance code. This value will correspond to a P-VTEC significance code as defined in NWS Directive 10-1703.
This will most frequently be "A" for a watch or "Y" for an advisory.
'
event_number:
type:
- integer
- 'null'
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/noaa-gov/refs/heads/main/openapi/noaa-gov-gridpoints-api-openapi.yml