nws-api-alerts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b331739dcd09b5ccde46291bca7f0dc820d1ac7be8f2f011344b9392c3c0fc2d
+  data.tar.gz: baa5f5f84d7481634a23608b1861ce7dfef43fc782394aa9e83f71b1968751cb
+SHA512:
+  metadata.gz: 4d87621dd3ec649385cca092fa7b1ad0fdfa2f15ca35b42340fd318690e27fd39e538710059e243d71a863916f9ec7bed123c4838fdc9436c7016ec63a314b6f
+  data.tar.gz: dc62383232da06a465fae3a2deb718e0c2254501444a1c6f228d14d760d1b5096e4b31a436479fc8f2e7e88f441e8932904ab9178185f6f293e4b6df2f613e32

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.17.3

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in nws-api-alerts.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: .
+  specs:
+    nws-api-alerts (0.1.0)
+      activesupport
+      httparty
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.0.0)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.1, >= 2.1.8)
+    concurrent-ruby (1.1.5)
+    diff-lcs (1.3)
+    httparty (0.17.0)
+      mime-types (~> 3.0)
+      multi_xml (>= 0.5.2)
+    i18n (1.6.0)
+      concurrent-ruby (~> 1.0)
+    mime-types (3.2.2)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2019.0331)
+    minitest (5.11.3)
+    multi_xml (0.6.0)
+    rake (10.5.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    zeitwerk (2.1.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17)
+  nws-api-alerts!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.17.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Steve Lewis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# Nws::Api::Alerts
+
+This gem provides a wrapper around the [NWS Weather Alerts API](https://www.weather.gov/documentation/services-web-alerts) 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:
+
+```ruby
+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:
+
+```ruby
+  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:
+
+```ruby
+  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`:
+
+```ruby
+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:
+
+```ruby
+  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](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "nws/api/alerts"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/nws/api/alerts.rb

@@ -0,0 +1,12 @@
+require "nws/api/alerts/version"
+require "nws/api/alerts/alert_set"
+require "nws/api/alerts/alert"
+require "nws/api/alerts/client"
+
+module Nws
+  module Api
+    module Alerts
+      class Error < StandardError; end
+    end
+  end
+end

data/lib/nws/api/alerts/alert.rb

@@ -0,0 +1,58 @@
+# The Alert class encapsulates all of the important information for a given weather alert
+
+
+module Nws
+  module Api
+    module Alerts
+      class Alert
+
+        attr_reader :nws_id, :onset, :expires, :message_type, :severity, :certainty, :urgency, :instruction, :geometry
+
+        def self.from_api_response(client, parsed_response, alerts = nil)
+          alerts ||= AlertSet.new
+          return alerts unless parsed_response['features']
+          parsed_response['features'].each do |alert_data|
+            alerts << self.new(alert_data)
+          end
+
+          if parsed_response['pagination'] && parsed_response['pagination']['next']
+            next_uri = URI.parse(parsed_response['pagination']['next'])
+            next_path = next_uri.to_s.gsub("#{next_uri.scheme}://#{next_uri.host}", '')
+
+            self.from_api_response(client, client.fetch_raw_alerts(path: next_path), alerts)
+          end
+
+          return alerts
+        end
+
+
+        def initialize(data)
+
+          if data['geometry']
+            @geometry    = data['geometry']['coordinates'].first
+          end
+
+          properties     = data['properties']
+          @nws_id        = properties['id']
+          @onset         = properties['onset']
+          @expires       = properties['expires']
+          @message_type  = properties['messageType']
+          @severity      = properties['severity']
+          @certainty     = properties['certainty']
+          @urgency       = properties['urgency']
+          @instruction   = properties['instruction']
+        end
+
+        def attributes
+          hsh = {}
+          # Give back a hash of attributes suitable for persistance to a DB, for instance.
+          instance_variables.map(&:to_s).map{|iv| iv.gsub('@', '')}.map{|att| hsh[att.to_sym] = self.send(att.to_sym)}
+
+          hsh
+        end
+
+
+      end
+    end
+  end
+end

data/lib/nws/api/alerts/alert_set.rb

@@ -0,0 +1,117 @@
+# The AlertSet class implements Enumerable, (each, map, select, etc), and
+# provides convenience methods for filtering a collection of Alerts
+
+module Nws
+  module Api
+    module Alerts
+      class AlertSet
+        include Enumerable
+        attr_reader :alerts
+
+        def initialize(alerts = nil)
+          @alerts = alerts.is_a?(Array) ? alerts : []
+        end
+
+        def <<(alert)
+          @alerts << alert
+        end
+
+        def each(&block)
+          alerts.each(&block)
+          self
+        end
+
+        alias length count
+        alias size count
+
+        def [](idx)
+          alerts[idx]
+        end
+
+        def first
+          alerts.first
+        end
+
+        def last
+          alerts.last
+        end
+
+        def severe
+          severity_filter_for('Severe')
+        end
+
+        def minor
+          severity_filter_for('Minor')
+        end
+
+        def moderate
+          severity_filter_for('Moderate')
+        end
+
+        def unknown_severity
+         severity_filter_for('Unknown')
+        end
+
+        def past
+          urgency_filter_for('Past')
+        end
+
+        def immediate
+          urgency_filter_for('Immediate')
+        end
+
+        def expected
+          urgency_filter_for('Expected')
+        end
+
+        def future
+          urgency_filter_for('Future')
+        end
+
+        def unknown_urgency
+          urgency_filter_for('Unknown')
+        end
+
+        def observed
+          certainty_filter_for('Observed')
+        end
+
+        def possible
+          certainty_filter_for('Possible')
+        end
+
+        def likely
+          certainty_filter_for('Likely')
+        end
+
+        def unknown_certainty
+          certainty_filter_for('Unknown')
+        end
+
+        def with_geometry
+          return self.class.new(self.select{|alert| alert.geometry })
+        end
+
+        def without_geometry
+          return self.class.new(self.reject{|alert| alert.geometry })
+        end
+
+        private
+
+        def severity_filter_for(severity)
+          return self.class.new(self.select{|alert| alert.severity == severity })
+        end
+
+        def urgency_filter_for(urgency)
+          return self.class.new(self.select{|alert| alert.urgency == urgency })
+        end
+
+        def certainty_filter_for(certainty)
+          return self.class.new(self.select{|alert| alert.certainty == certainty })
+        end
+
+      end
+    end
+  end
+end
+

data/lib/nws/api/alerts/client.rb

@@ -0,0 +1,35 @@
+require 'httparty'
+
+module Nws
+  module Api
+    module Alerts
+      class Client
+        include HTTParty
+        base_uri "https://api.weather.gov"
+
+        def get_alerts(message_type: 'alert', status: 'actual', urgency: nil, severity: nil, certainty: nil, limit: nil)
+          parsed     = fetch_raw_alerts(message_type: message_type,
+                                        status: status,
+                                        urgency: urgency,
+                                        severity: severity,
+                                        certainty: certainty,
+                                        limit: limit)
+          alerts     = Alert.from_api_response(self, parsed)
+
+          return alerts
+        end
+
+        def fetch_raw_alerts(message_type: 'alert', status: 'actual', urgency: nil, severity: nil, certainty: nil, limit: nil, path: nil)
+          path ||= "/alerts?message_type=#{message_type}&status=#{status}"
+          path << "&urgency=#{urgency}" if urgency
+          path << "&severity=#{severity}" if severity
+          path << "&certainty=#{certainty}" if certainty
+          patch << "&limit=#{limit}" if limit
+          raw_result = self.class.get(path)
+          JSON.parse(raw_result)
+        end
+
+      end
+    end
+  end
+end

data/lib/nws/api/alerts/version.rb

@@ -0,0 +1,7 @@
+module Nws
+  module Api
+    module Alerts
+      VERSION = "0.1.0"
+    end
+  end
+end

data/nws-api-alerts.gemspec

@@ -0,0 +1,37 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "nws/api/alerts/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "nws-api-alerts"
+  spec.version       = Nws::Api::Alerts::VERSION
+  spec.authors       = ["Lojistic Dev Team"]
+  spec.email         = ["dev@lojistic.com"]
+
+  spec.summary       = %q{ Simple wrapper around the NWS Alert API }
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httparty"
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/quick-test.rb

@@ -0,0 +1,8 @@
+require "bundler/setup"
+require "nws/api/alerts"
+
+client = Nws::Api::Alerts::Client.new
+alerts  =  client.get_alerts
+
+
+

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: nws-api-alerts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lojistic Dev Team
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- dev@lojistic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/nws/api/alerts.rb
+- lib/nws/api/alerts/alert.rb
+- lib/nws/api/alerts/alert_set.rb
+- lib/nws/api/alerts/client.rb
+- lib/nws/api/alerts/version.rb
+- nws-api-alerts.gemspec
+- quick-test.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Simple wrapper around the NWS Alert API
+test_files: []