Module: Genability::Client::Calculate

Included in:

Genability::Client

Defined in:

lib/genability/client/calculate.rb

Overview

The Calculate service basically calculates the cost of electricity for a given rate/pricing plan. This can be used to calculate a bill, "what-if" different rates, levels of usage, energy efficiency measures or any other electrical activity. It gives a total cost for a period of time. (Note that if you want a price/rate for a specific point in time, then look at the Price service.)

Instance Method Summary

• #calculate(tariff_id, from_date_time, to_date_time, tariff_inputs, options = {}) ⇒ Object

  Calculate the cost of electricity for a given rate/pricing plan.

• #calculate_metadata(tariff_id, from_date_time, to_date_time, options = {}) ⇒ Array

  Calling the URL as a HTTP GET will return the "inputs" required to accurately calculate the cost for a given period.

Instance Method Details

#calculate(tariff_id, from_date_time, to_date_time, tariff_inputs, options = {}) ⇒ Object

Calculate the cost of electricity for a given rate/pricing plan.

To run a new calculation, you will POST a payload containing the calculation criteria and inputs, and a Calculated Cost will be returned. The table below documents the various properties of the payload, and immediately after the table is an example of the payload itself.

Parameters:

• tariff_id (Integer) —

  Unique Genability ID (primary key) for a tariff.

• from_date_time (DateTime, String) —

  Starting date and time for this Calculate request. In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.

• to_date_time (DateTime, String) —

  End date and time for this Calculate request. In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.

• options (Hash) (defaults to: {}) —

  A customizable set of options.

Options Hash (options):

• :territory_id (Integer) —

  The territory ID of where the usage consumption occurred. (Required for most CA tariffs.)

• :detail_level (String) —

  Toggles the level of details for the calculation result. (Optional) Possible values are: ALL - return all details for this calculation (default) TOTAL - return only the overall total, without any details CHARGE_TYPE - group the details by charge types, such as FIXED, CONSUMPTION, QUANTITY RATE - group the details by rates. This is most similar to how a utility bill is constructed.

• :tariff_inputs (Array) —

  The array of TariffInput values to use when running the calculation.

See Also:

• https://developer.genability.com/documentation/api-reference/pricing/calculate

Rate Limited:

• true

Supported formats:

• :json

Requires Authentication:

• true

# File 'lib/genability/client/calculate.rb', line 68

def calculate(tariff_id, from, to, tariff_inputs, options = {})
  post( "beta/calculate/#{tariff_id}?appId=#{application_id}&appKey=#{application_key}",
        calculate_params(from, to, tariff_inputs, options)
      ).results.first
end

#calculate_metadata(tariff_id, from_date_time, to_date_time, options = {}) ⇒ Array

Calling the URL as a HTTP GET will return the "inputs" required to accurately calculate the cost for a given period. It essentially gives you the meta-data for what to pass into the calculate method, and as such provides a template for the payload of the HTTP POST.

Examples:

Return the inputs required to accurately calculate the cost for a given period

Genability.calculate_metadata(512, "2011-06-16T19:00:00.0-0400", "2011-08-01T00:00:00.0-0400",
  { :additional_values => { "connectionType" => "Primary Connection", "cityLimits" => "Inside" })

Parameters:

• tariff_id (Integer) —

  Unique Genability ID (primary key) for a tariff.

• from_date_time (DateTime, String) —

  Starting date and time for this Calculate request. In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.

• to_date_time (DateTime, String) —

  End date and time for this Calculate request. In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.

• options (Hash) (defaults to: {}) —

  A customizable set of options.

Options Hash (options):

• :territory_id (Integer) —

  The territory ID of where the usage consumption occurred. (Required for most CA tariffs.)

• :additional_values (Hash) —

  Any additional applicability values that are required to calculate this tariff are passed in on the request url. Keep in mind that this is only for the GET method where you are getting the required inputs. When you POST to run the calculation, you will pass these applicability values as part of the Tariff Input array. To find out how to get the list of applicability properties required for a tariff, read more here.

Returns:

• (Array) —

  Array of TariffInput for consumption.

See Also:

• https://developer.genability.com/documentation/api-reference/pricing/calculate

Rate Limited:

• true

Supported formats:

• :json

Requires Authentication:

• true

# File 'lib/genability/client/calculate.rb', line 39

def calculate_metadata(tariff_id, from, to, options = {})
  get("beta/calculate/#{tariff_id}", calculate_meta_params(from, to, options)).results
end