Tariff

Overview

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:

  • We have residential tariffs and general tariffs (commercial & industrial and speciality tariffs).
  • 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).

Data Definitions

The complete tariff data is actually a hierarchy of a number of objects. We call the "header" object the Tariff (to confuse things!), which contains zero or more TariffRate objects. Think of a tariff rate like the line item on your bill. Then each tariff rate has 1 or more TariffRateBand. Some charges (rates) can be banded to contain several levels based on demand or consumption (or other) thresholds. Our rich structure is designed to support the complexity found in the large array of tariff plans that are in the market.

TariffId versus MasterTariffId

Tariff data changes periodically. E-1 Residential in PG&E territory, for example, usually changes a few times per year. For each revision we created a new tariff with a unique tariffId. Logically, however, each of these new tariffs is actually just a different version of a single "master" tariff. This family of tariffs is tied together with the masterTariffId property. Again using E-1 as an example, each version of the tariff will have a different tariffId, but they all have the same masterTariffId -- 522.

Taxes

The Genability database only has rates that appear in utility tariff books. That means that it does not have state, local, and other tax rates. That doesn't mean that you can't include them in a calculation, though. We have a quick how-to[how_to] on exactly how to do that.

Tariff

The Tariff object has the following data structure.

Name Type Fields Description
tariffId Long M Unique Genability ID (primary key) for this tariff
masterTariffId Long M Unique Genability ID that persists across all revisions of this tariff
tariffCode String M Short code that the LSE uses as an alternate name for the tariff
tariffName String M Name of the tariff as used by the LSE
lseId Long M ID of load serving entity this tariff belongs to
lseName String M Name of the load serving entity
serviceType String M Type of service for the tariff. Current values include ELECTRICITY (grid power) and SOLAR_PV (Solar PPA or Lease)
priorTariffId Long Unique Genability ID that identifies the prior revision of the tariffId above
distributionLseId Long In states like Texas where the load serving entity that sells the power is different than the load serving entity that distributes the power, this will contain the ID of the distribution LSE. Otherwise, it will be null.
tariffType String Possible values are:
DEFAULT - tariff that is automatically given to this service class
ALTERNATE - opt in alternate tariff for this service class
OPTIONAL_EXTRA - opt in extra, such as green power or a smart thermostat program
RIDER - charge that can apply to multiple tariffs. Often a regulatory mandated charge
customerClass String Possible values are:
RESIDENTIAL - homes, apartments etc.
GENERAL - commercial, industrial and other business and organization service types (often have additional applicability criteria)
SPECIAL_USE - examples are government, agriculture, street lighting, transportation
customerCount Integer Number of customers that are on this master tariff
customerLikelihood Decimal The likelihood that a customer is on this tariff of all the tariffs in the search results. Only populated when getting more than one tariff.
customerCountSource String E Where we got the customer count numbers from. Typically FERC (form 1 filings) or Genability (our own estimates).
territoryId String ID of the territory that this tariff applies to. This is typically the service area for the LSE in this regulatory region (i.e. a state in the USA)
effectiveDate DateTime Date on which the tariff was or will be effective
endDate DateTime Date on which this tariff is no longer effective. Can be null which means end date is not known or tariff is open ended
closedDate Date E Date on which a tariff became closed to new customers, but still available for customers who were on it at the time. Can be null which means that the tariff is not closed. All versions of a particular tariff (i.e. those that share a particular masterTariffId) will have the same closedDate value. See example
timeZone String If populated (usually is), its the timezone that this tariffs dates and times refer to
billingPeriod String The minimum chargePeriod present on this tariff.
currency String ISO Currency code that the rates for this tariff refer to (e.g. USD for USA Dollar)
chargeTypes String A comma separated list of all the different ChargeType rates on this tariff.
chargePeriod String The most fine grained period for which charges are calculated.
minMonthlyConsumption Decimal E When applicable, the maximum monthly consumption allowed in order to be eligible for this tariff.
maxMonthlyConsumption Decimal E When applicable, the minimum monthly consumption allowed in order to be eligible for this tariff.
minMonthlyDemand Decimal E When applicable, the maximum monthly demand allowed in order to be eligible for this tariff.
maxMonthlyDemand Decimal E When applicable, the minimum monthly demand allowed in order to be eligible for this tariff.
hasTimeOfUseRates Boolean Indicates whether this tariff contains one or more Time of Use Rate.
hasTieredRates Boolean Indicates whether this tariff contains one or more Tiered Rate.
hasContractedRates Boolean Indicates whether this tariff contains one or more Rate that can be contracted (sometimes called by-passable or associated with a price to compare).
hasTariffApplicability Boolean E Indicates that this tariff has additional eligibility criteria, as specified in the TariffProperty collection (below).
hasRateApplicability Boolean Indicates that one or more rates on this tariff are only applicable to customer with a particular circumstance. When true, this will be specified in the TariffProperty collection, and also on the TariffRate or rates in question.
hasNetMetering Boolean E Indicates whether this tariff contains one or more net metered rates.
isActive Boolean DEPRECATED. Signifies that this tariff id is the currently active tariff (now) within all tariffs sharing this master tariff id. Instead, use the effective and end dates to test whether a tariff is active or not. If you're searching for tariffs, use effectiveOn instead.
properties List of TariffProperty The properties on this tariff. See below for the TariffProperty structure.
rates List of TariffRate The rates for this tariff. See below for TariffRate structure

Tariff Rate

The TariffRate object has the following data structure.

Name Type Fields Description
tariffRateId Long M Unique Genability ID (primary key) for each tariff rate
tariffId Long M Associates the rate with a tariff (foreign key)
riderId Long M Populated when this is a rider attached to this tariff. null otherwise
tariffSequenceNumber Integer M Sequence of this rate in the tariff, for display purposes only (e.g. this is the order on the bill)
rateGroupName String M Name of the group this rate belongs to
rateName String M Name of this rate. Can be null (in which case use the group name)
fromDateTime DateTime If populated, this indicates the rates effective date is not the same as that of its tariff
toDateTime DateTime If populated, this indicates the rates end date is not the same as that of its tariff
territory Territory Only populated when this rate applies to a different region than the whole tariff (e.g. California Baseline Regions)
season Season The season this rate applies to. Only used for seasonal rates (null otherwise)
timeOfUse TimeOfUse The time period this rate applies to. Only used for TOU rates (null otherwise)
chargeType String Possible values:
FIXED_PRICE - a fixed charge for the period
CONSUMPTION_BASED - based on quantity used (e.g. kW/h)
DEMAND_BASED - based on the peak demand (e.g. kW)
QUANTITY - a rate per number of items (e.g. $5 per street light)
FORMULA - a rate that has a specific or custom formula
MINIMUM - a minimum amount that the LSE will charge you, regardless of the other charges
TAX - a percentage tax rate which is applied to the sum of all of the other charges on a bill
chargeClass String A comma separated string that indicates what class(es) of charges this rate is for. Values include TRANSMISSION, DISTRIBUTION, SUPPLY, TAX, OTHER, CONTRACTED, USER_ADJUSTED, and AFTER_TAX.
chargePeriod String Indicates what period this charge is calculated for. This is usually the same as the billing period (and is usually monthly) but can be other intervals. Possible values are:
MONTHLY - each calendar month
DAILY - calculated for each day
QUARTERLY - every 3 months
ANNUALLY - every year
transactionType String E Indicates whether this rate is BUY (no credit when supplying back), SELL (e.g. a feed in tariff), or NET (you get a credit, e.g. net metering).
quantityKey String When not null, the property that defines the type of quantity this rate applies to.
applicabilityKey String When not null, the property that defines the eligibility criteria for this rate.
variableLimitKey String When populated this defines the variable which determines the upper limit(s) of this rate.
variableRateKey String When not null, this is the name of the property that defines the variable rate. In this case the rate field is null, or can (rarely) be used as an input to the determination of the variable rate
variableFactorKey String When not null, this is the name of the property that defines the variable factor to apply to this rate.
rateBands List of TariffRateBand See the data definition below

Tariff Rate Band

The TariffRateBand object has the following data structure.

Name Type Fields Description
tariffRateBandId Long Unique Genability ID (primary key) for each Band
tariffRateId Long ID of the rate this band belongs to (foreign key)
rateSequenceNumber Integer This bands position in the bands for its rate
hasConsumptionLimit Boolean true indicates that this has banded consumption
consumptionUpperLimit Decimal When hasConsumptionLimit is true, this indicates the upper consumption limit of this band. null means no upper limit
hasDemandLimit Boolean true indicates that this has banded demand
demandUpperLimit Decimal When hasDemandLimit is true, this indicates the upper demand limit of this band. null means no upper limit
hasPropertyLimit Boolean true indicates that this has a limit based on a property
propertyUpperLimit Decimal When hasPropertyLimit is true, this indicates the upper limit of this band. null means no upper limit
applicabilityValue String When not null, this indicates the value of applicability property that qualifies for this rate.
calculationFactor Decimal A factor to be applied to the cost of the rate.
rateAmount Decimal Charge amount for this band
rateUnit String Possible values:
COST_PER_UNIT - rate amount multiplied by the number of units
PERCENTAGE - percentage of a value (e.g. percentage of overall bill)
isCredit Boolean When true this band is a credit amount (reduces the bill)

Tariff Property

Tariff properties represent metadata about a tariff. They might tell you things like, "What values are required to do a calculation with this tariff?" or "What do I have to do in order to be eligible for this tariff?" They're broken down into a number of types, the most important of which are listed below.

Applicabilities

Tariff properties of type APPLICABILITY tell you whether or not a customer is eligible to receive service under a particular tariff. For example, a tariff that is only for electric vehicles might have the hasElectricVehicle applicability property.

Rate Criteria

Tariff properties of type RATE_CRITERIA represent things that you need to know in order to properly calculate the tariff. This includes obvious things like consumption and demand, but also things like dailyMedicalAllowance or isSmartRateCustomer.

For things other than consumption and demand, we usually set a reasonable default value so you don't have to answer questions about every single property before doing a calculation. If you want to set these values yourself, though, you can do that by running through the list of properties returned when you set populateProperties to true when getting a tariff.

Data Structure

The TariffProperty object has the following data structure.

Name Type Fields Description
keyName String M Unique name for this property
displayName String M The display name of this property
keyspace String M Top level categorization of the property hierarchy
family String M Second level categorization of the property hierarchy, below keyspace
description String M A longer description of the tariff property. Good for further explanation as part of a customer "questionaire"
dataType String M The data type of this property. Possible values are string, choice, boolean, date, decimal, integer, formula
propertyTypes String M The category of property. Possible values are APPLICABILITY, RATE_CRITERIA, BENEFIT, DATA_REPUTATION
operator String The mathematical operator associated with this property's value, where applicable.
propertyValue String If applicable the specific value of this property.
minValue String If applicable the minimum value of this property.
maxValue String If applicable the maximum value of this property.
choices Array of Choices The possible choices for this array
formulaDetail String If this property is a FORMULA type, the formula details will be in this field.
isDefault Boolean Whether the value of this Property is the default value.

Here's an example in JSON of a fully populated tariff, containing tariff rates and tariff rate bands:

{
    "tariffId":512,
    "masterTariffId":512,
    "priorTariffId":null,
    "lseId":2756,
    "lseName":"Georgia Power Co",
    "distributionLseId":null,
    "tariffCode":"R-17",
    "tariffName":"Residential Service",
    "tariffType":"DEFAULT",
    "customerClass":"RESIDENTIAL",
    "territoryId":3114,
    "effectiveDate":"2011-03-01T00:00:00.000-0800",
    "endDate":null,
    "isActive":true,
    "hasNetMetering":true,
    "minMonthlyConsumption":null,
    "maxMonthlyConsumption":null,
    "minMonthlyDemand":null,
    "maxMonthlyDemand":null,
    "billingPeriod":"MONTHLY",
    "properties":null,
    "timeZone":"US/Eastern",
    "currency":"USD",
    "rates":[
    {
       "tariffRateId":2734,
       "tariffId":512,
       "riderId":null,
       "tariffSequenceNumber":0,
       "rateGroupName":"Basic Service Charge",
       "rateName":"Basic Service Charge",
       "territory":null,
       "season":null,
       "timeOfUse":null,
       "chargeType":"FIXED_PRICE",
       "chargePeriod":"MONTHLY",
       "quantityKey":null,
       "applicabilityKey":null,
       "variableLimitKey":null,
       "rateBands":[
          {
             "tariffRateBandId":3258,
             "tariffRateId":2734,
             "rateSequenceNumber":1,
             "hasConsumptionLimit":false,
             "consumptionUpperLimit":null,
             "hasDemandLimit":false,
             "demandUpperLimit":null,
             "hasPropertyLimit":false,
             "propertyUpperLimit":null,
             "applicabilityValue":null,
             "calculationFactor":null,
             "rateAmount":.090000,
             "rateUnit":"COST_PER_UNIT",
             "isCredit":false
          }
       ]
    },
    {
       "tariffRateId":2735,
       "tariffId":512,
       "riderId":null,
       "tariffSequenceNumber":1,
       "rateGroupName":"Energy Charges",
       "rateName":"Winter Energy Charges",
       "territory":null,
       "season":{
          "seasonId":314,
          "lseId":2756,
          "seasonGroupId":3,
          "seasonName":"Winter",
          "seasonFromMonth":10,
          "seasonFromDay":1,
          "seasonToMonth":5,
          "seasonToDay":31
       },
       "timeOfUse":null,
       "chargeType":"CONSUMPTION_BASED",
       "chargePeriod":"MONTHLY",
       "quantityKey":null,
       "applicabilityKey":null,
       "variableLimitKey":null,
       "rateBands":[
          {
             "tariffRateBandId":3259,
             "tariffRateId":2735,
             "rateSequenceNumber":1,
             "hasConsumptionLimit":true,
             "consumptionUpperLimit":650.0,
             "hasDemandLimit":false,
             "demandUpperLimit":null,
             "hasPropertyLimit":false,
             "propertyUpperLimit":null,
             "applicabilityValue":null,
             "calculationFactor":null,
             "rateAmount":.050633,
             "rateUnit":"COST_PER_UNIT",
             "isCredit":false
          },
          {
             "tariffRateBandId":3260,
             "tariffRateId":2735,
             "rateSequenceNumber":2,
             "hasConsumptionLimit":true,
             "consumptionUpperLimit":1000.0,
             "hasDemandLimit":false,
             "demandUpperLimit":null,
             "hasPropertyLimit":false,
             "propertyUpperLimit":null,
             "applicabilityValue":null,
             "calculationFactor":null,
             "rateAmount":.043443,
             "rateUnit":"COST_PER_UNIT",
             "isCredit":false
          },
          {
             "tariffRateBandId":3261,
             "tariffRateId":2735,
             "rateSequenceNumber":3,
             "hasConsumptionLimit":true,
             "consumptionUpperLimit":null,
             "hasDemandLimit":false,
             "demandUpperLimit":null,
             "hasPropertyLimit":false,
             "propertyUpperLimit":null,
             "applicabilityValue":null,
             "calculationFactor":null,
             "rateAmount":.042647,
             "rateUnit":"COST_PER_UNIT",
             "isCredit":false
          }
       ]
    },
 ]
}

Operations

Get a List of Tariffs

This allows you to search for a set of tariffs and get them back as a list of tariff objects in the standard response format.

Resource URI

GET /rest/public/tariffs

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
lseId Long Filter tariffs for a specific LSE (Optional)
effectiveOn DateTime Only tariffs that are effective on this date (Optional)
openOn Date Only tariffs that were open (i.e. were not closed to new customers) on this date (Optional) See example
fromDateTime DateTime Only include tariffs that are effective on or after this date (Optional)
toDateTime DateTime Only include tariffs that are effective on or before this date (Optional)
customerClasses String Comma separated string that indicates the customer classes to include. Choices are: RESIDENTIAL, GENERAL, SPECIAL_USE (Optional)
tariffTypes String Comma separated string that indicates the tariff types to include. Choices are: DEFAULT, ALTERNATIVE, OPTIONAL_EXTRA, RIDER (Optional)
serviceTypes String Comma separated string that indicates the service types to include. Choices are: ELECTRICITY, SOLAR_PV (Optional, default is all serviceTypes)
privacyFlags String Comma separated string that indicates the privacy flags types to include. Only applicable if you publish private tariffs. Choices are: PUBLIC, UNLISTED, PRIVATE (Optional)
addressString String An address of any kind. Ideally this will contain a zipcode or post code. (Optional)
zipCode or postCode String An alternate to using addressString. Make sure its just the ZIP code or post code though. (Optional)
country String An alternate to using addressString. Use when passing in a postCode, set to the ISO Country Code you require (Optional)
populateProperties Boolean Populates the properties for the returned tariffs (Optional; defaults to false)
populateRates Boolean Populates the rate details for the returned tariffs (Optional; defaults to false)
populateDocuments Boolean Populates the document links for the returned tariffs (Optional; defaults to false)
accountId String The unique ID of the Account for which you want to find tariffs. Values passed in will override those from the account. For example, passing in zipCode=48322 will override whatever zipCode may be set on the Account. (Optional)
consumption Decimal Return tariffs which are eligible for this consumption amount (Optional)
demand Decimal Return tariffs which are eligible for this demand amount (Optional)
hasNetMetering Boolean Return tariffs which have or do not have any net metered tariff rates (Optional)
bundleRates Boolean When true (false by default) the rates are summarized (bundled). Note that this only works for tariffs with a customerClass of RESIDENTIAL. (Optional)
applicableRateOnly Boolean When true (false by default) rate applicability criteria will be applied to the rates. You’ll only get back rates that match the requests rate applicability values, or the default rate applicability value as set on the tariff. (Optional)

Example 1 - Retrieving Residential Tariffs for a Zip Code

In this example we query for all residential tariffs in the 94115 ZIP code. We also request to populate the properties. In the response, the territoryId property is returned with a default value, which is the territoryId that matches the requested ZIP code. This is helpful when working with tariffs with rates that vary by geographic location.

GET /rest/public/tariffs?zipCode=94115&populateProperties=true&customerClasses=RESIDENTIAL
{
   "status":"success",
   "count":40,
   "type":"Tariff",
   "results":[
      {
         "tariffId":518,
         "masterTariffId":518,
         "priorTariffId":518,
         "lseId":734,
         "lseName":"Pacific Gas & Electric Co",
         "distributionLseId":null,
         "tariffCode":"E-7",
         "tariffName":"Residential Time-Of-Use Service E-7 (Basic)",
         "tariffType":"ALTERNATIVE",
         "customerClass":"RESIDENTIAL",
         "territoryId":807,
         "effectiveDate":"2011-03-01",
         "endDate":"2011-06-19",
         "timeZone":"US/Pacific",
         "isActive":false,
         "hasNetMetering":true,
         "minMonthlyConsumption":null,
         "maxMonthlyConsumption":null,
         "minMonthlyDemand":null,
         "maxMonthlyDemand":null,
         "billingPeriod":"MONTHLY",
         "currency":"USD",
         "properties":[
            {
               "keyName":"territoryId",
               "displayName":"TerritoryId",
               "family":"billing",
               "keyspace":"electricity",
               "description":"Territory id where tariff is operational",
               "dataType":"CHOICE",
               "choices":[
                  {
                     "value":"3542",
                     "displayValue":"Baseline Region Y"
                  },
                  {
                     "value":"3543",
                     "displayValue":"Baseline Region Z"
                  },
                  {
                     "value":"3540",
                     "displayValue":"Baseline Region W"
                  },
                  {
                     "value":"3541",
                     "displayValue":"Baseline Region X"
                  },
                  {
                     "value":"3538",
                     "displayValue":"Baseline Region T"
                  },
                  {
                     "value":"3539",
                     "displayValue":"Baseline Region V"
                  },
                  {
                     "value":"3536",
                     "displayValue":"Baseline Region R"
                  },
                  {
                     "value":"3537",
                     "displayValue":"Baseline Region S"
                  },
                  {
                     "value":"3535",
                     "displayValue":"Baseline Region Q"
                  },
                  {
                     "value":"3534",
                     "displayValue":"Baseline Region P"
                  }
               ],
               "propertyTypes":"RATE_CRITERIA",
               "operator":null,
               "propertyValue":"3538",
               "isDefault":true
            },
            {
               "keyName":"consumption",
               "displayName":"Consumption (kWh)",
               "family":"load",
               "keyspace":"electricity",
               "description":"Quantity in kWh of load that is used for a period of time",
               "dataType":"DECIMAL",
               "choices":[

               ],
               "propertyTypes":"RATE_CRITERIA",
               "operator":null,
               "isDefault":false
            }
         ]
      },

      /* edited for length */

Example 2 - Excluding Closed Tariffs from Tariff Selection

Utilities may close a tariff to new customers and allow customers that are currently on the tariff to be grandfathered. Therefore, closed tariffs should typically be included in the pre-solar tariff list but does not need to be included in the post-solar tariff list unless the customer is currently on a closed tariff.

To exclude closed tariffs from the tariff list, add the openOn parameter to your Get Tariffs call:

GET /rest/public/tariffs?zipCode=93550&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&effectiveOn=20170101&openOn=20170101

Get One Tariff

This is how you retrieve a particular tariff.

Resource URI

GET /rest/public/tariffs/{masterTariffId}

Request Parameters

Along with the required security parameters, the following parameters are available as part of the request:

Name Type Description
populateProperties Boolean Optional. Populates the properties for the Tariff
populateRates Boolean Optional. Populates the rate details, seasons, and TOU definitions for this Tariff
populateDocuments Boolean Optional. Populates the list of tariff book documents for the Tariff
effectiveOn DateTime Optional. Will only return the version of this tariff that is effective as of this date if populated.
territoryId Long Optional. Will only include this territories rates and rates for all territories if passed in.
bundleRates Boolean When true (false by default) the rates are summarized (bundled).(Optional)
applicableRateOnly Boolean When true (false by default) rate applicability criteria will be applied to the rates. You’ll only get back rates that match the requests rate applicability values, or the default rate applicability value as set on the tariff. (Optional)
lookupVariableRates Boolean When true (false by default) any variable price tariff rates will be looked up and returned on the response. Can work in conjunction with a passed in date range. (Optional)

Example

GET /rest/public/tariffs/504
{
   "status":"success",
   "count":1,
   "type":"Tariff",
   "results":[
      {
         "tariffId":504,
         "masterTariffId":504,
         "priorTariffId":null,
         "lseId":2756,
         "lseName":"Georgia Power Co",
         "distributionLseId":null,
         "tariffCode":"DSM-R-2",
         "tariffName":"Demand Side Management - Residential Rider",
         "tariffType":"RIDER",
         "customerClass":null,
         "territoryId":3114,
         "effectiveDate":"2011-03-01T00:00:00.000-0800",
         "endDate":null,
         "isActive":true,
         "hasNetMetering":true,
         "minMonthlyConsumption":null3
         "maxMonthlyConsumption":null,
         "minMonthlyDemand":null,
         "maxMonthlyDemand":null,
         "billingPeriod":"MONTHLY",
         "properties":null,
         "timeZone":"US/Eastern",
         "currency":"USD",
         "rates":null
      }
   ]
}