Loading Time-of-Use Reading Data
This How-To explains how to upload a time-of-use (TOU) usage profile to an account. This is useful to know for those times when you have bills for a residential TOU customer but you don’t have 15-minute interval data.
You’ll need to create an account for your customer before you can upload a usage profile. Please visit our Add an Account documentation to learn how to do this.
Select a TOU Tariff
To be able to upload TOU data or to run a TOU calculation, you’ll have to make sure that you select a tariff with TOU periods.
When you retrieve a list of tariffs, you can determine if a tariff has TOU rates by checking if hasTimeOfUseRates is set to true. Here is an example of retrieving tariffs for a residential customer located in San Francisco, CA 94105:
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?effectiveOn=2017-11-01
This Get Account Tariffs request will include Pacific Gas & Electric’s “Residential - Time of Use” tariff (E-6-TOU) in the response. You know this tariff has TOU rates since hasTimeOfUseRates is set to true:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"tariffId": 3288164,
"masterTariffId": 525,
"tariffCode": "E-6-TOU",
"tariffName": "Residential - Time of Use (Closed)",
"lseId": 734,
"lseName": "Pacific Gas & Electric Co",
"priorTariffId": 3278528,
"tariffType": "ALTERNATIVE",
"customerClass": "RESIDENTIAL",
"customerCount": 7431,
"customerLikelihood": 0.13,
"territoryId": 807,
"effectiveDate": "2017-07-01",
"endDate": null,
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": true,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": true,
"isActive": true
},
You can also add the parameter hasTimeOfUseRates to the Get Account Tariffs request so only TOU tariffs are returned in the response. Here is an example:
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?effectiveOn=2017-11-01&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&hasTimeOfUseRates=true
Please visit our How-To on Selecting the Right Utility & Tariff for more information on how to select a TOU tariff.
Determine the Appropriate TOU Periods
TOU period definitions are different for each utility and, sometimes, even for different tariffs in the same utility. When creating a TOU profile or running a calculation with TOU inputs, you need to make sure that you use the correct TOU periods during the correct time periods for the data you provide to the API. For example, if you upload ON_PEAK data for Pacific Gas & Electric’s E-6-TOU tariff during the month of January, this data will be ignored because there is no ON_PEAK period during January in Pacific Gas & Electric’s territory.
To see which TOU periods are valid for a tariff, you’ll need to parse the tariff’s rates using the Tariff API. Here is the sample request to retrieve the tariff rates for Pacific Gas & Electric’s E-6-TOU:
GET /rest/v1/accounts/pid/{providerAccountId}/rates
This query will return the tariff fully populated with all of the details about each rate component. On some of those rates, there will be TimeOfUse objects. Collectively, these TOU objects – and their associated Season and TOU Periods objects – will define the dates and times during which each TOU period is valid.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
"tariffRateId": 17876265,
"tariffId": 3288164,
"tariffSequenceNumber": 18,
"rateGroupName": "Generation",
"rateName": "Generation Charge - Summer Peak",
"fromDateTime": "2017-07-01T00:00:00-07:00",
"toDateTime": null,
"season": {
"seasonId": 280,
"lseId": 734,
"seasonGroupId": 1,
"seasonName": "Summer",
"seasonFromMonth": 5,
"seasonFromDay": 1,
"seasonToMonth": 10,
"seasonToDay": 31
},
"timeOfUse": {
"touId": 772,
"touGroupId": 1,
"lseId": 734,
"touName": "Summer Peak",
"calendarId": null,
"isDynamic": false,
"season": {
"seasonId": 280,
"lseId": 734,
"seasonGroupId": 1,
"seasonName": "Summer",
"seasonFromMonth": 5,
"seasonFromDay": 1,
"seasonToMonth": 10,
"seasonToDay": 31
},
"touType": "ON_PEAK",
"touPeriods": [
{
"touPeriodId": 671,
"touId": 772,
"fromDayOfWeek": 0,
"fromHour": 13,
"fromMinute": 0,
"toDayOfWeek": 4,
"toHour": 19,
"toMinute": 0,
"calendarId": null
}
]
},
},
In the response above, the “Generation Charge - Summer Peak” rate has a touGroupId of 1 and a lseId of 734. You can use the IDs of the LSE and TOU group to get the full definition of a tariff’s TOU periods through the Time Of Use endpoint. This endpoint will return the start and end dates of each TOU period, the type of TOU period, and the seasons during which that period is active. Here is the request to get the full TOU definition of Pacific Gas & Electric’s E-6-TOU tariff:
GET /public/timeofuses/734/1
The call returns back a bunch of TimeOfUse objects that look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"touId": 772,
"touGroupId": 1,
"lseId": 734,
"touName": "Summer Peak",
"calendarId": null,
"isDynamic": false,
"season": {
"seasonId": 280,
"lseId": 734,
"seasonGroupId": 1,
"seasonName": "Summer",
"seasonFromMonth": 5,
"seasonFromDay": 1,
"seasonToMonth": 10,
"seasonToDay": 31
},
"touType": "ON_PEAK",
"touPeriods": [
{
"touPeriodId": 671,
"touId": 772,
"fromDayOfWeek": 0,
"fromHour": 13,
"fromMinute": 0,
"toDayOfWeek": 4,
"toHour": 19,
"toMinute": 0
}]
}
This TOU period definition is just like the definitions that we found on the tariff itself, but now they’re all grouped together. We no longer have to extract them from the individual rates for the tariff that we’re analyzing. Now that you have all of the data, you can determine which TOU periods are available and when they’re active. Once that’s done, you’ll be ready to upload TOU data or run calculations with TOU inputs.
Uploading a TOU Profile
If you use our Switch product, you will use our Usage Profile endpoint to upload your customer’s data before running an Account Cost Calculation or Savings Analysis. Uploading a profile with TOU data is very similar to uploading a profile with interval data, with one slight tweak: you have to set the touType field on the Reading Data objects that you pass in with your profile. This tells the API that the data you are uploading covers a particular TOU period for the specified interval.
There are four different options for the touType field: "ON_PEAK", "PARTIAL_PEAK" (also known as “mid-peak” for some utilities), "OFF_PEAK", and "CRITICAL_PEAK". The critical peak period is for energy used during demand response events under programs like Peak Day Pricing for Pacific Gas & Electric or Critical Peak Pricing for Southern California Edison.
Example
As an example, we’ll upload a very simple profile with TOU usage data. We can use the following request:
POST /rest/v1/profiles
with the following request body:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"providerAccountId":"YOUR_ACCOUNT_ID",
"providerProfileId":"YOUR_PROFILE_ID",
"profileName":"Residential TOU Profile",
"description":"Residential Electricity TOU Profile",
"isDefault":true,
"serviceTypes":"ELECTRICITY",
"sourceId":"ReadingEntry",
"readingData":[
{
"fromDateTime":"2014-11-17",
"toDateTime":"2014-12-18",
"quantityUnit":"kWh",
"quantityValue":"70",
"touType":"PARTIAL_PEAK"
},
{
"fromDateTime":"2014-11-17",
"toDateTime":"2014-12-18",
"quantityUnit":"kWh",
"quantityValue":"930",
"touType":"OFF_PEAK"
}
]
}
Make sure to replace "YOUR_ACCOUNT_ID" and "YOUR_PROFILE_ID" with your own account and profile IDs, respectively.
The profile that we just uploaded represents the data for the period 11/17/2014 to 12/18/2014. For this date range, there are two TOU periods, PARTIAL_PEAK and OFF_PEAK, in which our customer is using 70 kWh and 930 kWh, respectively.
After uploading this TOU profile to your customer’s account, you can use this profile to calculate your customer’s costs using the Account Cost Calculation or Savings Analysis endpoints.