Time of Use

Overview

Many tariffs have pricing that depends on the time of day the energy is being used. We call these times the time of use (TOU) for a tariff. The most common examples are "on peak" and "off peak". Some examples here may help:

  • Within a single time of use, e.g. on peak, the price for a tariff will always be the same.
  • Within a single time of use, e.g. on peak, you may have multiple periods. A period is a range of days and times that this TOU applies to. For example, each of these are one period:
    • Monday - Friday 12:00-14:00
    • Monday - Friday 20:00-22:00

Data Definitions

For a given load serving entity, there can be none to many time of use groups. A TOU group contains all the time of uses that make up a full 24 hour day and 7 day week. This is a good way to see at a glance what the LSE's time of use schedule looks like.

Time of Use Group

The TimeOfUsePeriod object has the following data structure.

Name Type Description
lseId Long ID of load serving entity this time of use group belongs to
touGroupId Long Genability ID (primary key) for this time of use group. This is unique within the LSE, not across LSEs so you will always need to specify the LSE ID when requested a TOU group.
timeOfUses List of Time of Use The times of use that comprise this time of use group.

Time of Use

The TimeOfUse object has the following data structure.

Name Type Fields Description
touId Long Unique Genability ID (primary key) for each time of use. This is unique across all LSEs.
touGroupId Long Associates the rate with a tariff (foreign key)
lseId Long ID of load serving entity this time of use group belongs to
touName String Display name of this TOU. Example: "On Peak"
calendarId Long The ID of the calendar of events and holidays that this TOU should apply to, regardless of the TOU period definitions. For example, a calendar could be used to specify that the entirety of Labor Day should be treated as OFF_PEAK, even though it falls on a Summer weekday.
season Season The Season object that this time of use applies to (if applicable).
isDynamic Boolean Indicates if the timeOfUse includes a calendar whose dates change from year-to-year. For example Critical Peak timeOfUse objects are dynamic, since the dates/hours change from year to year.
touPeriods List of Period The periods that comprise this time of use.
privacy String E Indicates whether this TimeOfUse is PUBLIC or PRIVATE. Only TOU groups created by your organization will be returned as PRIVATE.

Period

The Period object has the following data structure.

Name Type Description
touPeriodId Long The unique Genability ID of this period. This is unique across all LSE's.
touId Long The ID of the parent time of use this period belongs to (foreign key).
fromDayOfWeek Integer The day of the week this period starts. 0-6 Monday-Sunday.
fromHour Integer The hour this period starts. 0-23.
fromMinute Integer The minute this period starts. 0-59.
toDayOfWeek Integer The day of the week this period ends. 0-6 Monday-Sunday.
toHour Integer The hour this period ends. 0-23.
toMinute Integer The minute this period ends. 0-59.

Interval

The Interval object has the following data structure.

Name Type Description
touId Long The unique ID (foreign key) of the time of use this Interval applies to.
touName String The name of the time of use this interval applies to. e.g. "On Peak".
touGroupId Long The time of use group ID this interval applies to. This ID is unique within an LSE.
fromDateTime DateTime The day and time this interval starts, in ISO 8601 format.
toDateTime DateTime The day and time this Interval ends, in ISO 8601 format.

Here's an example in JSON of a fully populated time of use group:

{
  "lseId":2756,
  "touGroupId":1,
  "timeOfUses":[
     {
        "touId":1,
        "touGroupId":1,
        "lseId":2756,
        "touName":"On-Peak",
        "calendarId":null,
        "season":null,
        "isDynamic":false,
        "touPeriods":[
           {
              "touPeriodId":1,
              "touId":1,
              "fromDayOfWeek":0,
              "fromHour":14,
              "fromMinute":0,
              "toDayOfWeek":4,
              "toHour":19,
              "toMinute":0
           }
        ]
     },
     {
        "touId":2,
        "touGroupId":1,
        "lseId":2756,
        "touName":"Off-Peak",
        "calendarId":null,
        "season":null,
        "isDynamic":false,
        "touPeriods":[
           {
              "touPeriodId":2,
              "touId":2,
              "fromDayOfWeek":0,
              "fromHour":19,
              "fromMinute":0,
              "toDayOfWeek":4,
              "toHour":14,
              "toMinute":0
           }
        ]
     },
     {
        "touId":1109,
        "touGroupId":1,
        "lseId":2756,
        "touName":"Off-Peak",
        "calendarId":null,
        "season":null,
        "isDynamic":false,
        "touPeriods":[
           {
              "touPeriodId":36,
              "touId":1109,
              "fromDayOfWeek":0,
              "fromHour":19,
              "fromMinute":0,
              "toDayOfWeek":6,
              "toHour":14,
              "toMinute":0
           }
        ]
     },
     {
        "touId":1192,
        "touGroupId":1,
        "lseId":2756,
        "touName":"Off-Peak",
        "calendarId":null,
        "season":null,
        "isDynamic":false,
        "touPeriods":[
           {
              "touPeriodId":38,
              "touId":1192,
              "fromDayOfWeek":0,
              "fromHour":0,
              "fromMinute":0,
              "toDayOfWeek":6,
              "toHour":23,
              "toMinute":0
           }
        ]
     }
  ]
}

Operations

Get a Time of Use Group

This allows you to retrieve a particular TOU group using its touGroupId and the lseId.

Resource URI

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

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
lseId Long Get a TOU group for a specific LSE
touGroupId Long Get a TOU group by its ID (required when LSE ID is provided)

Example

GET /rest/public/timeofuses/2756/1

The JSON listing above is the output from this example.

Add a Private TOU Definition

This allows you to add your own, custom time of use definition to the Genability database for use with contracted rates or private tariffs. Once added, a private time of use definition can be only be retrieved, modified, or deleted by the organization that created it.

Creating a private TOU definition requires special API permissions. Contact us to find out more.

TOU Period Coverage

Private TOU definitions are required to have complete, non-overlapping coverage of the entire year; every minute of the year must be covered by exactly one TOU period. Due to this requirement, there are a few things to watch out for when creating private TOU definitions.

First, the days in a TOU period definition are not considered collectively, but rather individually. As an example, consider the following TOU period definition:

{ 
    "fromDayOfWeek": 0, 
    "toDayOfWeek": 2,
    "fromHour": 17,
    "toHour": 8,
    "fromMinute": 0,
    "toMinute": 0
}

One possible interpretation of this TOU period could be the following:

  1. Monday at 5 PM straight through to Wednesday at 8 AM.

However, this is not how the API treats this TOU period. Instead, each day is considered in isolation. As a result, this period will actually cover the following times:

  1. Monday, midnight to 8 AM and 5 PM to midnight
  2. Tuesday, midnight to 8 AM and 5 PM to midnight
  3. Wednesday, midnight to 8 AM and 5 PM to midnight

Secondly, fromHour/toHour and fromMinute/toMinute are defined to be inclusive of the from portion and exclusive of the to portion. For example, if you wanted to define a TOU period that covered the entire day on Monday, the TOU period would look like this:

{ 
    "fromDayOfWeek": 0, 
    "toDayOfWeek": 0,
    "fromHour": 0,
    "toHour": 0,
    "fromMinute": 0,
    "toMinute": 0
}

This definition includes 12:00 AM on Monday all the way through, but not including, 12:00 AM on Tuesday morning. Using a value of 1 in the toDayOfWeek field would change this TOU period to cover from midnight to midnight on both Monday and Tuesday.

Putting this all together, a TOU period definition that covered every day for the entire week would look like the following:

{ 
    "fromDayOfWeek": 0, 
    "toDayOfWeek": 6,
    "fromHour": 0,
    "toHour": 0,
    "fromMinute": 0,
    "toMinute": 0
}

That is, Monday (0) through Sunday (6), midnight to midnight.

Resource URI

POST /rest/timeofuses/

Request Parameters

The request parameters map to the data definitions defined above. You cannot specify the touGroupId or touId when adding a private time of use definition, those are auto-assigned and returned in the call response. If you use a seasonId or calendarId, you must select from public seasons and calendars. The Genability API does not support user-customizable seasons or calendars.

When updating the time of use group, time of use and time of use periods via a PUT, you will need to specify the touGroupId and touId.

Example

POST /rest/timeofuses/
{
   "lseId": 100277,
   "timeOfUses": [
     {
       "touName": "Summer On-Peak",
       "calendarId": null,
       "seasonId": 165,
       "touType": "ON_PEAK",
       "touPeriods": [
         {
           "fromDayOfWeek": 0,
           "fromHour": 12,
           "fromMinute": 0,
           "toDayOfWeek": 4,
           "toHour": 19,
           "toMinute": 0
         }
       ]
     },
     {
       "touName": "Summer Off-Peak",
       "calendarId": 127,
       "seasonId": 165,
       "touType": "OFF_PEAK",
       "touPeriods": [
         {
           "fromDayOfWeek": 0,
           "fromHour": 19,
           "fromMinute": 0,
           "toDayOfWeek": 4,
           "toHour": 12,
           "toMinute": 0
         },
         {
           "fromDayOfWeek": 5,
           "fromHour": 0,
           "fromMinute": 0,
           "toDayOfWeek": 6,
           "toHour": 0,
           "toMinute": 0
         }
       ]
     },
     {
       "touName": "Winter On-Peak",
       "calendarId": null,
       "isDynamic": false,
       "seasonId": 166,
       "touType": "ON_PEAK",
       "touPeriods": [
         {
           "fromDayOfWeek": 0,
           "fromHour": 12,
           "fromMinute": 0,
           "toDayOfWeek": 4,
           "toHour": 19,
           "toMinute": 0
         }
       ]
     },
     {
       "touName": "Winter Off-Peak",
       "calendarId": 127,
       "isDynamic": false,
       "seasonId": 166,
       "touType": "OFF_PEAK",
       "touPeriods": [
         {
           "fromDayOfWeek": 0,
           "fromHour": 19,
           "fromMinute": 0,
           "toDayOfWeek": 4,
           "toHour": 12,
           "toMinute": 0
         },
         {
           "fromDayOfWeek": 5,
           "fromHour": 0,
           "fromMinute": 0,
           "toDayOfWeek": 6,
           "toHour": 0,
           "toMinute": 0
         }
       ]
     }
   ]
 }

Get a Group's Intervals

This returns all the intervals for a time of use group for an optionally specified from and to date and time range. Defaults to current time if fromDateTime is not specified and to a one week look ahead window if toDateTime is not specified.

Resource URI

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

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
fromDateTime DateTime ISO 8601 format for the starting date and time of the requested intervals. Defaults to current day and time if not specified. (Optional)
toDateTime DateTime ISO 8601 format for the ending date and time of the requested intervals. Defaults to one week after the fromDateTime. (Optional)
Example
GET /rest/public/timeofuses/2756/1/intervals
[
   {
         "touId":1,
         "fromDateTime":"2011-06-10T14:00:00.0-0700",
         "toDateTime":"2011-06-10T19:00:00.0-0700",
         "touGroupId":1,
         "touName":"On-Peak"
      },

      /* truncated for length */

      {
         "touId":1109,
         "fromDateTime":"2011-06-12T19:00:00.0-0700",
         "toDateTime":"2011-06-13T14:00:00.0-0700",
         "touGroupId":1,
         "touName":"Off-Peak"
      },
]