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 | 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 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
}
]
}
]
}
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 Single 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
}