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 postcode, 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 it is 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 UCZs 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. A utility climate zone makes sure that important tariff rates and climatic boundaries aren't blended 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 - What is the building used for
Our building types are hierarchical. They start at the top level by splitting buildings into residential, small, medium, or large commercial. Then these can be further split into building types that distinguish 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 displaying the typical building in your apps.
| Name | Type | Fields | Description |
|---|---|---|---|
| baselineId | String | M | Unique Arcadia 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 contain 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 interval's 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) building type (like small commercial or even hospital).
Resource URI
GET /rest/v1/typicals/baselines/best
Request Parameters
The required security parametersshould 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 postcode we will use to look up local buildings. (Optional) |
| country | String | [ISO country code][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 (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 on this page). More often than not you will want all 8760 hours, so just remove the groupBy property. The output is:
{
"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 scaled 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 targeted. As you can see we are modeling Single Family Detached:
{
"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:
{
"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
}
}
]
}
]
}