Nws::Api::Alerts
This gem provides a wrapper around the NWS Weather Alerts API which provides the ability to fetch and filter weather alert information throughout the United States. While subject to rate-limiting for the sake of abuse prevention, the NWS API is entirely free to use by anyone, which means that this gem will work out of the box without any configuration.
Installation
Add this line to your application's Gemfile:
gem 'nws-api-alerts'
And then execute:
$ bundle
Or install it yourself as:
$ gem install nws-api-alerts
Usage
You can get back a list of every alert currently in force throughout the country with the following code snippet:
client = Nws::Api::Alerts::Client.new
alerts = client.get_alerts
The plan is to introduce parameters for filtering the list of returned alerts in a forthcoming release. For now, the list returned represents every currently active alert in the country. These alerts are returned inside of an AlertSet
object.
An AlertSet
implements the Enumerable
interface, which makes methods such as each
, map
, and select
available on it. It also implements a handful of methods that allow it to behave somewhat like an array. For instance, you can call first
and last
on an AlertSet
, in addition to dereferencing a particular Alert
by it's index. Here's some examples of the array methods in action:
client = Nws::Api::Alerts::Client.new
alerts = client.get_alerts
first_alert = alerts.first # => Nws::Api::Alerts::Alert
last_alert = alerts.last # => Nws::Api::Alerts::Alert
nth_alert = alerts[2] # => Nws::Api::Alerts::Alert
Here are some examples of enumerating through an AlertSet
:
alerts = client.get_alerts
nws_ids = alerts.map{|alert| alert.nws_id } # => Array
expirations = alerts.map(&:expires) # => Array
expired = alerts.select{|alert| Time.parse(alert.expires) < Time.now } # => Array
Filtering Alerts
An AlertSet
can also be filtered based upon the severity, urgency, or certainty of the Alert, or any combination thereof. You can also choose to filter out Alerts that do not provide geometry data for mapping purposes. Examples of these are below:
alerts = client.get_alerts
severe_severity = alerts.severe # => Nws::Api::Alerts::AlertSet
moderate_severity = alerts.moderate # => Nws::Api::Alerts::AlertSet
immediately_urgent = alerts.immediate # => Nws::Api::Alerts::AlertSet
expected_urgency = alerts.expected # => Nws::Api::Alerts::AlertSet
observed_certainty = alerts.observed # => Nws::Api::Alerts::AlertSet
possible_certainty = alerts.possible # => Nws::Api::Alerts::AlertSet
# You can also chain together filters in any order, bearing in mind that filters within a given category are mutually exclusive.
severe_immediate_observed_alerts = alerts.severe.immediate.observed # => Nws::Api::Alerts::AlertSet
The filters available for each "category": severity, urgency, and certainty, are as follows:
- Severity:
severe
,moderate
,minor
,unknown_severity
- Urgency:
immediate
,expected
,future
,unknown_urgency
- Certainty:
observed
,possible
,likely
,unknown_certainty
To filter the AlertSet
based upon whether or not geographic map data is available, you can call with_geography
and without_geography
respectively.
Alert Data
An AlertSet
is ultimately a collection of Alert
objects. An Alert
instance currently doesn't do much more than store the attributes of a specific weather alert. The attributes/methods available on an Alert
are as follows:
nws_id
: The unique identifier for this alert as assigned by the National Weather Service.onset
: A timestamp referring to the time when the conditions described in the alert first began.expires
: A timestamp referring to when the alert will no longer be in effect.message_type
: Mostly used internally, currently will only ever be 'Alert'severity
: A string describing the "severity" of the Alert, "Severe", "Moderate", "Minor", or "Unknown"certainty
: A string describing the "certainty" of the Alert, "Observed", "Possible", "Likely", or "Unknown"urgency
: A string describing the "urgency" of the Alert, "Immediate", "Expected", "Future", or "Unknown"instruction
: A string describing the conditions of the alert and action recommended by local authorities for proceeding safely.geometry
: An array of latitude, longitude pairs that describe a polygon over a geographic area. Used for displaying alert information on a map.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Lojistic/NwsAlerts-gem.
License
The gem is available as open source under the terms of the MIT License.