A typical baseline gives you “typical” hourly (8760) usage for a specific type of building in a specific geography. We have a large portfolio of typical baselines to choose from. Using a location, such as an address, a ZIP or post code, or a lat/lng, and optionally some additional information about the building you are trying to model, this API can give you what an average building of that type might use for each hour of the year. This allows you to quickly assess and qualify leads, plug gaps in billing history, and compare your customers with similar circumstances.

The major parameters that drive a typical baseline are:

  • its customer class which denotes if its residential, C&I or specialty
  • its building type such as single family home, or hospital
  • its location as weather patterns and climate correlate to energy usage

Location - where it is

The location you supply drives the baseline. We map locations to a “utility climate zone” (UCZ). A UCZ is the intersection of a climate zone (ASHRAE climate zones in the US) and a utility’s service area. There are approximately 650 UCZ’s in the US. Furthermore, where a utility splits its service area for rate purposes into smaller territories (sometimes called baseline regions - the California IOUs and some utilities in the northeast of the US do this), we also split the UCZ to this lower level too. A utility climate zone makes sure that important tariff rates and climatic boundaries aren’t blended together distorting the local typical cost. We define the region for a Utility Climate Zone as a Territory with a usageType of UTILITY_CLIMATE_ZONE.

Building Type - whats the building used for

Our building types are hierarchical. They start out at the top level by splitting buildings into residential, or small, medium or large commercial. Then these can be further split into building types that distinguishes the major purpose of the building (e.g. hospital vs small office vs large retail store). A complete list of residential building types can be found by looking at the Property Key with the keyName of buildingTypeResidential. Similarly, commercial building types are available using the property key buildingTypeCommercial.

Where are they currently available?

We currently have baselines for the US. We will be adding more markets over time.

Data Definitions

The data structure of a baseline consists of a “header” that denotes key information about it such as its name, building type and other key values. It also has a collection (list) of BaselineMeasure records that contain the actual hourly or 15 minute usage for each interval of a year.

Baseline

Each Baseline object has a unique baselineId to represent it. Each building also has a name that can be used for identifying and display the typical building in your apps.

Name Type Fields Description
baselineId String M Unique Genability ID for the baseline profile this actual baseline is based on.
name String M The short name that describes this baseline.
buildingType Map of String to String M What type of building this record is. This has an id, a name, an optional description, and a customerClass
serviceType String   For typical buildings this is ELECTRICITY.
sourceId String   Where the data comes from.
startDay Integer   The day of the week that this baseline starts on. Ranges from 1 (Monday) to 7 (Sunday).
climateZone Territory M Territory object of the utility climate zone this baseline is applicable for.
properties Array of PropertyData   Properties of this building such as Customer Class
factors Map of String to Decimal M Key factors associated with modeling this baseline. See Below.
type String   Typical buildings have ARCHETYPE account type
measureDuration Integer   Interval duration in milliseconds (e.g. 3600000 for hourly)
measureValue String   Unit of quantities
measureUnit String   One of total, intensity, or proportion
measures Array of Baseline Measure   Actual hourly or monthly intervals. See below for details of Baseline Measures.
intervals Array of Interval Info   Optionally returned when you request an interval range and gives you kWh and kW values for that interval. See below for details of Interval Info.

Baseline Measure

The baseline’s measures contains an array of BaselineMeasure objects. These are simply an index (i) which increases in chronological order from 1 to 8760 (if hourly) or 4 x 8760 (if 15 minutes), and a value (v) that denotes that intervals value.

Name Type Fields Description
i Integer   Interval of the year (hour or month).
v Decimal   Amount (value) for this interval.

Interval Info

The baseline’s intervals property contains an array of IntervalInfo when you request them. They are the same structure as the Intervals you get back when requesting a Profile.

Name Type Fields Description
fromDateTime DateTime   Start of the interval.
toDateTime DateTime   End of the interval.
duration Decimal   Length of the interval, in milliseconds.
kWh.quantityAmount Decimal   Consumption (kWh) for this interval.
kWh.rateAmount Decimal   Ignore for this purpose.
kW.quantityAmount Decimal   Demand (kW) for this interval.
kW.rateAmount Decimal   Ignore for this purpose.

Get Best Baseline

Use this method to get a baseline that best fits your required criteria. You need to pass in something indicating location (an address string, a ZIP or postcode with a country code, or a lat/lon). You’ll also likely have some definition of the type of building you are interested in, either as a customer class (i.e RESIDENTIAL, GENERAL or SPECIAL_USE) or a more specifically (and recommended) a building type (like small commercial or even hospital).

Resource URI

GET /rest/v1/typicals/baselines/best

Request Parameters

The required security parameters should be included. You can also use the standard pagination or search and sort options. The following additional parameters are supported too:

Name Type Description
zipCode or postCode String The ZIP or post code we will use to look up local buildings. (Optional)
country String ISO country code. Use in conjunction with postcode parameters.
addressString String The address string we will geo-tag (we will find the lat-lng for) to look up local buildings. (Optional)
lat Double Latitude to look up. Send lng too if you send this. (Optional)
lng Double Longitude to look up. Send lat too if you send this. (Optional)
customerClass String The class of customer, which is one of RESIDENTIAL, GENERAL, or SPECIAL_USE. (Optional)
buildingType String The building type that best describes this building. Use RESIDENTIAL or one of the choices returned from the property key buildingTypeResidential or buildingTypeCommercial (Optional)
serviceType String Currently this is always ELECTRICITY, but more service types are coming (Optional)
buildingArea Long If you have it, pass in the finished size of the building. Otherwise we will default to the average for the region and building type (Optional)
buildingVintage String Not currently used, but will be soon. Choose one of the choices from buildingVintageResidential or buildingVintageCommercial (make sure you pick the right one based on whether you are looking for residential or not)
excludeMeasures Boolean Setting to true will omit the measures (makes it faster if you don’t need them). Defaults to false.
measuresUnit String By default we will return total usage per interval. If you ask for intensity we’ll convert this into energy intensity (e.g. per sqr ft or meter). Your final choice is proportion which means that each value in the year will add up to 100.
groupBy String Optional. When supplied will roll up measures into this unit. Possible values are MONTH, DAY, YEAR.
sizingKeyName String Optional. Use when you want to adjust the size of the load. Currently supports loadSize. When setting this also set sizingDataValue and sizingUnit.
sizingDataValue Number Optional, and should be set to the quantity to size to (e.g. 12000 for 12,000 kWh)
sizingUnit String Optional, and denotes the unit of measure for the accompanying sizingDataValue. Currently we support kWh.
intervalFromDateTime DateTime Optional. Pass in when you want the “intervals” to be populated from a certain date (e.g. 2014-01-01).
intervalToDateTime DateTime Optional. Pass in when you want the “intervals” to be populated to a certain date (e.g. 2015-01-01).

Example 1 : Residential Home in San Francisco

GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=RESIDENTIAL&excludeMeasures=false&groupBy=MONTH

The above asks for a residential building for downtown San Francisco, and requests that the results be grouped into months (to keep the response small in this page). More often than not you will want all 8760 hours, so just remove the groupBy property. The output is:

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
{
    "status": "success",
    "count": 1,
    "type": "Baseline",
    "results": [
        {
            "baselineId": "5462916ef81548bdd70a3d24",
            "name": "Residential",
            "buildingType": {
                "id": "RESIDENTIAL",
                "name": "Residential",
                "description": "Residential - Post1980 3C",
                "customerClass": "RESIDENTIAL"
            },
            "serviceType": "ELECTRICITY",
            "sourceId": "UTILITY",
            "climateZone": {
                "territoryId": 3858,
                "territoryName": "Pacific Gas & Electric Co - Baseline Region T - 3C",
                "lseId": 734,
                "lseName": "Pacific Gas & Electric Co",
                "parentTerritoryId": 3538,
                "usageType": "UTILITY_CLIMATE_ZONE",
                "itemTypes": "ZIPCODE",
                "deregRes": false,
                "deregCandi": false,
                "centerPoint": {
                    "latitude": 37.22589772602739,
                    "longitude": -122.04498898630153
                }
            },
            "properties": [
                {
                    "keyName": "buildingVintage",
                    "dataType": "STRING",
                    "dataValue": "Post1980"
                },
                {
                    "keyName": "customerClass",
                    "dataType": "INTEGER",
                    "dataValue": "1"
                }
            ],
            "factors": {
                "peakDemand": 1.97588,
                "monthlyConsumption": 562.437,
                "annualConsumption": 6749.248024,
                "meanAnnualConsumption": 6749.2424,
                "meanBuildingArea": 1667,
                "meanIntensity": 4.04874,
                "buildingArea": 1667
            },
            "measureDuration": 3600000,
            "measureValue": "kWh",
            "measureUnit": "total",
            "startDay": 7,
            "measures": [
                {
                    "i": 1,
                    "v": 596.826384
                },
                {
                    "i": 2,
                    "v": 521.373326
                },
                {
                    "i": 3,
                    "v": 572.028226
                },
                {
                    "i": 4,
                    "v": 540.660167
                },
                {
                    "i": 5,
                    "v": 546.64008
                },
                {
                    "i": 6,
                    "v": 532.986784
                },
                {
                    "i": 7,
                    "v": 566.854876
                },
                {
                    "i": 8,
                    "v": 566.260058
                },
                {
                    "i": 9,
                    "v": 575.247387
                },
                {
                    "i": 10,
                    "v": 578.347188
                },
                {
                    "i": 11,
                    "v": 557.123136
                },
                {
                    "i": 12,
                    "v": 594.900412
                }
            ]
        }
    ]
}

Example 2 : Single Family Home in San Francisco

In this example we have been more specific about the buildingType, saying it’s a Single Family Home. Also, we’ve stated that our annual load (sizingKeyName) should be scalled to 12,000 kWh (sizingDataValue and sizingUnit respectfully).

GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=singleFamilyDetached&excludeMeasures=false&groupBy=MONTH&sizingKeyName=loadSize&sizingDataValue=12000&sizingUnit=kWh

Like example 1, the output is in months (drop the groupBy if you want hours), but in this case the whole year adds up to the 12,000 kWh we targetted. And you can see we are modeling Single Family Detached:

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
{
    "status": "success",
    "count": 1,
    "type": "Baseline",
    "results": [
        {
            "baselineId": "541341e170de02ebbb531978",
            "name": "Single Family Detached",
            "buildingType": {
                "id": "singleFamilyDetached",
                "name": "Single Family Detached",
                "description": "Single Family Detached - Post1980 3C",
                "customerClass": "RESIDENTIAL"
            },
            "serviceType": "ELECTRICITY",
            "sourceId": "UTILITY",
            "climateZone": {
                "territoryId": 3858,
                "territoryName": "Pacific Gas & Electric Co - Baseline Region T - 3C",
                "lseId": 734,
                "lseName": "Pacific Gas & Electric Co",
                "parentTerritoryId": 3538,
                "usageType": "UTILITY_CLIMATE_ZONE",
                "itemTypes": "ZIPCODE",
                "deregRes": false,
                "deregCandi": false,
                "centerPoint": {
                    "latitude": 37.22589772602739,
                    "longitude": -122.04498898630153
                }
            },
            "properties": [
                {
                    "keyName": "buildingVintage",
                    "dataType": "STRING",
                    "dataValue": "Post1980"
                },
                {
                    "keyName": "customerClass",
                    "dataType": "INTEGER",
                    "dataValue": "1"
                }
            ],
            "factors": {
                "peakDemand": 3.51307,
                "monthlyConsumption": 1000,
                "annualConsumption": 11999.999995,
                "meanAnnualConsumption": 11135,
                "meanBuildingArea": 2108,
                "meanIntensity": 5.28226,
                "buildingArea": 2108
            },
            "measureDuration": 3600000,
            "measureValue": "kWh",
            "measureUnit": "total",
            "startDay": 7,
            "measures": [
                {
                    "i": 1,
                    "v": 1061.142835
                },
                {
                    "i": 2,
                    "v": 926.989107
                },
                {
                    "i": 3,
                    "v": 1017.052348
                },
                {
                    "i": 4,
                    "v": 961.280538
                },
                {
                    "i": 5,
                    "v": 971.912771
                },
                {
                    "i": 6,
                    "v": 947.637634
                },
                {
                    "i": 7,
                    "v": 1007.85422
                },
                {
                    "i": 8,
                    "v": 1006.796756
                },
                {
                    "i": 9,
                    "v": 1022.776194
                },
                {
                    "i": 10,
                    "v": 1028.287505
                },
                {
                    "i": 11,
                    "v": 990.551436
                },
                {
                    "i": 12,
                    "v": 1057.718651
                }
            ]
        }
    ]
}

Example 3 : Large Hotel with intervals for a specific year

In this example we are requesting a Large Hotel for the buildingType. But also notice that we are requesting a specific period of time (in this case a year) via the intervalFromDateTime and intervalToDateTime. When you pass these dates in (you need both) we “move” the typical data to the requested period, taking into account weekdays vs weekends as well as leap days and daylight savings.

GET /rest/v1/typicals/baselines/best?postCode=94105&country=US&buildingType=largeHotel&excludeMeasures=false&groupBy=MONTH&intervalFromDateTime=2014-01-01&intervalToDateTime=2015-01-01

Like example 1, the output is in months (drop the groupBy if you want hours), but also includes the intervals list that contains Interval Info for the range we requested:

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
{
    "status": "success",
    "count": 1,
    "type": "Baseline",
    "results": [
        {
            "baselineId": "51b64f0303643f03a7e50040",
            "name": "Large Hotel",
            "buildingType": {
                "id": "largeHotel",
                "name": "Large Hotel",
                "description": "Large Hotel - Post1980 3C",
                "customerClass": "GENERAL"
            },
            "serviceType": "ELECTRICITY",
            "sourceId": "DOECRB",
            "climateZone": {
                "territoryId": 3858,
                "territoryName": "Pacific Gas & Electric Co - Baseline Region T - 3C",
                "lseId": 734,
                "lseName": "Pacific Gas & Electric Co",
                "parentTerritoryId": 3538,
                "usageType": "UTILITY_CLIMATE_ZONE",
                "itemTypes": "ZIPCODE",
                "deregRes": false,
                "deregCandi": false,
                "centerPoint": {
                    "latitude": 37.22589772602739,
                    "longitude": -122.04498898630153
                }
            },
            "properties": [
                {
                    "keyName": "buildingArea",
                    "dataType": "INTEGER",
                    "dataValue": "122120"
                },
                {
                    "keyName": "buildingVintage",
                    "dataType": "STRING",
                    "dataValue": "Post1980"
                },
                {
                    "keyName": "customerClass",
                    "dataType": "INTEGER",
                    "dataValue": "2"
                }
            ],
            "factors": {
                "peakDemand": 421.966,
                "monthlyConsumption": 149560,
                "annualConsumption": 1794724.1063,
                "meanAnnualConsumption": 1794723,
                "meanBuildingArea": 122120,
                "meanIntensity": 14.6964,
                "buildingArea": 122120,
                "intervalConsumption": 1794456.3733
            },
            "measureDuration": 3600000,
            "measureValue": "kWh",
            "measureUnit": "total",
            "startDay": 7,
            "measures": [
                {
                    "i": 1,
                    "v": 144693.5199
                },
                {
                    "i": 2,
                    "v": 134257.838
                },
                {
                    "i": 3,
                    "v": 145410.838
                },
                {
                    "i": 4,
                    "v": 143265.826
                },
                {
                    "i": 5,
                    "v": 151190.957
                },
                {
                    "i": 6,
                    "v": 148748.816
                },
                {
                    "i": 7,
                    "v": 158989.11
                },
                {
                    "i": 8,
                    "v": 159172.299
                },
                {
                    "i": 9,
                    "v": 159241.901
                },
                {
                    "i": 10,
                    "v": 159299.1
                },
                {
                    "i": 11,
                    "v": 146003.821
                },
                {
                    "i": 12,
                    "v": 144450.0804
                }
            ],
            "intervals": [
                {
                    "fromDateTime": "2014-01-01T00:00:00.000Z",
                    "toDateTime": "2014-02-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 144933.2189,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 344.495,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-02-01T00:00:00.000Z",
                    "toDateTime": "2014-03-01T00:00:00.000Z",
                    "duration": 2419200000,
                    "kWh": {
                        "quantityAmount": 134532.899,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 364.082,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-03-01T00:00:00.000Z",
                    "toDateTime": "2014-04-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 144924.947,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 345.085,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-04-01T00:00:00.000Z",
                    "toDateTime": "2014-05-01T00:00:00.000Z",
                    "duration": 2592000000,
                    "kWh": {
                        "quantityAmount": 143874.186,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 365.563,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-05-01T00:00:00.000Z",
                    "toDateTime": "2014-06-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 150539.979,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 361.79,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-06-01T00:00:00.000Z",
                    "toDateTime": "2014-07-01T00:00:00.000Z",
                    "duration": 2592000000,
                    "kWh": {
                        "quantityAmount": 153164.372,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 421.966,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-07-01T00:00:00.000Z",
                    "toDateTime": "2014-08-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 155478.661,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 359.239,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-08-01T00:00:00.000Z",
                    "toDateTime": "2014-09-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 159750.645,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 367.567,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-09-01T00:00:00.000Z",
                    "toDateTime": "2014-10-01T00:00:00.000Z",
                    "duration": 2592000000,
                    "kWh": {
                        "quantityAmount": 159123.466,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 419.424,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-10-01T00:00:00.000Z",
                    "toDateTime": "2014-11-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 158559.329,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 382.977,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-11-01T00:00:00.000Z",
                    "toDateTime": "2014-12-01T00:00:00.000Z",
                    "duration": 2592000000,
                    "kWh": {
                        "quantityAmount": 145476.029,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 355.998,
                        "rateAmount": 0
                    }
                },
                {
                    "fromDateTime": "2014-12-01T00:00:00.000Z",
                    "toDateTime": "2015-01-01T00:00:00.000Z",
                    "duration": 2678400000,
                    "kWh": {
                        "quantityAmount": 144098.6414,
                        "rateAmount": 0
                    },
                    "kW": {
                        "quantityAmount": 343.259,
                        "rateAmount": 0
                    }
                }
            ]
        }
    ]
}