This How-To explains how to upload a time-of-use (TOU) usage profile to an account if you use our Switch or Conduct products. In addition, this How-To explains how to run a calculation with TOU inputs if you use our Signal product. These are useful to know for those times when you have bills for a commercial customer or a residential TOU customer but you don’t have 15-minute interval data.

Prerequisites

Below are the prerequisites you must complete before you upload a TOU usage profile or use our Calculation APIs with TOU inputs.

Create an Account

If you use our Switch or Conduct products, 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/public/tariffs?zipCode=94105&country=US&effectiveOn=2017-11-01&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY

This Get 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 Tariffs request so only TOU tariffs are returned in the response. Here is an example:

GET /rest/public/tariffs?zipCode=94105&country=US&effectiveOn=2017-11-01&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&hasTimeOfUseRates=true

Please visit our documentations on the Tariff API as well as 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/public/tariffs/525?populateRates=true

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
52
                {
                    "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
                            }
                        ]
                    },
    /* more rate data */
                },

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 or Conduct products, 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.

Running a Calculation with TOU Inputs

If you use our Signal product, you will use our On-Demand Cost Calculation endpoint to run calculations with a customer’s TOU data. Our How-To on Running a Calculation to Match a Bill goes over how to use this Calculation endpoint to match a customer’s utility bill. When you have TOU data, you will specify the TOU period for each consumption or demand value under the calculation request’s propertyInputs. This tells the API that the inputs you are passing are for a particular TOU period. The four different options for period are ON_PEAK, PARTIAL_PEAK, OFF_PEAK, and CRITICAL_PEAK.

Example

Below is a sample calculation request for Pacific Gas & Electric’s E-6-TOU tariff with the TOU inputs for consumption.

POST /rest/v1/ondemand/calculate
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "masterTariffId": 525,
    "fromDateTime": "2014-11-17",
    "toDateTime": "2014-12-18",
    "billingPeriod": true,
    "minimums": true,
    "groupBy": "MONTH",
    "detailLevel": "CHARGE_TYPE_AND_TOU",
    "propertyInputs": [ {
        "keyName" : "consumption",
        "unit" : "kWh",
        "period": "PARTIAL_PEAK",
        "dataValue": "70"
    },{
        "keyName" : "consumption",
        "unit" : "kWh",
        "period": "OFF_PEAK",
        "dataValue": "930"
    }
]
}

The request above will calculate the costs for a date range of 11/17/2014 to 12/18/2014 using the kWh values for the PARTIAL_PEAK and OFF_PEAK TOU periods.

If you use our Switch or Conduct products, now you know how to upload a TOU usage profile when you have bills for a commercial customer or a residential TOU customer. If you use our Signal product, now you know how to run a calculation with TOU inputs. Please reach out to support@genability.com if you have any questions.