genability 0.1.0

data/lib/genability/client.rb

@@ -0,0 +1,24 @@
+module Genability
+  # Wrapper for the Genability REST API
+  class Client < API
+    require 'genability/client/helpers'
+    require 'genability/client/load_serving_entity'
+    require 'genability/client/price'
+    require 'genability/client/season'
+    require 'genability/client/tariff'
+    require 'genability/client/territory'
+    require 'genability/client/time_of_use'
+    require 'genability/client/zip_code'
+
+    include Genability::Client::Helpers
+
+    include Genability::Client::LoadServingEntity
+    include Genability::Client::Price
+    include Genability::Client::Season
+    include Genability::Client::Tariff
+    include Genability::Client::Territory
+    include Genability::Client::TimeOfUse
+    include Genability::Client::ZipCode
+  end
+end
+

data/lib/genability/client/helpers.rb

@@ -0,0 +1,57 @@
+require 'time'
+require 'chronic'
+
+module Genability
+  class Client
+    # @private
+    module Helpers
+
+      private
+
+      def pagination_params(options)
+        {
+          'pageStart' => options['pageStart'] || options[:page_start] || options[:page],
+          'pageCount' => options['pageCount'] || options[:page_count] || options[:per_page],
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+      def convert_to_boolean(value = nil)
+        return nil if value.nil? || value.empty?
+        "true"
+      end
+
+      def multi_option_handler(value)
+        return nil if value.nil?
+        if value.is_a?(Array)
+          value.collect{|x| x.upcase}.join(',')
+        else
+          value.upcase
+        end
+      end
+
+      def format_to_iso8601(date_time = nil)
+        if date_time.respond_to?(:iso8601)
+          genability_iso8601_converter(date_time)
+        else
+          parse_and_format_to_iso8601(date_time)
+        end
+      end
+
+      def parse_and_format_to_iso8601(date_time = nil)
+        parsed_date = Chronic.parse(date_time.to_s)
+        parsed_date = parsed_date.nil? ? Time.parse(date_time.to_s) : parsed_date
+        genability_iso8601_converter(parsed_date)
+      rescue
+        nil
+      end
+
+      def genability_iso8601_converter(date_time = nil)
+        date_time.iso8601(1).gsub(/(?<=\-\d{2}):(?=\d{2})/, '')
+      rescue
+        nil
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/load_serving_entity.rb

@@ -0,0 +1,77 @@
+module Genability
+  class Client
+    # Load Serving Entity (LSE) is the industry term for what most people would call a utility,
+    # or an electric company. Since there are different types of electric company, we use the
+    # term LSE in our API's. This is a company or other organization that supplies load (electrons,
+    # electricity) to a customer. In many cases this is the same company that distributes the
+    # electricity too, but in some cases customers can have one company that they buy the load
+    # from, and another that operates the distribution system (runs the line to the house,
+    # manages the meters etc). Some characteristics and uses:
+    #
+    #   1. LSE's have territories that they operate in. Sometimes they operate in more than 1.
+    #   2. LSE's have tariffs (rate plans) and are central to many of our data structures.
+    module LoadServingEntity
+      # Returns a list of load serving entities
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] :starts_with  Indicates the search phrase should match the start of the name. (Optional)
+      # @option options [String] :ends_with Indicates the search phrase should match the end of the name. (Optional)
+      # @option options [String] :contains Indicates the search phrase should be somewhere in the middle of the name. (Optional)
+      # @option options [Integer] :page The page number to begin the result set from. If not specified, this will begin with the first result set. (Optional)
+      # @option options [Integer] :per_page The number of results to return. If not specified, this will return 25 results. (Optional)
+      # @return [Array] List of load serving entities.
+      # @see https://developer.genability.com/documentation/api-reference/public/lse
+      # @example Return the first 25 load serving entities
+      #   Genability.load_serving_entities
+      # @example Return the next 25 load serving entities
+      #   Genability.load_serving_entities(:page => 2)
+      # @example Return only 10 load serving entities
+      #   Genability.load_serving_entities(:per_page => 10)
+      # @example Search for load serving entities with the name 'Infinite'
+      #   Genability.load_serving_entities(:search => 'Infinite')
+      # @example Search for load serving entities starting with the letters 'Ka'
+      #   Genability.load_serving_entities(:starts_with => 'Ka')
+      # @example Search for load serving entities ending with the word 'Inc'
+      #   Genability.load_serving_entities(:ends_with => 'Inc')
+      # @example Search for load serving entities with the word 'Energy' somewhere in the name
+      #   Genability.load_serving_entities(:contains => 'Energy')
+      def load_serving_entities(options={})
+        get("lses", lses_params(options)).results
+      end
+
+      alias :lses :load_serving_entities
+
+      # Returns details for a single load serving entity
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param load_serving_entity_id [Integer] Unique Genability ID (primary key) for a Load Serving Entity.
+      # @return [Hashie::Mash] Details for a load serving entity.
+      # @see https://developer.genability.com/documentation/api-reference/public/lse
+      # @example Return the details for Georgia Power Co
+      #   Genability.load_serving_entity(2756)
+      def load_serving_entity(load_serving_entity_id)
+        get("lses/#{load_serving_entity_id}").results.first
+      end
+
+      alias :lse :load_serving_entity
+
+      private
+
+      def lses_params(options)
+        {
+          'wildCardText' => options[:contains] || options[:starts_with] || options[:ends_with],
+          'startsWithWildCard' => convert_to_boolean(options[:starts_with]),
+          'endsWithWildCard' => convert_to_boolean(options[:ends_with]),
+          'containsWildCard' => convert_to_boolean(options[:contains])
+        }.delete_if{ |k,v| v.nil? }.merge( pagination_params(options) )
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/price.rb

@@ -0,0 +1,53 @@
+module Genability
+  class Client
+    # Given a start date and time, Price returns the price of a specified Tariff as well as
+    # all the changes in price over the course of the next week. Optional parameters allow
+    # you to retrieve more specific pricing based on Territory and Consumption and Demand usage.
+    module Price
+      # @overload prices(tariff_id, from_date_time = Time.now.iso8601, options = {})
+      #   Returns the price of the specified tariff for the passed in date and time,
+      #   and also the changes in price for this tariff for the next week.
+      #   @param tariff_id [Integer] Unique Genability ID (primary key) for a tariff.
+      #   @param from_date_time [DateTime, String] Date and time of the requested start of the Price.
+      #     In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.
+      #     (Required, but can be omitted to default to Time.now.iso8601)
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [DateTime, String] :to Date and time of the requested end of the Price.
+      #     In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used. (Optional)
+      #   @option options [Integer] :territory_id When specified, rate changes returned will be for the specified Territory. (Optional)
+      #   @option options [Float] :consumption_amount By default, the rate amount calculation assumes the highest banded level of consumption. When a consumption amount is specified, this amount is used in the calculation. (Optional)
+      #   @option options [Float] :demand_amount By default, the rate amount calculation assumes the highest banded level of demand. When a demand amount is specified, this amount is used in the calculation. (Optional)
+      #   @return [Array] Array of charge types for the specified tariff, each with the price for the passed in date and time, and also the changes in price for this tariff for the next week.
+      #   @example Various examples for retrieving the price(s) of tariff number 520 (Pacific Gas & Electric Co Residential Time-Of-Use Service E-6)
+      #     Genability.prices(520)
+      #     Genability.prices(520, :consumption_amount => 500)
+      #     Genability.prices(520, "2011-06-13T00:00:00.0-070")
+      #     Genability.prices(520, Date.yesterday)
+      #     Genability.prices(520, "Last friday at 6:45pm", :to => "yesterday afternoon", :consumption_amount => 500)
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @see https://developer.genability.com/documentation/api-reference/public/price
+      def prices(tariff_id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        from_date_time = args.first || Time.now
+        get("prices/#{tariff_id}", prices_params(from_date_time, options)).results
+      end
+
+      private
+
+      def prices_params(from_date_time, options)
+        {
+          "fromDateTime" => format_to_iso8601(from_date_time),
+          "toDateTime" => format_to_iso8601(options[:to]),
+          "territoryId" => options[:territory_id],
+          "consumptionAmount" => options[:consumption_amount],
+          "demandAmount" => options[:demand_amount]
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+
+    end
+  end
+end
+

data/lib/genability/client/season.rb

@@ -0,0 +1,27 @@
+module Genability
+  class Client
+    # Most LSEs will charge different rates depending on the time of year. Each
+    # LSE defines the times of the year themselves but typically they are split
+    # into Summer and Winter. We refer to these as the Seasons of an LSE. We
+    # also define Season Groups, which contain more than Seasons and which
+    # altogether span a full calendar year. Each Season belongs to one and
+    # only one Season Group.
+    module Season
+      # Returns a list of season groups for a given load serving entity.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param load_serving_entity_id [Integer] Unique Genability ID (primary key) for a Load Serving Entity.
+      # @return [Array] list of season groups for a load serving entity.
+      # @see https://developer.genability.com/documentation/api-reference/public/season
+      # @example Return a list of season groups for Pacific Gas & Electric Co
+      #   Genability.seasons(734)
+      def seasons(load_serving_entity_id)
+        get("seasons", { :lseId => load_serving_entity_id }).results
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/tariff.rb

@@ -0,0 +1,80 @@
+module Genability
+  class Client
+    # Tariffs are rate plans for electricity. They describe who the plan applies
+    # to (service and applicability), what the charges are, and other information
+    # about this electricity service:
+    #
+    #   1. We have residential tariffs currently. General tariffs (commercial &
+    #      industrial and speciality tariffs) are coming soon.
+    #   2. You can specify whether you want the tariff fully populated, or whether
+    #      you just want a sub section of the data (to avoid charges and to speed
+    #      up your queries).
+    module Tariff
+      # Returns a list of tariffs.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :lse_id Filter tariffs for a specific Load Serving Entity. (Optional)
+      # @option options [Date] :effective_on  Only tariffs that are effective on this date. (Optional)
+      # @option options [String, Array] :customer_classes Only include these customer classes. Choices are: RESIDENTIAL, GENERAL. (Optional)
+      # @option options [String, Array] :tariff_types Only include these tariff types. Choices are: DEFAULT, ALTERNATIVE, OPTIONAL_EXTRA, RIDER. (Optional)
+      # @option options [String] :zip_code Return tariffs for this zip or post code. (Optional)
+      # @option options [Boolean] :populate_rates Populates the rate details for the returned Tariffs. (Optional)
+      # @option options [Integer] :page The page number to begin the result set from. If not specified, this will begin with the first result set. (Optional)
+      # @option options [Integer] :per_page The number of results to return. If not specified, this will return 25 results. (Optional)
+      # @return [Array] List of tariffs.
+      # @see https://developer.genability.com/documentation/api-reference/public/tariff
+      # @example Return the first 25 tariffs
+      #   Genability.tariffs
+      # @example Return the tariffs for Georgia Power Co
+      #   Genability.tariffs(:lse_id => 2756)
+      # @example Return only residential tariffs
+      #   Genability.tariffs(:customer_classes => 'residential')
+      # @example Return only default and alternative tariff types
+      #   Genability.tariffs(:tariff_types => ['default', 'alternative'])
+      def tariffs(options = {})
+        get("tariffs", tariffs_params(options)).results
+      end
+
+      # Returns one tariff.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param tariff_id [Integer] Unique Genability ID (primary key) for a tariff.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean] :populate_rates Populates the rate details for the returned Tariff. (Optional)
+      # @return [Hashie::Mash] A tariff.
+      # @see https://developer.genability.com/documentation/api-reference/public/tariff
+      # @example Return the residential serice tariff for Georgia Power Co
+      #   Genability.tariff(512)
+      def tariff(tariff_id, options = {})
+        get("tariffs/#{tariff_id}", tariff_params(options)).results.first
+      end
+
+      private
+
+      def tariffs_params(options)
+        {
+          'lseId' => options[:lse_id],
+          'effectiveOn' => options[:effective_on],
+          'customerClasses' => multi_option_handler(options[:customer_classes]),
+          'tariffTypes' => multi_option_handler(options[:tariff_types]),
+          'zipCode' => options[:zip_code]
+        }.delete_if{ |k,v| v.nil? }.
+          merge( tariff_params(options) ).
+          merge( pagination_params(options) )
+      end
+
+      def tariff_params(options)
+        {
+          'populateRates' => convert_to_boolean(options[:populate_rates])
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/territory.rb

@@ -0,0 +1,80 @@
+module Genability
+  class Client
+    # Territories define the areas of coverage for Load Serving Entities
+    # and in some cases for individual tariffs. The areas of coverage can
+    # be at these levels:
+    #
+    #   1. State
+    #   2. County
+    #   3. City
+    #   4. Zip Code
+    #
+    # Territories can have one of these two usage types:
+    #
+    #   1. Service - defines the areas where this LSE provides service
+    #   2. Tariff - defines the areas where a particular tariff rate applies
+    #      to. These types of territories are typically defined by the LSE.
+    #
+    # We define a Service Territory for each state that an LSE provides
+    # coverage. The usageType attribute specifies how this definition
+    # is done, either at the State, County, City or Zip Code level.
+    module Territory
+
+      # Returns one territory.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param territory_id [Integer] Unique Genability ID (primary key) for each Territory.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean] :populate_items If true, this returns a List of TerritoryItems for each Territory in the result set. (Optional; defaults to false)
+      # @return [Hashie::Mash] Details for one territory.
+      # @see https://developer.genability.com/documentation/api-reference/public/territory
+      # @example Return territory Baseline Region V for Pacific Gas & Electric Co
+      #   Genability.territory(3539)
+      def territory(territory_id, options = {})
+        get("territories/#{territory_id}", territory_params(options)).results.first
+      end
+
+      # Returns a list of territories.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :lse_id Filter tariffs for a specific Load Serving Entity. (Optional)
+      # @option options [Boolean] :populate_items If true, this returns a List of TerritoryItems for each Territory in the result set. (Optional; defaults to false)
+      # @option options [Integer] :master_tariff_id Filters the result set to only include territories covered by this master tariff id. (Optional)
+      # @option options [String] :contains_item_type Filters the result set to include a particular type of territory. Possible values are: CITY, ZIPCODE, STATE, COUNTY. (Optional)
+      # @option options [String] :contains_item_value Filters the Types by this value. e.g. 94115 when searching for types of ZIPCODE. (Optional)
+      # @return [Array] List of territories.
+      # @see https://developer.genability.com/documentation/api-reference/public/territory
+      # @example Return a list of territories for Pacific Gas & Electric Co
+      #   Genability.territories(:lse_id => 734)
+      def territories(options = {})
+        get("territories", territories_params(options)).results
+      end
+
+      private
+
+      def territory_params(options)
+        {
+          'populateItems' => convert_to_boolean(options[:populate_items])
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+      def territories_params(options)
+        {
+          'lseId' => options[:lse_id],
+          'masterTariffId' => options[:master_tariff_id],
+          'containsItemType' => options[:contains_item_type],
+          'containsItemValue' => options[:contains_item_value]
+        }.delete_if{ |k,v| v.nil? }.
+          merge( territory_params(options) ).
+          merge( pagination_params(options) )
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/time_of_use.rb

@@ -0,0 +1,66 @@
+module Genability
+  class Client
+    # Many tariffs have pricing that depends on the time of day the energy
+    # is being used. We call these times the Time of Use for a tariff.
+    # The most common examples are On Peak and Off Peak. Some examples
+    # here may help:
+    #
+    #   1. Within a single Time of Use, e.g. On Peak, the price for a
+    #      tariff will always be the same.
+    #   2. Within a single Time of Use, e.g. On Peak, you may have multiple
+    #      Periods. A Period is a range of days and times that this TOU applies to.
+    module TimeOfUse
+
+      # Returns a particular time of use group using its time of use group ID and the load serving entity ID.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param load_serving_entity_id [Integer] Unique Genability ID (primary key) for a Load Serving Entity.
+      # @param time_of_use_group_id [Integer] Genability ID (primary key) for this Time of Use Group. This is unique within the LSE, not across LSE's so you will always need to specify the LSE ID when requested a TOU Group.
+      # @return [Hashie::Mash] Return the time of uses for a load serving entity.
+      # @see https://developer.genability.com/documentation/api-reference/public/time-of-use
+      # @example Return the time of use group for Georgia Power Co
+      #   Genability.time_of_uses(2756, 1)
+      def time_of_uses(load_serving_entity_id, time_of_use_group_id)
+        get("timeofuses/#{load_serving_entity_id}/#{time_of_use_group_id}").results.first
+      end
+
+      alias :tou :time_of_uses
+
+      # Returns all the Intervals for a Time of Use Group for an optionally specified
+      # from and to date and time range. Defaults to current time if fromDateTime is
+      # not specified and to a one week look ahead window if toDateTime is not specified.
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @param load_serving_entity_id [Integer] Unique Genability ID (primary key) for a Load Serving Entity.
+      # @param time_of_use_group_id [Integer] Genability ID (primary key) for this Time of Use Group. This is unique within the LSE, not across LSE's so you will always need to specify the LSE ID when requested a TOU Group.
+      # @param options [Hash] A customizable set of options.
+      # @option options [DateTime] :from ISO 8601 format for the starting date and time of the requested Intervals. Defaults to current day and time if not specified. (Optional)
+      # @option options [DateTime] :to ISO 8601 format for the ending date and time of the requested Intervals. Defaults to one week after the fromDateTime. (Optional)
+      # @return [Array] Returns all the Intervals for a Time of Use Group.
+      # @see https://developer.genability.com/documentation/api-reference/public/time-of-use
+      # @example Return the intervals for the time of use group for Georgia Power Co
+      #   Genability.time_of_use_intervals(2756, 1)
+      def time_of_use_intervals(load_serving_entity_id, time_of_use_group_id, options = {})
+        get("timeofuses/#{load_serving_entity_id}/#{time_of_use_group_id}/intervals", interval_params(options)).results
+      end
+
+      alias :tou_intervals :time_of_use_intervals
+      alias :intervals :time_of_use_intervals
+
+      private
+
+      def interval_params(options)
+        {
+          'fromDateTime' => format_to_iso8601(options[:from]),
+          'toDateTime' => format_to_iso8601(options[:to])
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+    end
+  end
+end
+