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

TOU behavior examples:

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

Related endpoints

Get TOU Group

Retrieve a Time of Use group by lseId and touGroupId.

Get TOU by ID

Retrieve one Time of Use definition by touId.

List TOU Group Intervals

Expand a TOU group into concrete date-time intervals.

List TOU Intervals

Return intervals for a specific touId.

Create Private TOU Definition

Create a private Time of Use definition with special API permissions.

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	Arcadia 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 requesting 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 Arcadia 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).
touType	String		The type of TOU period, which is one of SUPER_OFF_PEAK, OFF_PEAK, PARTIAL_PEAK, ON_PEAK, SUPER_ON_PEAK or CRITICAL_PEAK.
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 Arcadia ID of this period. This is unique across all LSEs.
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
           }
        ]
     }
  ]
}

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.

Get a Time of Use Definition

This allows you to retrieve a single Time of Use definition using the touId.

Resource URI

GET /rest/public/timeofuses/{touId}

Example

GET /rest/public/timeofuses/50959

{
    "status": "success",
    "count": 1,
    "type": "TimeOfUse",
    "results": [
        {
            "touId": 50959,
            "touGroupId": 97,
            "lseId": 1071,
            "touName": "Summer Off-Peak",
            "calendarId": 4,
            "isDynamic": false,
            "season": null,
            "touType": "PARTIAL_PEAK",
            "touPeriods": [
                {
                    "touPeriodId": 59138,
                    "touId": 50959,
                    "fromDayOfWeek": 0,
                    "fromHour": 21,
                    "fromMinute": 0,
                    "toDayOfWeek": 4,
                    "toHour": 0,
                    "toMinute": 0,
                    "calendarId": null
                },
                {
                    "touPeriodId": 59139,
                    "touId": 50959,
                    "fromDayOfWeek": 0,
                    "fromHour": 6,
                    "fromMinute": 0,
                    "toDayOfWeek": 4,
                    "toHour": 16,
                    "toMinute": 0,
                    "calendarId": null
                },
                {
                    "touPeriodId": 59140,
                    "touId": 50959,
                    "fromDayOfWeek": 5,
                    "fromHour": 21,
                    "fromMinute": 0,
                    "toDayOfWeek": 6,
                    "toHour": 0,
                    "toMinute": 0,
                    "calendarId": 4
                },
                {
                    "touPeriodId": 59141,
                    "touId": 50959,
                    "fromDayOfWeek": 5,
                    "fromHour": 14,
                    "fromMinute": 0,
                    "toDayOfWeek": 6,
                    "toHour": 16,
                    "toMinute": 0,
                    "calendarId": 4
                }
            ]
        }
    ]
}

Add a Private TOU Definition

This allows you to add your own, custom time of use definition to the Arcadia database for use with contracted rates or private tariffs. Once added, a private time-of-use definition can 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:

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 cover the following times:

Monday, midnight to 8 AM and 5 PM to midnight
Tuesday, midnight to 8 AM and 5 PM to midnight
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 Arcadia 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"
      },
]

Get a TOU's Intervals

This is a variation on the intervals request that takes a touId and returns intervals only for that touId.

Resource URI

This is a variation that additionally takes a touId and returns intervals only for that touId.

GET /rest/public/timeofuses/intervals/{touId}

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/intervals/1?fromDateTime=2016-09-19T17:19:08-04:00&toDateTime=2016-09-19T19:00:00-04:00

{
  "status": "success",
  "count": 1,
  "type": "TimeOfUseIntervals",
  "results": [
    {
      "touId": 1,
      "touName": "Summer On-Peak",
      "touGroupId": 1,
      "fromDateTime": "2016-09-19T17:19:08-04:00",
      "toDateTime": "2016-09-19T19:00:00-04:00",
      "touType": "ON_PEAK",
      "calendarId": null
    }
  ],
  "pageStart": 0,
  "pageCount": 0
}