weese 1.0.0

data/lib/weese/deserialize.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# Extension to String for deserializing JSON
+class String
+  #
+  # Convert this {String} into a JSON Hash
+  #
+  # @raise [WeeseError] If JSON parse fails
+  #
+  # @return [Hash] Hash representing the given JSON
+  #
+  def deserialize
+    JSON.parse(self)
+  rescue JSON::ParserError => e
+    raise WeeseError, e.to_s
+  end
+end

data/lib/weese/location.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Weese
+  # Classes relating to locations in latitude and longtidue, and radiuses in meters.
+  module Location
+    # A radius in meters at a {Coordinates}
+    class RadiusAtCoordinates
+      # @return [Numeric] Radius in meters around coordinates
+      attr_accessor :radius
+      # @return [Coordinates] A latitude and longitude
+      attr_accessor :coordinates
+
+      #
+      # Create a Radius at a Coordinates
+      #
+      # @param [Numeric] radius Distance in meters to check from the given coordinates
+      # @param [Coordinates] coordinates Latitude and Longitude to
+      #
+      def initialize(radius, coordinates)
+        @radius = radius
+        @coordinates = coordinates
+      end
+
+      #
+      # Converts this object to a hash
+      #
+      # @return [Hash] Hash containing radius, latitude and longitude
+      #
+      def to_h
+        {
+          radius: radius,
+          latitude: coordinates.latitude,
+          longitude: coordinates.longitude
+        }
+      end
+    end
+
+    # A latitude and longitude
+    class Coordinates
+      # @return [Numeric] A latitude
+      attr_accessor :latitude
+      # @return [Numeric] A longitude
+      attr_accessor :longitude
+
+      #
+      # Creates a latitude and longitude pair
+      #
+      # @param [Numeric] latitude A latitude
+      # @param [Numeric] longitude A longitude
+      #
+      def initialize(latitude, longitude)
+        @latitude = latitude
+        @longitude = longitude
+      end
+    end
+  end
+end

data/lib/weese/rail/line.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Weese
+  module Rail
+    # WMATA Line Codes and Line helper methods
+    module Line
+      RD = 'RD' # Red line code
+      BL = 'BL' # Blue line code
+      YL = 'YL' # Yellow line code
+      OR = 'OR' # Orange line code
+      GR = 'GR' # Green line code
+      SV = 'SV' # Silver line code
+      YLRP = 'YLRP' # Yellow Line Rush Plus line code. Deprecated.
+
+      # Extensions to String relating to Lines
+      class String
+        #
+        # Checks if this {String} is a Line code
+        #
+        # @return [bool] If the current string is a Line Code
+        #
+        def line?
+          case self
+          when Line::RD, Line::BL, Line::YL, Line::YL, Line::OR, Line::GR, Line::SV, Line::YLRP
+            true
+          else
+            false
+          end
+        end
+
+        #
+        # Line name for the current Line
+        #
+        # @return [String] Human-presentable Line name
+        #
+        def line_name
+          case self
+          when Line::RD
+            'Red'
+          when Line::BL
+            'Blue'
+          when Line::YL
+            'Yellow'
+          when Line::OR
+            'Orange'
+          when Line::GR
+            'Green'
+          when Line::SV
+            'Silver'
+          when Line::YLRP
+            'Yellow Line Rush Plus'
+          else
+            raise 'Invalid line'
+          end
+        end
+      end
+    end
+
+    # These requests require a Line
+    module RequiresLine
+      include Requests::Requester
+
+      #
+      # Station location and address information for all stations on the given line.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe330c WMATA Documentation}
+      #
+      # @param [String] line A Line code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def stations(line = nil)
+        query = line ? { LineCode: line } : {}
+
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::STATIONS,
+            query
+          )
+        )
+      end
+    end
+  end
+end

data/lib/weese/rail/metro_rail.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'weese/requests'
+require 'weese/rail/urls'
+require 'weese/rail/station'
+require 'weese/rail/line'
+require 'weese/location'
+
+module Weese
+  # Module containing everything MetroRail. Most important class: {MetroRail}.
+  module Rail
+    # MetroRail client. Used for accessing MetroRail-related WMATA APIs. See {RequiresLine} and {RequiresStation} for all API calls.
+    class MetroRail
+      include Requests::Requester
+      include Rail::RequiresStation
+      include Rail::RequiresLine
+
+      # @return [String] WMATA API key
+      attr_accessor :api_key
+
+      #
+      # A MetroRail client, used for accessing all MetroRail-related APIs
+      #
+      # @param [String] api_key WMATA API Key, get one at {http://developer.wmata.com}
+      #
+      def initialize(api_key)
+        @api_key = api_key
+      end
+
+      #
+      # Basic information on all MetroRail lines.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe330c WMATA Documentation}
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] Response JSON
+      #
+      def lines
+        fetch(
+          Requests::Request.new(
+            api_key,
+            Rail::Urls::LINES,
+            {}
+          )
+        )
+      end
+
+      #
+      # A list of nearby station entrances based on latitude, longitude, and radius (meters).
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe330f WMATA Documentation}
+      #
+      # @param [RadiusAtCoordinates] radius_at_coordinates Radius and lat/long to look around
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] Response JSON
+      #
+      def entrances(radius_at_coordinates)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::ENTRANCES,
+            radius_at_coordinates.to_h
+          )
+        )
+      end
+
+      #
+      # Uniquely identifiable trains in service and what track circuits they currently occupy.
+      # {https://developer.wmata.com/docs/services/5763fa6ff91823096cac1057/operations/5763fb35f91823096cac1058 WMATA Documentation}
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] Response JSON
+      #
+      def positions
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::POSITIONS,
+            contentType: 'json'
+          )
+        )
+      end
+
+      #
+      # Returns an ordered list of mostly revenue (and some lead) track circuits, arranged by line and track number.
+      # {https://developer.wmata.com/docs/services/5763fa6ff91823096cac1057/operations/57641afc031f59363c586dca WMATA Documentation}
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] Response JSON
+      #
+      def routes
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::ROUTES,
+            contentType: 'json'
+          )
+        )
+      end
+
+      #
+      # All track circuits including those on pocket tracks and crossovers. Each track circuit may include references to its right and left neighbors.
+      # {https://developer.wmata.com/docs/services/5763fa6ff91823096cac1057/operations/57644238031f59363c586dcb WMATA Documentation}
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] Response JSON
+      #
+      def circuits
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::CIRCUITS,
+            contentType: 'json'
+          )
+        )
+      end
+    end
+  end
+end

data/lib/weese/rail/station.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Weese
+  module Rail
+    # Constants for WMATA station codes
+    module Station
+      A01 = 'A01' # A WMATA Station code
+      A02 = 'A02' # A WMATA Station code
+      A03 = 'A03' # A WMATA Station code
+      A04 = 'A04' # A WMATA Station code
+      A05 = 'A05' # A WMATA Station code
+      A06 = 'A06' # A WMATA Station code
+      A07 = 'A07' # A WMATA Station code
+      A08 = 'A08' # A WMATA Station code
+      A09 = 'A09' # A WMATA Station code
+      A10 = 'A10' # A WMATA Station code
+      A11 = 'A11' # A WMATA Station code
+      A12 = 'A12' # A WMATA Station code
+      A13 = 'A13' # A WMATA Station code
+      A14 = 'A14' # A WMATA Station code
+      A15 = 'A15' # A WMATA Station code
+      B01 = 'B01' # A WMATA Station code
+      B02 = 'B02' # A WMATA Station code
+      B03 = 'B03' # A WMATA Station code
+      B04 = 'B04' # A WMATA Station code
+      B05 = 'B05' # A WMATA Station code
+      B06 = 'B06' # A WMATA Station code
+      B07 = 'B07' # A WMATA Station code
+      B08 = 'B08' # A WMATA Station code
+      B09 = 'B09' # A WMATA Station code
+      B10 = 'B10' # A WMATA Station code
+      B11 = 'B11' # A WMATA Station code
+      B35 = 'B35' # A WMATA Station code
+      C01 = 'C01' # A WMATA Station code
+      C02 = 'C02' # A WMATA Station code
+      C03 = 'C03' # A WMATA Station code
+      C04 = 'C04' # A WMATA Station code
+      C05 = 'C05' # A WMATA Station code
+      C06 = 'C06' # A WMATA Station code
+      C07 = 'C07' # A WMATA Station code
+      C08 = 'C08' # A WMATA Station code
+      C09 = 'C09' # A WMATA Station code
+      C10 = 'C10' # A WMATA Station code
+      C12 = 'C12' # A WMATA Station code
+      C13 = 'C13' # A WMATA Station code
+      C14 = 'C14' # A WMATA Station code
+      C15 = 'C15' # A WMATA Station code
+      D01 = 'D01' # A WMATA Station code
+      D02 = 'D02' # A WMATA Station code
+      D03 = 'D03' # A WMATA Station code
+      D04 = 'D04' # A WMATA Station code
+      D05 = 'D05' # A WMATA Station code
+      D06 = 'D06' # A WMATA Station code
+      D07 = 'D07' # A WMATA Station code
+      D08 = 'D08' # A WMATA Station code
+      D09 = 'D09' # A WMATA Station code
+      D10 = 'D10' # A WMATA Station code
+      D11 = 'D11' # A WMATA Station code
+      D12 = 'D12' # A WMATA Station code
+      D13 = 'D13' # A WMATA Station code
+      E01 = 'E01' # A WMATA Station code
+      E02 = 'E02' # A WMATA Station code
+      E03 = 'E03' # A WMATA Station code
+      E04 = 'E04' # A WMATA Station code
+      E05 = 'E05' # A WMATA Station code
+      E06 = 'E06' # A WMATA Station code
+      E07 = 'E07' # A WMATA Station code
+      E08 = 'E08' # A WMATA Station code
+      E09 = 'E09' # A WMATA Station code
+      E10 = 'E10' # A WMATA Station code
+      F01 = 'F01' # A WMATA Station code
+      F02 = 'F02' # A WMATA Station code
+      F03 = 'F03' # A WMATA Station code
+      F04 = 'F04' # A WMATA Station code
+      F05 = 'F05' # A WMATA Station code
+      F06 = 'F06' # A WMATA Station code
+      F07 = 'F07' # A WMATA Station code
+      F08 = 'F08' # A WMATA Station code
+      F09 = 'F09' # A WMATA Station code
+      F10 = 'F10' # A WMATA Station code
+      F11 = 'F11' # A WMATA Station code
+      G01 = 'G01' # A WMATA Station code
+      G02 = 'G02' # A WMATA Station code
+      G03 = 'G03' # A WMATA Station code
+      G04 = 'G04' # A WMATA Station code
+      G05 = 'G05' # A WMATA Station code
+      J02 = 'J02' # A WMATA Station code
+      J03 = 'J03' # A WMATA Station code
+      K01 = 'K01' # A WMATA Station code
+      K02 = 'K02' # A WMATA Station code
+      K03 = 'K03' # A WMATA Station code
+      K04 = 'K04' # A WMATA Station code
+      K05 = 'K05' # A WMATA Station code
+      K06 = 'K06' # A WMATA Station code
+      K07 = 'K07' # A WMATA Station code
+      K08 = 'K08' # A WMATA Station code
+      N01 = 'N01' # A WMATA Station code
+      N02 = 'N02' # A WMATA Station code
+      N03 = 'N03' # A WMATA Station code
+      N04 = 'N04' # A WMATA Station code
+      N06 = 'N06' # A WMATA Station code
+    end
+
+    # These requests require a Station
+    module RequiresStation
+      include Requests::Requester
+
+      #
+      # Distance, fare information, and estimated travel time between any two stations, including those on different lines.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe3313 WMATA Documentation}
+      #
+      # @param [String] from_station Station code to start trip at. Optional.
+      # @param [String] to_destination_station Destination station code. Optional.
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def station_to_station(from_station = nil, to_destination_station = nil)
+        query = {}
+
+        query['FromStationCode'] = from_station if from_station
+
+        query['ToStationCode'] = to_destination_station if to_destination_station
+
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::STATION_TO_STATION,
+            query
+          )
+        )
+      end
+
+      #
+      # List of reported elevator and escalator outages at a given station.
+      # {https://developer.wmata.com/docs/services/54763641281d83086473f232/operations/54763641281d830c946a3d76 WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def elevator_and_escalator_incidents(station = nil)
+        query = station ? { StationCode: station } : {}
+
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::ELEVATOR_AND_ESCALATOR_INCIDENTS,
+            query
+          )
+        )
+      end
+
+      #
+      # Reported rail incidents (significant disruptions and delays to normal service)
+      # {https://developer.wmata.com/docs/services/54763641281d83086473f232/operations/54763641281d830c946a3d77 WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def incidents(station = nil)
+        query = station ? { StationCode: station } : {}
+
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::INCIDENTS,
+            query
+          )
+        )
+      end
+
+      #
+      # Next train arrivals for the given station.
+      # {https://developer.wmata.com/docs/services/547636a6f9182302184cda78/operations/547636a6f918230da855363f WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def next_trains(station)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            [Rail::Urls::NEXT_TRAINS, station].join('/'),
+            {}
+          )
+        )
+      end
+
+      #
+      # Location and address information at the given station.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe3310 WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def station_information(station)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::INFORMATION,
+            StationCode: station
+          )
+        )
+      end
+
+      #
+      # Parking information for the given station.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe330d WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def parking_information(station)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::PARKING_INFORMATION,
+            StationCode: station
+          )
+        )
+      end
+
+      #
+      # Stations and distances between two stations on the same line.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe330e WMATA Documentation}
+      #
+      # @param [String] station Starting station code
+      # @param [String] to_destination_station Destination station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def path_from(station, to_destination_station)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::PATH,
+            FromStationCode: station,
+            ToStationCode: to_destination_station
+          )
+        )
+      end
+
+      #
+      # Opening and scheduled first/last train times for the given station.
+      # {https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe3312 WMATA Documentation}
+      #
+      # @param [String] station A station code
+      #
+      # @raise [WeeseError] If request or JSON parse fails
+      #
+      # @return [Hash] JSON Response
+      #
+      def timings(station)
+        fetch(
+          Requests::Request.new(
+            @api_key,
+            Rail::Urls::TIMINGS,
+            StationCode: station
+          )
+        )
+      end
+    end
+  end
+end

data/lib/weese/rail/urls.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Weese
+  module Rail
+    # URLS for MetroRail related endpoints
+    module Urls
+      LINES = 'https://api.wmata.com/Rail.svc/json/jLines' # WMATA Endpoints
+      ENTRANCES = 'https://api.wmata.com/Rail.svc/json/jStationEntrances' # WMATA Endpoints
+      POSITIONS = 'https://api.wmata.com/TrainPositions/TrainPositions' # WMATA Endpoints
+      ROUTES = 'https://api.wmata.com/TrainPositions/StandardRoutes' # WMATA Endpoints
+      CIRCUITS = 'https://api.wmata.com/TrainPositions/TrackCircuits' # WMATA Endpoints
+      ELEVATOR_AND_ESCALATOR_INCIDENTS = 'https://api.wmata.com/Incidents.svc/json/ElevatorIncidents' # WMATA Endpoints
+      INCIDENTS = 'https://api.wmata.com/Incidents.svc/json/Incidents' # WMATA Endpoints
+      NEXT_TRAINS = 'https://api.wmata.com/StationPrediction.svc/json/GetPrediction/' # WMATA Endpoints
+      INFORMATION = 'https://api.wmata.com/Rail.svc/json/jStationInfo' # WMATA Endpoints
+      PARKING_INFORMATION = 'https://api.wmata.com/Rail.svc/json/jStationParking' # WMATA Endpoints
+      PATH = 'https://api.wmata.com/Rail.svc/json/jPath' # WMATA Endpoints
+      TIMINGS = 'https://api.wmata.com/Rail.svc/json/jStationTimes' # WMATA Endpoints
+      STATION_TO_STATION = 'https://api.wmata.com/Rail.svc/json/jSrcStationToDstStationInfo' # WMATA Endpoints
+      STATIONS = 'https://api.wmata.com/Rail.svc/json/jStations' # WMATA Endpoint
+    end
+  end
+end

data/lib/weese/requests.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'weese/deserialize'
+
+module Weese
+  # Structures related to making API requests
+  module Requests
+    # Everything needed to make an HTTP request
+    class Request
+      # @return [String] WMATA API key
+      attr_accessor :api_key
+      # @return [String] URL
+      attr_accessor :path
+      # @return [Hash] Query parameters
+      attr_accessor :query
+
+      #
+      # Create a Request
+      #
+      # @param [String] api_key API key to make this Request with
+      # @param [String] path URL to make Request to
+      # @param [Hash] query Query parameters to append to Request
+      #
+      def initialize(api_key, path, query)
+        @api_key = api_key
+        @path = path
+        @query = query
+      end
+    end
+
+    # Actually making the HTTP request
+    module Requester
+      #
+      # Make a request to WMATA API
+      #
+      # @param [Request] wmata_request Request to send to WMATA API
+      #
+      # @raise [WeeseError] If the requests fails in any way
+      #
+      # @return [String] Body of response
+      #
+      def request(wmata_request)
+        response = Faraday.get(wmata_request.path) do |request|
+          request.params = wmata_request.query
+          request.headers['api_key'] = wmata_request.api_key
+        end
+
+        return response.body if response.success?
+
+        raise WeeseError, "#{response.status}, #{response.body}"
+      end
+
+      #
+      # Makes a request to WMATA API & deserializes the response into a Hash
+      #
+      # @param [Request] wmata_request Request to send to WMATA API
+      #
+      # @raise [WeeseError] If the requests fails in any way
+      #
+      # @return [Hash] Hash of response JSON
+      #
+      def fetch(wmata_request)
+        request(wmata_request).deserialize
+      end
+    end
+  end
+end

data/lib/weese/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Weese, a WMATA API gem
+module Weese
+  VERSION = '1.0.0' # Version
+end

data/lib/weese.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'weese/version'
+
+require 'weese/rail/metro_rail'
+require 'weese/rail/line'
+require 'weese/rail/station'
+
+require 'weese/bus/metro_bus'
+require 'weese/bus/route'
+require 'weese/bus/stop'
+
+require 'weese/location'
+
+module Weese
+  # Error output buy all functions in this gem
+  class WeeseError < StandardError; end
+end