A Calendar defines important dates that are associated with tariffs, including billing dates, holiday schedules (which are typically off-peak and thus have lower rates), and “dynamic” events such as smart days, critical peaks and system peaks. The Calendar endpoints allow you to query what calendars are available and what dates they specify.

Data Definitions

Calendar has a resource type of Calendar. An individual date has a resource type of CalendarDate. Each calendar has a list of events on them that denote the type of dates on the calendar. For example “billing period end” would be an event on a billing period calendar, and Easter Sunday would be an event on a holiday calendar. Then Easter Sunday 2015 is actually a calendar date, as is the specific billing period end date of June 12, 2015.

Calendar

A Calendar is a simple object that has the following data structure.

Name Type Fields Description
calendarId Long M A unique ID for each calendar
calendarName String M A descriptive name for the calendar. If the utility gives it a name (they typically do for billing cycles) it will be that. Otherwise its indicative of its purpose (e.g. “Holidays”).
calendarType String M Indicates the type of dates in this calendar. Values are HOLIDAY (e.g. 4th July), BILLING (for billing periods) and PRICING_PERIOD for dynamic pricing events like critical peaks.
lseId Long M The ID of the utility (LSE) that the calendar belongs to.
events List of CalendarEvent   A list of the types of events on this calendar (See below for CalendarEvent structure). This is only populated on Get Calendar, not on Get Calendars.

Each CalendarEvent item in the events list above has the following fields:

Name Type Fields Description
calendarEventId Long M A unique ID for each calendar event
calendarEventName String M Short, descriptive name for the event
lseId Long M The ID of the utility (LSE) that the calendar belongs to.
calendarEventType String M Either HOLIDAY, BILLING or PRICING_PERIOD
dateDefinitionType String E FIXED_DATE occurs on the same date, MANUAL is non-deterministic, FLOATING_DATE floats (e.g. first Monday of the month), and EASTER_DATE relates to the easter calendar
locale String   ISO Country Code of the locales date (e.g. US).
seededUntil Date   When the underlying dates for this event are populated through to.
fixedMonth Integer E For fixed dates, the month of year.
fixedDay Integer E For fixed dates, the day of month.
dayOfWeek Integer E For floating dates, the day of the week.
weekOfMonth Integer E For floating dates, the week of the month.
adjustment Integer E An adjustment value, uses for various date types.

Calendar Date

The actual dates are provided in the CalendarDate resource type.

Name Type Fields Description
eventDateId Long M A unique ID for this specific calendar date
subKey String M Typically null. Populated for System Peak events
eventName Long M Short descriptive name of the event
startDateTime DateTime M Date and time the event date starts. Typically midnight, but not always.
endDateTime DateTime M Typically null, but populated when the calendar date is for a period other than 1 whole day
calendarEventId Long M The ID of the dates calendar event
lseId Long M The utility that the calendar date belongs to

Get Calendars

This endpoint returns all of the calendars that match the passed in request arguments.

Resource URI

GET /rest/public/calendars/

Request Parameters

Name Type Description
lseId Long lseId (Optional).
calendarType String Type of calendar. Can be either HOLIDAY, BILLING, or PRICING_PERIOD (Optional).

Example 1 : Get all the Holidays Calendars for a Utility

GET /rest/public/calendars?lseId=734&calendarType=HOLIDAY
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
   "status": "success",
   "count": 5,
   "type": "Calendar",
   "results": [
      {
         "calendarId": 2,
         "calendarName": "Holidays",
         "calendarType": "HOLIDAY",
         "lseId": 734
      },
      {
         "calendarId": 86,
         "calendarName": "Holidays",
         "calendarType": "HOLIDAY",
         "lseId": 734
      },
      {
         "calendarId": 634,
         "calendarName": "Holiday-Peaks",
         "calendarType": "HOLIDAY",
         "lseId": 734
      },
      {
         "calendarId": 646,
         "calendarName": "Holidays - Summer",
         "calendarType": "HOLIDAY",
         "lseId": 734
      },
      {
         "calendarId": 647,
         "calendarName": "Holidays - Winter",
         "calendarType": "HOLIDAY",
         "lseId": 734
      }
   ],
   "pageStart": 0,
   "pageCount": 25
}

Example 2 : Get all the Billing Cycle Calendars for a Utility

GET /rest/public/calendars?lseId=734&calendarType=BILLING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "status": "success",
   "count": 21,
   "type": "Calendar",
   "results": [
      {
         "calendarId": 705,
         "calendarName": "Read Cycle B",
         "calendarType": "BILLING",
         "lseId": 734
      },

    /* edited for length */

      {
         "calendarId": 726,
         "calendarName": "Read Cycle Z",
         "calendarType": "BILLING",
         "lseId": 734
      }
   ],
   "pageCount": 25,
   "pageStart": 0
}

Get Calendar

The endpoint returns the Calendar and its events for the given calendarId. You can optionally filter events by a given date range.

Resource URI

GET /rest/public/calendars/{calendarId}

Request Parameters

Name Type Description
calendarId Type Calender Id
fromDateTime DateTime from date (Optional)
toDateTime DateTime to date (Optional)

Example

GET /rest/public/calendars/2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
	"status": "success",
	"count": 1,
	"type": "Calendar",
	"results": [
	{
		"calendarId": 2,
		"calendarName": "Holidays",
		"calendarType": "HOLIDAY",
		"lseId": 734,
		"events": [
		{
			"calendarEventId": 2,
			"calendarEventName": "New Year's Day",
			"lseId": null,
			"calendarEventType": "HOLIDAY",
			"locale": "US",
			"seededUntil": "2017-01-01"
		},
		
		/* edited for length */
		
	}]
}

Get Calendar Dates

Returns actual dates of events for the given criteria, which includes date ranges, lseId filters.

Resource URI

GET /rest/public/calendars/dates

Request Parameters

Name Type Description
calendarId Long Optionally return only dates for a given calendar.
lseId Long Optional filter for a given utility. Since calendars belong to LSEs, you don’t need to send this if sending calendarId.
locale String Optional ISO country code of the locale you are interested in (e.g. US).
fromDateTime DateTime Event dates on or after this date (Optional).
toDateTime DateTime Event dates on or before this date (Optional).
calendarEventTypes String Comma separated string that indicates the calendar event types to include. Choices are: HOLIDAY, BILLING, PRICING_PERIOD (Optional).
dateDefinitionTypes String Comma separated string that indicates the date definition types to include. Choices are: FIXED_DATE, MANUAL, FLOATING_DATE, EASTER_DATE (Optional).
calendarEventId Long Optionally return only dates with the same event For example, passing in the event ID associated with the 4th July will return different instances of the 4th of July.

Example

GET /rest/public/calendars/dates
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
	"status": "success",
	"count": 37381,
	"type": "CalendarDate",
	"results": [
		{
			"eventDateId": 2,
			"subKey": null,
			"eventName": "New Year's Day",
			"startDateTime": "2010-01-01T00:00:00+00:00",
			"endDateTime": null,
			"calendarEventId": 2,
			"lseId": 2654
		},
		{
			"eventDateId": 2,
			"subKey": null,
			"eventName": "New Year's Day",
			"startDateTime": "2010-01-01T00:00:00+00:00",
			"endDateTime": null,
			"calendarEventId": 2,
			"lseId": 734
		},
	
		/* edited for length */

}