This How-To explains how to upload a usage profile with time-of-use (TOU) reading data to an account. This is useful for those times when you have bills for a commercial customer (or a TOU residential customer) but you don’t have 15-minute interval data.

Prerequisites

Create an Account

Before you can upload a usage profile, you’ll need to create an Account to associate it with.

Select a TOU Tariff

Time-of-use data doesn’t make much sense if the account is not on a TOU tariff. To be able to upload TOU data, you’ll have to make sure that your tariff has TOU periods. You can see if it does by checking whether its hasTimeOfUseRates property has a value of true.

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, you need to make sure that you only upload data for the correct TOU periods during the correct time periods. For example, you can’t upload ON_PEAK data for PG&E’s E-6 tariff during the month of January, because there is no ON_PEAK period during January in PG&E territory.

To see which TOU periods are valid for a tariff, you’ll need to parse that tariff’s rates. To get those details, you can make the following call to the API:

GET /rest/public/tariffs/{masterTariffId}?populateRates=true

That 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 TimeOfUsePeriod objects – will define the dates and times during which each TOU period is valid.

The next step is to get the full definition of a tariff’s TOU periods. To do that, you can use the TimeOfUse endpoint. This endpoint will return, for a given LSE and TOU group, the start and end dates of each TOU period, the type of TOU period, and the seasons during which that period is active. You can get the lseId and touGroupId from the rates on a particular tariff.

Let’s use E-6 as an example. after we make the call to get the tariff’s rates, we’ll see that each of the TOU rate objects on PG&E’s E-6 tariff looks like this:

{
    "tariffRateId": 17316628,
    "tariffId": 3215823,
    "tariffSequenceNumber": 1,
    "rateGroupName": "Generation",
    "rateName": "Generation Charge - Summer Peak",
    "fromDateTime": "2015-03-01T00:00:00-08:00",
    "toDateTime": null,
    "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
        }]
    }

    /* more rate data */

}

This rate has a touGroupId of 1 and, because it’s PG&E, we know that it has an lseId of 734. Now, to get the full TOU definition for this tariff, we would use the following call:

GET /public/timeofuses/734/1

This call returns back a bunch of TimeOfUse objects that look like this:

{
    "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 some data.

Uploading a TOU Profile

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 time-of-use 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 PDP in PG&E territory or CPP in SCE territory.

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:

{
   "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":"ON_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 - 12/18/2014. For this date range, there are two TOU periods, ON_PEAK and OFF_PEAK, in which our customer is using 70 kWh and 930 kWh, respectively.