Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
Typical Baseline
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 in square feet. 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
}
}
]
}
]
}