NWSAPy User API Reference
- class nwsapy.NWSAPy
- get_active_alerts(**kwargs)
Returns an active alerts object containing all active alerts. This object is comprised of IndividualAlerts.
Endpoint:/alerts/activeDescription: Returns all currently active alerts.- Parameters
area (str or list[str]) – The land or marine region where the alert is in. Either a 2 letter abbreviation (i.e. “FL”) or the full state name (i.e. “Florida”) Data Validation Table
certainty (str or list[str]) – The certainty of the alert. Data Validation Table
event (str or list[str]) – The type of alert (i.e. Severe Thunderstorm Warning, etc). Data Validation Table
limit (int) – The number of alerts to return at most. Will only retrieve the first n alerts.
message_type (str or list[str]) – Data Validation Table
point (list[float]) – A tuple or list containing a latitude and longitude pair.
region (str or list[str]) – A marine region where the alert resides. Data Validation Table
region_type (str) – The type of region where the alert resides. Data Validation Table
severity (str or list[str]) – The severity level of the alert. Data Validation Table
status (str or list[str]) – The status of the alert. Data Validation Table
urgency (str or list[str]) – The urgency of the alert. Data Validation Table
zone (str or list[str]) – The NWS zone of the alert. Note this has no validation checks, so a 404 error can occur.
- Returns
An object containing information from the
alerts/activeendpoint.- Return type
nwsapy.endpoints.alerts.ActiveAlert
- get_alert_by_area(area)
Retrieves alerts by a given area (state or marine).
Endpoint:alerts/active/area/{area}Description: Retrieves alerts for the given area (state or marine area)- Parameters
area (str) – 2 letter state abbreviation or full state name (i.e. Florida) Data Validation Table
- Returns
An object containing information about the specified alert.
- Return type
- get_alert_by_id(id)
Retrieves an alert by ID from the
alerts/active/{id}endpoint.Endpoint:alerts/active/{id}Description: Returns a specific alert- Parameters
id (string) – The ID of an alert.
- Returns
An object containing information about the specified alert.
- Return type
- get_alert_by_marine_region(marine_region)
Retrieves alerts by a specific marine region.
Endpoint:alerts/active/region/{regionId}Description: Returns active alerts for the given marine region- Parameters
marine_region (str) – A 2 letter marine region. Data Validation Table
- Returns
An object containing information about alerts in the specified marine region.
- Return type
nwsapy.endpoints.alerts.AlertByRegion
- get_alert_by_zone(zone)
Retrieves alerts by the 6 character NWS zone or county. Note that this method does not have any data validation checks as of v1.0.0.
Endpoint:/alerts/active/zone/{zoneId}Description: Returns active alerts for the given NWS public zone or county- Parameters
zone (str) – A 6 character NWS zone or county (ex: BAC222)
- Returns
An object containing information about the NWS public zone or county
- Return type
- get_alert_count()
Gets the number of land, marine, and total active alerts. Also provides a dictionary of the number of alerts by areas (states), zones, and marine regions.
Endpoint:
/alerts/active/countDescription: Returns info on the number of active alerts.- Returns
An object containing the number of alerts for certain parameters.
- Return type
- get_alert_types()
Retrieves a list of the alert types that the National Weather Service puts out.
Endpoint:
/alerts/typesDescription: Returns a list of alert types.Note
NWSAPy has this built in as a data validation table. To retrieve:
from nwsapy.services.validation import valid_products products = valid_products()
Using this will allow for your code to be run quicker, as it retrieves a list compared to a NWS API request.
- Returns
An object containing information about the alert types.
- Return type
nwsapy.endpoints.alert.AlertType
- get_alerts(**kwargs)
Returns an alerts object with the previous 500 alerts. Note that this is the maximum value and also the default.
Endpoint:/alertsDescription: Returns all alerts.- Parameters
area (str or list[str]) – The land or marine region where the alert is in. Either a 2 letter abbreviation (i.e. “FL”) or the full state name (i.e. “Florida”) Data Validation Table
certainty (str or list[str]) – The certainty of the alert. Data Validation Table
event (str or list[str]) – The type of alert (i.e. Severe Thunderstorm Warning, etc). Data Validation Table
limit (int) – The number of alerts to return at most. Will only retrieve the first n alerts.
message_type (str or list[str]) – Data Validation Table
point (list[float]) – A tuple or list containing a latitude and longitude pair.
region (str or list[str]) – A marine region where the alert resides. Data Validation Table
region_type (str) – The type of region where the alert resides. Data Validation Table
severity (str or list[str]) – The severity level of the alert. Data Validation Table
status (str or list[str]) – The status of the alert. Data Validation Table
urgency (str or list[str]) – The urgency of the alert. Data Validation Table
zone (str or list[str]) – The NWS zone of the alert. Note this has no validation checks, so a 404 error can occur.
- Returns
An object containing information from the
alerts/activeendpoint.- Return type
nwsapy.endpoints.alerts.ActiveAlert
- get_glossary()
Makes a request to the /glossary endpoint in the API and returns a glossary object containing information about the terms listed in the glossary.
Endpoint:/glossaryDescription: Glossary terms- Returns
An object containing information from the /glossary endpoint.
- Return type
- get_point(lat, lon)
Makes a request to the /point endpoint in the API and returns a point object containing metadata about the given lat/lon.
Endpoint:/points/{point}Description: Returns metadata about a given latitude/longitude point.- Returns
An object containing information from the /point endpoint.
- Return type
- make_request(url)
Makes a request to the NWS API with a given URL. This method allows you to have full control over the data without the functionality and organization of any NWSAPy
get_*methods.Note
This does not have any kind of data validation checks and does not handle any errors on behalf of you.
- Parameters
url (string) – The URL to make a request to the NWS API.
- Returns
A response object containing the request for the query.
- Return type
request.Response
- ping_server()
Pings the server for integrity and/or testing.
- Returns
ServerPing object
- Return type
nwsapy.entrypoint.ServerPing
- set_user_agent(app_name, contact)
Sets the User-Agent in header for requests. This should be unique to your application.
- From the NWS API documentation:
“A User Agent is required to identify your application. This string can be anything, and the more unique to your application the less likely it will be affected by a security event. If you include contact information (website or email), we can contact you if your string is associated to a security event.”
Link: https://www.weather.gov/documentation/services-web-api#/
- Parameters
app_name (str) – The name of your application.
contact (str) – The contact email/website. This is needed for API authentication.