Calendars

Use Calendars to retrieve tariff-related dates, including billing dates, holidays, and dynamic pricing events.

A Calendar defines important dates associated with tariffs. These dates can include billing dates, holiday schedules, and dynamic events such as smart days, critical peaks, and system peaks. Use Calendar endpoints to discover available calendars and retrieve the dates they specify.

Calendars are part of the time-based tariff metadata model. Use Seasons for utility-defined seasonal date ranges and Time of Uses for schedules that determine when time-of-use rates apply.

Get Calendars

Retrieve calendars by utility, calendar type, or date range.

Get One Calendar

Retrieve one calendar and its event definitions by calendarId.

Get Calendar Dates

Retrieve actual holiday, billing, or pricing-period event dates.

Data Definitions

A calendar has a resource type of Calendar. An individual event date has a resource type of CalendarDate.

Each calendar has a list of events that describe the type of dates on the calendar. For example, billing period end can be an event on a billing-period calendar, and Easter Sunday can be an event on a holiday calendar. A specific event occurrence, such as Easter Sunday 2015 or the billing-period end date of June 12, 2015, is a CalendarDate.

Calendar

A Calendar object 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, it's indicative of its purpose (e.g. "Holidays").
calendarType	String	M	Indicates the type of dates in this calendar. Values are `HOLIDAY` (e.g. July 4), `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. 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 locale's 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 is used for various date types.

Calendar Date

The actual event 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	String	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 date's calendar event
lseId	Long	M	The utility that the calendar date belongs to

Get Calendars

Retrieve calendars that match the request parameters.

Resource URI

GET /rest/public/calendars/

Request parameters

Name	Type	Description
lseId	Long	LSE ID. Optional.
calendarType	String	Type of calendar. Choices are `HOLIDAY`, `BILLING`, and `PRICING_PERIOD`. Optional.

Example 1: Get all holiday calendars for a utility

GET /rest/public/calendars?lseId=734&calendarType=HOLIDAY

{  
   "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 billing cycle calendars for a utility

GET /rest/public/calendars?lseId=734&calendarType=BILLING

This abbreviated response shows two of the matching billing calendars:

{  
   "status": "success",  
   "count": 21,  
   "type": "Calendar",  
   "results": [  
      {  
         "calendarId": 705,  
         "calendarName": "Read Cycle B",  
         "calendarType": "BILLING",  
         "lseId": 734  
      },
      {  
         "calendarId": 726,  
         "calendarName": "Read Cycle Z",  
         "calendarType": "BILLING",  
         "lseId": 734  
      }  
   ],  
   "pageCount": 25,  
   "pageStart": 0  
}

Get Calendar

Retrieve a calendar and its events by calendarId. You can optionally filter events by date range.

Resource URI

GET /rest/public/calendars/{calendarId}

Request parameters

Name	Type	Description
calendarId	Long	Calendar ID. Required.
fromDateTime	DateTime	Return events on or after this date. Optional.
toDateTime	DateTime	Return events on or before this date. Optional.

Example

GET /rest/public/calendars/2

This abbreviated response shows the calendar metadata and event list shape.

{
  "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"
        }
      ]
    }
  ]
}

Get Calendar Dates

Retrieve actual event dates for criteria such as date range, lseId, calendar type, or date-definition type. Use this endpoint when you need the concrete dates represented by a calendar event.

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 calendar event types to include. Choices are `HOLIDAY`, `BILLING`, and `PRICING_PERIOD`. Optional.
dateDefinitionTypes	String	Comma-separated date definition types to include. Choices are `FIXED_DATE`, `MANUAL`, `FLOATING_DATE`, and `EASTER_DATE`. Optional.

Example

GET /rest/public/calendars/dates

This abbreviated response shows the calendar date list shape.

{
  "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
    }
  ]
}