Use Time of Uses to retrieve time-of-use schedules that determine when tariff rates apply.
Use Time of Uses to retrieve time-of-use schedules that determine when tariff rates apply.
Many tariffs have prices that depend on when energy is used. Arcadia represents these periods as time of use (TOU). Common TOU labels include ON_PEAK, PARTIAL_PEAK, OFF_PEAK, and CRITICAL_PEAK.
Time of Uses are part of the time-based tariff metadata model. Use Calendars for holidays, billing dates, and dynamic pricing events, and use Seasons for utility-defined seasonal date ranges.
These examples explain the TOU model:
- Within a single time of use, such as on-peak, the price for a tariff is the same.
- A single time of use can have multiple periods. A period is a range of days and times when the TOU applies. For example, each of these is one period:
- Monday through Friday, 12:00 to 14:00
- Monday through Friday, 20:00 to 22:00
Retrieve a time-of-use group by lseId and touGroupId.
Retrieve one time-of-use definition by touId.
Retrieve concrete intervals for a time-of-use group.
Retrieve concrete intervals for one time-of-use definition.
Create a private time-of-use definition for contracted rates or private tariffs.
Data definitions
For a given load-serving entity (LSE), there can be zero to many time-of-use groups. A TOU group contains the time-of-use definitions that cover a full 24-hour day and 7-day week. Use TOU groups to understand an LSE's time-of-use schedule.
Time of Use Group
The TimeOfUseGroup object has the following data structure.
| Name | Type | Description |
|---|---|---|
| lseId | Long | ID of the 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 time of use with a TOU group (foreign key). | |
| lseId | Long | ID of the 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 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. Values are 0 to 6, Monday to Sunday. |
| fromHour | Integer | The hour this period starts. Values are 0 to 23. |
| fromMinute | Integer | The minute this period starts. Values are 0 to 59. |
| toDayOfWeek | Integer | The day of the week this period ends. Values are 0 to 6, Monday to Sunday. |
| toHour | Integer | The hour this period ends. Values are 0 to 23. |
| toMinute | Integer | The minute this period ends. Values are 0 to 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. |
This example shows 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 TOU Group
Retrieve a TOU group using lseId and touGroupId. For endpoint-specific details, see Get TOU Group.
Resource URI
GET /rest/public/timeofuses/{lseId}/{touGroupId}
Request parameters
| Name | Type | Description |
|---|---|---|
| lseId | Long | LSE ID for the TOU group. Required. |
| touGroupId | Long | TOU group ID within the LSE. Required. |
Example
GET /rest/public/timeofuses/2756/1
The JSON listing above is the output from this request.
Get TOU
Retrieve a single time-of-use definition using touId. For endpoint-specific details, see Get TOU.
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 Private TOU
Add a custom time-of-use definition for use with contracted rates or private tariffs. After a private time-of-use definition is created, only the organization that created it can retrieve, modify, or delete it. For endpoint-specific details, see Add Private TOU.
Creating a private TOU definition requires special API permissions. Contact us to find out more.
TOU period coverage
Private TOU definitions must have complete, non-overlapping coverage for the entire year. Every minute of the year must be covered by exactly one TOU period.
Review these rules before creating private TOU definitions.
First, days in a TOU period definition are evaluated individually, not collectively. Consider this 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.
The API does not treat this as one continuous period. Each day is evaluated independently. As a result, this period covers:
- 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
Second, fromHour/toHour and fromMinute/toMinute are inclusive of the from value and exclusive of the to value. For example, to define a TOU period that covers the entire day on Monday, use:
{
"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
}
This covers Monday (0) through Sunday (6), midnight to midnight.
Resource URI
POST /rest/timeofuses
Request parameters
The request parameters map to the data definitions above. You cannot specify touGroupId or touId when adding a private time-of-use definition. These IDs are assigned automatically and returned in the response.
If you use seasonId or calendarId, 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, or time-of-use periods with PUT, specify 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 TOU Group Intervals
Retrieve all intervals for a time-of-use group. You can optionally specify a fromDateTime and toDateTime range. If fromDateTime is omitted, the default is the current time. If toDateTime is omitted, the default is one week after fromDateTime. For endpoint-specific details, see Get TOU Group Intervals.
Resource URI
GET /rest/public/timeofuses/{lseId}/{touGroupId}/intervals
Request parameters
| Name | Type | Description |
|---|---|---|
| fromDateTime | DateTime | Start date and time for the requested intervals in ISO 8601 format. Defaults to the current date and time. Optional. |
| toDateTime | DateTime | End date and time for the requested intervals in ISO 8601 format. Defaults to one week after fromDateTime. Optional. |
Example
GET /rest/public/timeofuses/2756/1/intervals
This abbreviated response shows the interval list returned for the TOU group.
[
{
"touId": 1,
"fromDateTime": "2011-06-10T14:00:00.0-0700",
"toDateTime": "2011-06-10T19:00:00.0-0700",
"touGroupId": 1,
"touName": "On-Peak"
},
{
"touId": 1109,
"fromDateTime": "2011-06-12T19:00:00.0-0700",
"toDateTime": "2011-06-13T14:00:00.0-0700",
"touGroupId": 1,
"touName": "Off-Peak"
}
]
Get TOU Intervals
Retrieve intervals for a single touId. For endpoint-specific details, see Get TOU Intervals.
Resource URI
This endpoint takes a touId and returns only intervals for that TOU.
GET /rest/public/timeofuses/intervals/{touId}
Request parameters
| Name | Type | Description |
|---|---|---|
| fromDateTime | DateTime | Start date and time for the requested intervals in ISO 8601 format. Defaults to the current date and time. Optional. |
| toDateTime | DateTime | End date and time for the requested intervals in ISO 8601 format. Defaults to one week after 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
}