Calendar

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

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 */

}