The tariff history API, as the name hints at, gives you the complete history of revisions for a given tariff, as defined by its masterTariffId. This history includes when the tariff's rates were changed (or versioned) as well as when any riders that are attached to the tariff were also versioned. Finally, we include a summary of the history of any variable pricing indexes associated with the tariff too.
You can call this endpoint for many use cases including displaying version changes to your users. It is also a powerful way to "poll" a master tariff to see if it has changed if you store our tariffs locally in your own database.
As stated the history includes tariff versions, rider versions, and variable prices recorded in lookups, all of which update according to their own schedules. The Tariff History API provides a single point to gather the effective date ranges for a tariff, its riders, and a list of all its variable prices (lookups).
Tariff rates are those rates that are specific to the tariff and change upon the issuance of a new tariff document by the utility.
Rider rates are rates that can be shared across multiple tariffs within the same utility (e.g. Societal Benefits Charge). They may be updated more or less frequently than the tariff itself.
Lookups are frequently changing rates that are recorded as in price schedules (e.g. Fuel Cost Adjustments). Lookups are specified by the variableRateKey property on a Tariff Rate. You can retrieve the schedule of prices from the Lookup API.
Data Definitions
The Tariff History data structure first contains a "header" of summary information about the Tariff, including its masterTariffId and name etc. Following the header is a list of tariffVersions that tell you each time the tariff was versioned over its lifetime (or at least its history in our database). Each version in this list in turn tells you about the date range for the version as well as if and how that version's riders and lookups changed.
Tariff History
The TariffHistory object has the following structure.
| Name | Type | Description |
|---|---|---|
| masterTariffId | Long | Unique Arcadia ID that persists across all revisions of this tariff |
| tariffCode | String | Shortcode that the LSE uses as an alternate name for the tariff |
| tariffName | String | Name of the tariff as used by the LSE |
| lseId | Long | ID of load serving entity this tariff belongs to |
| serviceType | String | Type of service for the tariff. Current values include ELECTRICITY (grid power), SOLAR_PV (for a Solar PPA, Lease or similar) and GAS (Natural Gas) |
| 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, transportationPROPOSED - Utility rates that have been proposed by utilities and approved by utility commissions, but are not yet effective (requires product subscription) |
| initialEffectiveDate | DateTime | Date on which the tariff was first effective. That is the effective date of the first tariff version. |
| closedDate | Date | 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. |
| tariffVersions | List of TariffVersion | A list of all tariff versions for this tariff. |
Tariff Version
The TariffVersion object has the following structure.
| Name | Type | Description |
|---|---|---|
| tariffId | Long | Unique Arcadia ID (primary key) for this tariff |
| 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 |
| lastUpdatedDate | DateTime | The date when this tariff was last updated. This date includes all updates to riders and lookups as well. |
| riderVersions | List of RiderVersion | A list of all rider versions linked in tariff rates on this tariff version. |
| lookupVariableRates | List of PropertyLookupSummary | A list of summaries of lookup variable rates attached to this tariff version. |
Rider Version
The RiderVersion object has the following structure
| Name | Type | Description |
|---|---|---|
| riderId | Long | Unique Arcadia ID that persists across all revisions of this tariff. This is the masterTariffId of the Rider. |
| riderTariffId | Long | Unique Arcadia ID (primary key) for this tariff |
| 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 |
Property Lookup Summary
The PropertyLookupSummary object has the following structure
| Name | Type | Description |
|---|---|---|
| propertyKey | String | The unique name for this property. |
| subPropertyKey | String | sub property name for this property. |
| fromDate | LocalDate | Date Range - from date time |
| toDate | LocalDate | Date Range - from date time |
| lastUpdatedDate | DateTime | The last time this series of lookups was updated |
| count | Integer | The number of lookup entries |
Get Tariff History
Retrieve the tariff history for the specified tariff.
Resource URI
GET /rest/public/tariffs/{masterTariffId}/history
Request Parameters
Only the required security parameters are needed. There are no other request parameters.
Example 1 - Retrieve Tariff History
GET /rest/public/tariffs/81587/history
{
"status": "success",
"count": 1,
"type": "TariffHistory",
"results": [
{
"masterTariffId": 627,
"tariffCode": "BES",
"tariffName": "Residential - Single-Family",
"lseId": 2241,
"serviceType": "ELECTRICITY",
"customerClass": "RESIDENTIAL",
"initialEffectiveDate": "2010-03-09",
"tariffVersions": [
{
"tariffId": 84828,
"effectiveDate": "2011-06-01",
"lastUpdatedDate": "2019-08-27",
"riderVersions": [
{
"riderId": 6747,
"riderTariffId": 3339759,
"effectiveDate": "2019-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3333472,
"effectiveDate": "2019-06-01",
"endDate": "2019-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3321635,
"effectiveDate": "2019-01-01",
"endDate": "2019-06-01"
},
{
"riderId": 3293258,
"riderTariffId": 3328412,
"effectiveDate": "2019-01-01"
},
{
"riderId": 3287872,
"riderTariffId": 3314773,
"effectiveDate": "2018-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3314767,
"effectiveDate": "2018-09-01",
"endDate": "2019-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3310577,
"effectiveDate": "2018-06-01",
"endDate": "2018-09-01"
},
{
"riderId": 3287872,
"riderTariffId": 3308527,
"effectiveDate": "2018-06-01",
"endDate": "2018-09-01"
},
{
"riderId": 3300728,
"riderTariffId": 3300728,
"effectiveDate": "2018-02-01"
},
{
"riderId": 6747,
"riderTariffId": 3300558,
"effectiveDate": "2018-02-01",
"endDate": "2018-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3297275,
"effectiveDate": "2018-01-01",
"endDate": "2018-02-01"
},
{
"riderId": 3293258,
"riderTariffId": 3307302,
"effectiveDate": "2018-01-01",
"endDate": "2019-01-01"
},
{
"riderId": 3295414,
"riderTariffId": 3295414,
"effectiveDate": "2017-10-01",
"endDate": "2017-11-01"
},
{
"riderId": 3293258,
"riderTariffId": 3293258,
"effectiveDate": "2017-10-01",
"endDate": "2018-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3291993,
"effectiveDate": "2017-09-01",
"endDate": "2018-01-01"
},
{
"riderId": 3286649,
"riderTariffId": 3286649,
"effectiveDate": "2017-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3286627,
"effectiveDate": "2017-06-01",
"endDate": "2017-09-01"
},
{
"riderId": 3287872,
"riderTariffId": 3287872,
"effectiveDate": "2017-06-01",
"endDate": "2018-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3284357,
"effectiveDate": "2017-04-01",
"endDate": "2017-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3270275,
"effectiveDate": "2017-01-01",
"endDate": "2017-04-01"
},
{
"riderId": 6747,
"riderTariffId": 3262396,
"effectiveDate": "2016-09-01",
"endDate": "2017-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3262386,
"effectiveDate": "2016-06-01",
"endDate": "2016-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3250824,
"effectiveDate": "2016-01-01",
"endDate": "2016-06-01"
},
{
"riderId": 626,
"riderTariffId": 3285582,
"effectiveDate": "2015-12-09"
},
{
"riderId": 6747,
"riderTariffId": 3236217,
"effectiveDate": "2015-09-01",
"endDate": "2016-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3236207,
"effectiveDate": "2015-06-01",
"endDate": "2015-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3208046,
"effectiveDate": "2015-01-01",
"endDate": "2015-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3196062,
"effectiveDate": "2014-09-01",
"endDate": "2015-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3185857,
"effectiveDate": "2014-06-01",
"endDate": "2014-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3164318,
"effectiveDate": "2014-01-01",
"endDate": "2014-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3162578,
"effectiveDate": "2013-09-01",
"endDate": "2014-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3161687,
"effectiveDate": "2013-07-01",
"endDate": "2013-09-01"
},
{
"riderId": 6747,
"riderTariffId": 3160715,
"effectiveDate": "2013-06-01",
"endDate": "2013-07-01"
},
{
"riderId": 6747,
"riderTariffId": 3155798,
"effectiveDate": "2013-01-01",
"endDate": "2013-06-01"
},
{
"riderId": 6747,
"riderTariffId": 3155206,
"effectiveDate": "2012-11-01",
"endDate": "2013-01-01"
},
{
"riderId": 6747,
"riderTariffId": 3154405,
"effectiveDate": "2012-06-20",
"endDate": "2012-11-01"
},
{
"riderId": 6747,
"riderTariffId": 84823,
"effectiveDate": "2011-06-01",
"endDate": "2012-06-20"
},
{
"riderId": 626,
"riderTariffId": 3153417,
"effectiveDate": "2011-06-01",
"endDate": "2015-12-09"
},
{
"riderId": 84572,
"riderTariffId": 84572,
"effectiveDate": "2011-01-01"
},
{
"riderId": 622,
"riderTariffId": 622,
"effectiveDate": "2010-12-18"
},
{
"riderId": 6583,
"riderTariffId": 6583,
"effectiveDate": "2010-12-18"
},
{
"riderId": 6586,
"riderTariffId": 6586,
"effectiveDate": "2010-11-19"
},
{
"riderId": 6587,
"riderTariffId": 6587,
"effectiveDate": "2010-10-15"
},
{
"riderId": 621,
"riderTariffId": 621,
"effectiveDate": "2010-05-21"
},
{
"riderId": 6591,
"riderTariffId": 6591,
"effectiveDate": "2009-01-15"
}
],
"lookupVariableRates": [
{
"propertyKey": "advancedMeteringResidential2241",
"fromDate": "2011-04-01",
"toDate": "2020-01-01",
"lastUpdatedDate": "2018-01-15",
"count": 8
},
{
"propertyKey": "energyEfficiencyDemandResponseAdjR",
"fromDate": "2011-06-01",
"toDate": "2021-05-01",
"lastUpdatedDate": "2018-12-15",
"count": 21
},
{
"propertyKey": "EnvironmentalCostRecoveryAdjustmentLse2241",
"fromDate": "2011-04-01",
"toDate": "2022-01-01",
"lastUpdatedDate": "2019-07-21",
"count": 34
},
{
"propertyKey": "pjmServiceChargesResidentialNonElectric",
"fromDate": "2011-06-01",
"toDate": "2022-06-01",
"lastUpdatedDate": "2019-05-31",
"count": 38
},
{
"propertyKey": "purchasedElectricityChargeAdjustmentPEA",
"fromDate": "2011-06-01",
"toDate": "2021-10-01",
"lastUpdatedDate": "2019-08-27",
"count": 112
},
{
"propertyKey": "purchasedElectricityChargesResidentialNonElectricNonSummer",
"fromDate": "2011-06-01",
"toDate": "2021-10-01",
"lastUpdatedDate": "2019-08-27",
"count": 40
},
{
"propertyKey": "purchasedElectricityChargesResidentialNonElectricSummer",
"fromDate": "2011-06-01",
"toDate": "2021-10-01",
"lastUpdatedDate": "2019-08-27",
"count": 40
},
{
"propertyKey": "renewableEnergyAdjustmentRateBES2241",
"fromDate": "2011-06-01",
"toDate": "2023-06-01",
"lastUpdatedDate": "2018-09-29",
"count": 7
},
{
"propertyKey": "residentialRealTimePricingProgramCostRecoveryCharge",
"fromDate": "2011-06-01",
"toDate": "2019-07-01",
"lastUpdatedDate": "2016-04-26",
"count": 6
}
]
},
{
"tariffId": 627,
"effectiveDate": "2010-03-09",
"endDate": "2011-06-01",
"lastUpdatedDate": "2019-01-09",
"riderVersions": [
{
"riderId": 626,
"riderTariffId": 626,
"effectiveDate": "2011-02-02",
"endDate": "2011-06-01"
},
{
"riderId": 84572,
"riderTariffId": 84572,
"effectiveDate": "2011-01-01"
},
{
"riderId": 6583,
"riderTariffId": 6583,
"effectiveDate": "2010-12-18"
},
{
"riderId": 622,
"riderTariffId": 622,
"effectiveDate": "2010-12-18"
},
{
"riderId": 6586,
"riderTariffId": 6586,
"effectiveDate": "2010-11-19"
},
{
"riderId": 6587,
"riderTariffId": 6587,
"effectiveDate": "2010-10-15"
},
{
"riderId": 621,
"riderTariffId": 621,
"effectiveDate": "2010-05-21"
},
{
"riderId": 6747,
"riderTariffId": 6747,
"effectiveDate": "2010-03-09",
"endDate": "2011-06-01"
},
{
"riderId": 6591,
"riderTariffId": 6591,
"effectiveDate": "2009-01-15"
}
],
"lookupVariableRates": [
{
"propertyKey": "advancedMeteringResidential2241",
"fromDate": "2010-12-18",
"toDate": "2011-10-01",
"lastUpdatedDate": "2016-04-26",
"count": 3
},
{
"propertyKey": "energyEfficiencyDemandResponseAdjR",
"fromDate": "2010-10-15",
"toDate": "2011-11-01",
"lastUpdatedDate": "2014-06-01",
"count": 2
},
{
"propertyKey": "EnvironmentalCostRecoveryAdjustmentLse2241",
"fromDate": "2010-11-19",
"toDate": "2011-09-01",
"lastUpdatedDate": "2014-03-31",
"count": 2
},
{
"propertyKey": "pjmServiceChargesResidentialNonElectric",
"fromDate": "2010-05-21",
"toDate": "2011-09-01",
"lastUpdatedDate": "2014-05-13",
"count": 2
},
{
"propertyKey": "purchasedElectricityChargeAdjustmentPEA",
"fromDate": "2011-01-01",
"toDate": "2011-07-01",
"lastUpdatedDate": "2014-03-02",
"count": 6
},
{
"propertyKey": "purchasedElectricityChargesResidentialNonElectricNonSummer",
"fromDate": "2011-06-01",
"toDate": "2011-09-01",
"lastUpdatedDate": "2014-05-13",
"count": 1
},
{
"propertyKey": "purchasedElectricityChargesResidentialNonElectricSummer",
"fromDate": "2010-12-18",
"toDate": "2011-09-01",
"lastUpdatedDate": "2016-04-26",
"count": 2
}
]
}
]
}
]
}