API Reference

All forecast functions are accessed via an instance of the WxAPI class:

import nwswx
nws = nwswx.WxAPI('test@email.com')

Most functions accept a return_format parameter, which is expected to be a Content-Type string or an attribute on the friendlier, easier-to-read helper object nwswx.formats.

Format

Content-Type

Format Helper

GeoJSON

application/geo+json

nwswx.formats.GeoJSON

JSON-LD

application/ld+json

nwswx.formats.JSONLD

DWML

application/vnd.noaa.dwml+xml

nwswx.formats.DWML

OXML

application/vnd.noaa.obs+xml

nwswx.formats.OXML

CAP

application/cap+xml

nwswx.formats.CAP

ATOM

application/atom+xml

nwswx.formats.ATOM

The examples in this documentation will use the nwswx.formats helper.

WxAPI Class

class nwswx.WxAPI(useragent_id, *, api_host=None)

WxAPI class that acts as the central object for interfacing with the NWS Weather Forecast API.

Parameters:

  • useragent_id – identifier to send in useragent, generally an email address

  • api_host – optional, NWS Weather Forecast API host, defaults to api.weather.gov

active_alerts(params=None, *, return_format=None)

Retrieves a list of active alerts, optionally filtered by parameters

Parameters:

  • params – a dict of parameters

  • return_format – optional, one of JSONLD or ATOM

Filter Parameters:

This list is included verbatim from the NWS Weather Forecast API documentation.

  • status - event status (alert, update, cancel)

  • type - event type (list forthcoming)

  • zone_type - zone type (land or marine)

  • point - point (latitude,longitude)

  • region - region code (list forthcoming)

  • state - state/marine code (list forthcoming)

  • zone - zone ID (forecast or county, list forthcoming)

  • urgency - urgency (expected, immediate)

  • severity - severity (minor, moderate, severe)

  • certainty - certainty (likely, observed)

  • limit - limit (an integer)

Examples:

import nwswx
nws = nwswx.WxAPI('test@email.com')
nws.active_alerts({'point': '39.0693,-94.6716'})
nws.active_alerts({'point': '39.0693,-94.6716'},
                  return_format=nwswx.formats.JSONLD)
Returns:

If format is JSONLD, a dict of alerts. Otherwise, a string containing alerts in ATOM format.

alert(alert_id, *, return_format=None)

Retrieves details for a specific alert

Parameters:

  • alert_id – an alert ID provided by another endpoint, eg. NWS-IDP-PROD-2202530-2064731

  • return_format – optional, one of JSONLD, CAP, or GeoJSON

Examples:

import nwswx
nws = nwswx.WxAPI('test@email.com')
nws.alert('NWS-IDP-PROD-2202530-2064731')
nws.alert('NWS-IDP-PROD-2202530-2064731',
          return_format=nwswx.formats.JSONLD)
Returns:

If format is JSONLD, a dict containing the alert details. If format is CAP, a string containing the alert in CAP format. Otherwise, a string containing the alert in GeoJSON format.

Note

GeoJSON is a supported format for this endpoint despite the API documentation saying otherwise.

alerts(params=None, *, return_format=None)

Retrieves a list of alerts, optionally filtered by parameters

Parameters:

  • params – a dict of parameters

  • return_format – optional, one of JSONLD or ATOM

Filter Parameters:

This list is included verbatim from the NWS Weather Forecast API documentation.

  • active - active alerts (1 or 0)

  • start - start time (ISO8601DateTime)

  • end - end time (ISO8601DateTime)

  • status - event status (alert, update, cancel)

  • type - event type (list forthcoming)

  • zone_type - zone type (land or marine)

  • point - point (latitude,longitude)

  • region - region code (list forthcoming)

  • state - state/marine code (list forthcoming)

  • zone - zone ID (forecast or county, list forthcoming)

  • urgency - urgency (expected, immediate)

  • severity - severity (minor, moderate, severe)

  • certainty - certainty (likely, observed)

  • limit - limit (an integer)

Examples:

import nwswx
nws = nwswx.WxAPI('test@email.com')
nws.alerts({'point': '39.0693,-94.6716'})
nws.alerts({'point': '39.0693,-94.6716'},
           return_format=nwswx.formats.JSONLD)
Returns:

If format is JSONLD, a dict of alerts. Otherwise, a string containing alerts in ATOM format.

gridpoint(wfo, grid_x, grid_y, *, return_format=None)

Retrieves raw gridded data

Parameters:

  • wfo – a Weather Office ID

  • grid_x – the grid x coordinate

  • grid_y – the grid y coordinate

  • return_format – optional, one of GeoJSON, JSONLD

Gridded Data Dict Keys:

  • @context

  • @id

  • @type

  • apparentTemperature

  • atmosphericDispersionIndex

  • ceilingHeight

  • davisStabilityIndex

  • dewpoint

  • dispersionIndex

  • elevation

  • forecastOffice

  • geometry

  • grasslandFireDangerIndex

  • gridId

  • gridX

  • gridY

  • hainesIndex

  • hazards

  • heatIndex

  • iceAccumulation

  • lightningActivityLevel

  • lowVisibilityOccurrenceRiskIndex

  • maxTemperature

  • minTemperature

  • mixingHeight

  • potentialOf15mphWinds

  • potentialOf20mphWindGusts

  • potentialOf25mphWinds

  • potentialOf30mphWindGusts

  • potentialOf35mphWinds

  • potentialOf40mphWindGusts

  • potentialOf45mphWinds

  • potentialOf50mphWindGusts

  • potentialOf60mphWindGusts

  • pressure

  • primarySwellDirection

  • primarySwellHeight

  • probabilityOfHurricaneWinds

  • probabilityOfPrecipitation

  • probabilityOfThunder

  • probabilityOfTropicalStormWinds

  • quantitativePrecipitation

  • redFlagThreatIndex

  • relativeHumidity

  • secondarySwellDirection

  • secondarySwellHeight

  • skyCover

  • snowLevel

  • snowfallAmount

  • stability

  • temperature

  • transportWindDirection

  • transportWindSpeed

  • twentyFootWindDirection

  • twentyFootWindSpeed

  • updateTime

  • validTimes

  • visibility

  • waveDirection

  • waveHeight

  • wavePeriod

  • wavePeriod2

  • weather

  • windChill

  • windDirection

  • windGust

  • windSpeed

  • windWaveHeight

Returns:

If format is JSONLD, a dict of gridded data. Otherwise, a string of gridded data in GeoJSON format.

point(lat, lon, *, return_format=None)

Retrieves metadata about a point

Parameters:

  • lat – latitude, eg. 39.0693

  • lon – longitude, eg. -94.6716

  • return_format – optional, one of GeoJSON, JSONLD

Point Metadata Dict Keys:

  • @context

  • @id

  • @type

  • county

  • cwa

  • fireWeatherZone

  • forecast

  • forecastGridData

  • forecastHourly

  • forecastOffice

  • forecastZone

  • geometry

  • gridX

  • gridY

  • observationStations

  • radarStation

  • relativeLocation

  • timeZone

Returns:

If format is JSONLD, a dict of metadata. Otherwise, a string of metadata in GeoJSON format.

point_forecast(lat, lon, *, return_format=None)

Retrieves forecast data for a point

Parameters:

  • lat – latitude, eg. 39.0693

  • lon – longitude, eg. -94.6716

  • return_format – optional, one of GeoJSON, JSONLD, DWML

Forecast Dict Keys:

  • @`context`

  • elevation

  • forecastGenerator

  • generatedAt

  • geometry

  • periods - a dict of periods (see period keys below)

  • units

  • updateTime

  • updated

  • validTimes

Period Dict Keys:

  • number - sequence number

  • name - short name for period, eg. ‘Today’, ‘Monday Night’

  • startTime

  • endTime

  • isDaytime - boolean

  • temperature

  • temperatureUnit - ‘F’ or ‘C’

  • temperatureTrend

  • windSpeed

  • windDirection

  • icon - URL to icon image

  • shortForecast - eg. ‘Mostly Clear’

  • detailedForecast

Returns:

If format is JSONLD, a dict containing forecast data. Otherwise, a string containing forecast data in GeoJSON or DWML format.

point_hourly_forecast(lat, lon, *, return_format=None)

Retrieves hourly forecast data for a point

Parameters:

  • lat – latitude, eg. 39.0693

  • lon – longitude, eg. -94.6716

  • return_format – optional, one of GeoJSON, JSONLD

Forecast Dict Keys:

  • @`context`

  • elevation

  • forecastGenerator

  • generatedAt

  • geometry

  • periods - a dict of periods (see period keys below)

  • units

  • updateTime

  • updated

  • validTimes

Period Dict Keys:

  • number - sequence number

  • name - short name for period, eg. ‘Today’, ‘Monday Night’

  • startTime

  • endTime

  • isDaytime - boolean

  • temperature

  • temperatureUnit - ‘F’ or ‘C’

  • temperatureTrend

  • windSpeed

  • windDirection

  • icon - URL to icon image

  • shortForecast - eg. ‘Mostly Clear’

  • detailedForecast

Returns:

If format is JSONLD, a list of dicts containing forecast data. Otherwise, a string containing forecast data in GeoJSON format.

Note

Very long-term forecast periods do not contain the full set of keys listed above.

point_stations(lat, lon, *, return_format=None)

Retrieves stations nearest to a point in order of distance

Parameters:

  • lat – latitude, eg. 39.0693

  • lon – longitude, eg. -94.6716

  • return_format – optional, one of GeoJSON or JSONLD

Returns:

If format is JSONLD, a list of station URLs. Otherwise, a string containing forecast data in GeoJSON format.