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 |
|
|
JSON-LD |
|
|
DWML |
|
|
OXML |
|
|
CAP |
|
|
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
orATOM
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
, orGeoJSON
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 isCAP
, 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
orATOM
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 numbername
- short name for period, eg. ‘Today’, ‘Monday Night’startTime
endTime
isDaytime
- booleantemperature
temperatureUnit
- ‘F’ or ‘C’temperatureTrend
windSpeed
windDirection
icon
- URL to icon imageshortForecast
- 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 numbername
- short name for period, eg. ‘Today’, ‘Monday Night’startTime
endTime
isDaytime
- booleantemperature
temperatureUnit
- ‘F’ or ‘C’temperatureTrend
windSpeed
windDirection
icon
- URL to icon imageshortForecast
- 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
orJSONLD
- Returns:
If format is
JSONLD
, a list of station URLs. Otherwise, a string containing forecast data in GeoJSON format.