Load Time-of-Use (TOU) Readings into a Profile or Calculation

Select a time-of-use tariff, identify valid TOU periods, and upload TOU readings to a usage profile for calculations or savings analyses.

Prerequisites

Create an account for the customer. Read Add an Account to learn how to do this.
Confirm the account’s utility and electricity tariff.
Collect TOU usage totals by billing period and TOU period.

TOU readings workflow

Select an electricity tariff where hasTimeOfUseRates=true.
Retrieve tariff rates and find the timeOfUse objects.
Use lseId and touGroupId to retrieve full TOU period definitions.
Confirm which touType values are valid for the reading date range.
Upload readings with the correct touType.
Use the profile in an Account Cost Calculation or Savings Analysis.

A TOU reading is usage for a specific time-of-use period during a billing interval. The touType field tells Switch which TOU bucket the usage belongs to, such as ON_PEAK, PARTIAL_PEAK, or OFF_PEAK.

Select a TOU tariff

To upload TOU data or run a TOU calculation, 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. This response snippet has been shortened to show the relevant tariff fields:

{  
    "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  
}

In this response, note:

hasTimeOfUseRates=true confirms that the tariff has TOU rates.
lseId identifies the utility.
masterTariffId identifies the tariff family.

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

Read Select the Right Utility and 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, for different tariffs in the same utility. When creating a TOU profile or running a calculation with TOU inputs, use TOU periods that are valid for the dates covered by your readings.

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.

Upload TOU readings only for TOU periods that are valid during the reading date range. If you upload ON_PEAK usage for a month where the tariff has no ON_PEAK period, that usage can be ignored.

To see which TOU periods are valid for a tariff, you'll need to parse the tariff's rates using the Tariffs API. Use this request to retrieve the tariff rates for Pacific Gas & Electric's E-6-TOU:

GET /rest/v1/accounts/pid/{providerAccountId}/rates

This query returns the tariff with details about each rate component. Some rates include TimeOfUse objects.

Together, these TOU objects and their associated Season and TOU Period objects define the dates and times during which each TOU period is valid.

This response snippet has been shortened to show the timeOfUse object on a tariff rate:

{  
    "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 this object, note:

touGroupId and lseId are used to retrieve the full TOU definition.
touType is the value you use when uploading readings.
season defines when the period applies.
touPeriods defines the days and hours within that season.

Field	Why it matters
`lseId`	Identifies the utility.
`touGroupId`	Groups TOU periods for lookup.
`touType`	Value used on uploaded readings.
`season`	Defines active months and days.
`touPeriods`	Defines active days and hours.

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.

Request template:

GET /public/timeofuses/{lseId}/{touGroupId}

Here is an example request to get the full TOU definition of Pacific Gas & Electric's E-6-TOU tariff:

GET /public/timeofuses/734/1

The call returns 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 like the definitions found on the tariff itself, but grouped together. You no longer have to extract them from the individual rates for the tariff that you're analyzing.

Now that you have all of the data, determine which TOU periods are available and when they're active. Once that's done, you're ready to upload TOU data or run calculations with TOU inputs.

Use the season object to determine the active date range and touPeriods to determine the active days and hours within that season.

Upload a TOU profile

Use the Usage Profile endpoint to upload your customer’s TOU data before running an Account Cost Calculation or Savings Analysis.

Uploading a profile with TOU data is similar to uploading a profile with interval data. The key difference is that each Reading Data object must include touType. This tells the API which TOU period the reading covers for the specified interval.

When uploading TOU readings:

Use serviceTypes: "ELECTRICITY".
Use sourceId: "ReadingEntry".
Add one readingData object per billing period and TOU period.
Set touType to a valid value for the reading date range.

There are four different options for the touType field:

`touType`	Meaning
`ON_PEAK`	Peak period usage.
`PARTIAL_PEAK`	Mid-peak or partial-peak usage.
`OFF_PEAK`	Off-peak usage.
`CRITICAL_PEAK`	Critical peak usage during demand response or critical peak pricing events.

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 TOU profile

As an example, we'll upload a very simple profile with TOU usage data. We can use the following request:

POST /rest/v1/profiles

Use 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":"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.

Multiple TOU readings can share the same fromDateTime and toDateTime when each reading represents a different TOU bucket for the same billing period.

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.

Next steps

After uploading a TOU profile, you can: