Many utilities (LSEs) charge different tariff rates depending on the time of year. A utility might charge 8.5¢ during summer, and 7¢ in winter, for instance. Utilities have their own definition of when these times of year start and end. For example one utility might define “Summer” as starting on 4/1 and “Winter” on 9/15, whereas other says “Summer” starts on 6/15 but also defines different rates for “Spring” and “Fall” too. Genability has a data driven way of defining these periods, called Seasons (as they usually, but not always, have names resembling seasons of the year). A Season belongs to a utility (LSE), and one or more Seasons are organized into a Season Group, where together they span a full calendar year.

Seasons can start on a fixed date, which is defined by the combination of the seasonStartMonth and seasonStartDay properties. Similarly the seasonEndMonth and seasonEndDay properties define the end date. However, in some cases, the start date or the end date of the Season is not fixed, but is dynamically overridden by either the start date or end date of the billing period that it occurs in. This behavior is recorded by the Season’s optional fromEdgePredominance and toEdgePredominance properties. When populated they can be set to PREDOMINANT, which tells you that this date should move to the start of the bill or SUBSERVIENT, which means it moves to the end of the bill.

As an example, consider a utility customer who gets their March 5th to April 4th bill. This utility defines their “summer” Season as starting at the beginning of the bill that includes March 15th. And to be consistent their “winter” season also ends at the start of the bill that includes March 15th. The customer would pay “summer” rates for the entire billing period, and no “winter” rates, because the “summer” start date and “winter” end date would both be dynamically overridden to March 5th.

Data Definitions

Season

The Season object has the following data structure.

Name Type Fields Description
seasonId Long   Unique Genability ID (primary key) for each season
lseId Long   The ID of the LSE this territory belongs to
seasonGroupId Long   The ID of the season group that contains this season
seasonName String   The name of the season (i.e. "Summer" or "Winter")
seasonFromMonth Integer   Value of 1-12 representing the month this season begins
seasonFromDay Integer   Value of 1-31 (depending on month) representing the day this season begins
fromEdgePredominance String E Can be null (from date is a fixed date), PREDOMINANT (from date is the start of the bill the season starts starts in), or SUBSERVIENT (from date is the end of the bill the season starts in).
seasonToMonth Integer   Value of 1-12 representing the month this season ends
seasonToDay Integer   Value of 1-31 (depending on month) representing the day this season ends
toEdgePredominance String E Can be null (to date is a fixed date), PREDOMINANT (to date is the start of the bill the season starts ends in), or SUBSERVIENT (to date is the end of the bill the season starts in).

Season Group

The SeasonGroup object has the following data structure.

Name Type Description
seasonGroupId Long Unique Genability ID (primary key) for each season group
seasons List of Season A List of the Seasons within this Season Group

Here’s an example in JSON of one season group populated with two seasons that start and end on fixed 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
28
29
30
31
32
33
34
35
36
{
   "status":"success",
   "count":1,
   "type":"SeasonGroup",
   "results":[
      {
         "seasonGroupId":1,
         "seasons":[
            {
               "seasonId":3,
               "seasonGroupId":1,
               "lseId":1,
               "seasonName":"Winter",
               "seasonFromMonth":10,
               "seasonFromDay":1,
               "fromEdgePredominance":null,
               "seasonToDay":31,
               "seasonToMonth":5,
               "toEdgePredominance":null
            },
            {
               "seasonId":4,
               "seasonGroupId":1,
               "lseId":1,
               "seasonName":"Summer",
               "seasonFromMonth":6,
               "seasonFromDay":1,
               "fromEdgePredominance":null,
               "seasonToDay":30,
               "seasonToMonth":9,
               "toEdgePredominance":null
            }
         ]
      }
   ]
}

Get a List of Season Groups for an LSE

This returns a list of season groups for a given LSE. The result set is a list of season group objects in the standard response format.

Resource URI

GET /rest/public/seasons

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 The LSE ID who’s seasons we want. (Required)

Example

GET /rest/public/seasons?lseId=734
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
{
   "status":"success",
   "count":1,
   "type":"SeasonGroup",
   "results":[
      {
         "seasonGroupId":1,
         "seasons":[
            {
               "seasonId":3,
               "seasonGroupId":1,
               "lseId":1,
               "seasonName":"Winter",
               "seasonFromMonth":10,
               "seasonFromDay":1,
               "fromEdgePredominance":"SUBSERVIENT",
               "seasonToDay":31,
               "seasonToMonth":5,
               "toEdgePredominance":"SUBSERVIENT"
            },
            {
               "seasonId":4,
               "seasonGroupId":1,
               "lseId":1,
               "seasonName":"Summer",
               "seasonFromMonth":6,
               "seasonFromDay":1,
               "fromEdgePredominance":"PREDOMINANT",
               "seasonToDay":30,
               "seasonToMonth":9,
               "toEdgePredominance":"PREDOMINANT"
            }
         ]
      }
   ]
}

History

  • Now includes new season from and to predominance rules - 3/6/2017
  • Updated to include Sorting and Searching by name - 1/9/2012
  • Formatting update - 3/10/2015
  • Initial Release - 4/28/2011 - Seasons