Use Typical Baselines to estimate hourly electricity usage for residential and commercial buildings when real-world usage data is unavailable.
Use Typical Baselines to estimate hourly electricity usage for residential and commercial buildings when real-world usage data is unavailable.
A Typical Baseline provides an hourly, 8,760-hour energy usage profile for a building type in a specific location. Arcadia baselines can use optional building characteristics to improve the estimate. Provide a location, such as an address, ZIP or postal code, or latitude/longitude, and optionally provide building details to estimate what an average building of that type would consume each hour of the year.
Use typical baselines to quickly qualify leads, fill gaps in billing history, and compare customers with similar usage patterns when real-world data is not available. Typical Baselines often depend on location metadata from Territories and building-type property keys from Properties.
Retrieve the best matching typical baseline for a location and building type.
Retrieve property keys such as buildingTypeResidential and buildingTypeCommercial.
Understand utility climate zones and baseline regions used for local baseline selection.
Use typical baseline data in a Quick Switch Savings Analysis.
The core components that drive a typical baseline are:
- The customer class, which denotes whether the site is residential, commercial and industrial (C&I), or specialty.
- The location, as weather patterns and climate correlate to energy usage.
- The building type, such as single-family home (residential) or hospital (C&I).
- The building vintage, or when the building was constructed.
Location
The location you supply drives the baseline. Arcadia maps locations to a Utility Climate Zone (UCZ), which is the intersection of a climate zone and a utility's service area. In the US, climate zones use ASHRAE climate zones.
Where a utility splits its service area into smaller territories for rate purposes, sometimes called baseline regions, Arcadia also splits the UCZ to that lower level. Utility climate zones help avoid blending tariff-rate and climate boundaries that would distort local typical cost. A Utility Climate Zone is represented as a Territory with usageType=UTILITY_CLIMATE_ZONE.
Building type
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.
GET /rest/public/properties/buildingTypeResidential{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "buildingTypeResidential",
"displayName": "Building Type Residential",
"family": "specifications",
"keyspace": "building",
"description": "Type of Residential Building",
"dataType": "CHOICE",
"choices": [
{
"displayValue": "Single Family Detached",
"value": "singleFamilyDetached",
"dataValue": "singleFamilyDetached"
},
{
"displayValue": "Single Family Attached",
"value": "singleFamilyAttached",
"dataValue": "singleFamilyAttached"
},
{
"displayValue": "Apartment (2 to 4 Units)",
"value": "apartmentUnder5Units",
"dataValue": "apartmentUnder5Units"
},
{
"displayValue": "Apartment (5 Units or more)",
"value": "apartmentOver4Units",
"dataValue": "apartmentOver4Units"
},
{
"displayValue": "Mobile Home",
"value": "mobileHome",
"dataValue": "mobileHome"
},
{
"displayValue": "Residential",
"value": "RESIDENTIAL",
"dataValue": "RESIDENTIAL"
}
]
}
]
}GET /rest/public/properties/buildingTypeCommercial{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "buildingTypeCommercial",
"displayName": "Building Type Commercial",
"family": "specifications",
"keyspace": "building",
"description": "Type of Commercial Building",
"dataType": "CHOICE",
"choices": [
{
"displayValue": "Large Office",
"value": "largeOffice",
"dataValue": "largeOffice"
},
{
"displayValue": "Medium Office",
"value": "mediumOffice",
"dataValue": "mediumOffice"
},
{
"displayValue": "Small Office",
"value": "smallOffice",
"dataValue": "smallOffice"
},
{
"displayValue": "Warehouse",
"value": "warehouse",
"dataValue": "warehouse"
},
{
"displayValue": "Stand Alone Retail",
"value": "standAloneRetail",
"dataValue": "standAloneRetail"
},
{
"displayValue": "Strip Mall",
"value": "stripMall",
"dataValue": "stripMall"
},
{
"displayValue": "Primary School",
"value": "primarySchool",
"dataValue": "primarySchool"
},
{
"displayValue": "Secondary School",
"value": "secondarySchool",
"dataValue": "secondarySchool"
},
{
"displayValue": "Supermarket",
"value": "supermarket",
"dataValue": "supermarket"
},
{
"displayValue": "Quick Service Restaurant",
"value": "quickServiceRestaurant",
"dataValue": "quickServiceRestaurant"
},
{
"displayValue": "Full Service Restaurant",
"value": "fullServiceRestaurant",
"dataValue": "fullServiceRestaurant"
},
{
"displayValue": "Hospital",
"value": "hospital",
"dataValue": "hospital"
},
{
"displayValue": "Outpatient Health Care",
"value": "outpatientHealthCare",
"dataValue": "outpatientHealthCare"
},
{
"displayValue": "Small Hotel",
"value": "smallHotel",
"dataValue": "smallHotel"
},
{
"displayValue": "Large Hotel",
"value": "largeHotel",
"dataValue": "largeHotel"
},
{
"displayValue": "Midrise Apartment",
"value": "midriseApartment",
"dataValue": "midriseApartment"
},
{
"displayValue": "Small Commercial",
"value": "SMALL_COMMERCIAL",
"dataValue": "SMALL_COMMERCIAL"
},
{
"displayValue": "Medium Commercial",
"value": "MEDIUM_COMMERCIAL",
"dataValue": "MEDIUM_COMMERCIAL"
},
{
"displayValue": "Large Commercial",
"value": "LARGE_COMMERCIAL",
"dataValue": "LARGE_COMMERCIAL"
}
]
}
]
}Building vintage
A building's vintage reflects the era it was designed and constructed, from the materials and insulation standards to the efficiency of its heating, cooling, and lighting systems. We currently support three eras: Pre1980, Post1980 (1980 to 2003), and New (2003+). If you do not define a buildingVintage, we default to Post1980.
Availability
Our baselines are limited to use for locations within the United States.
Data definitions
The baseline data structure starts with header fields, such as name, building type, and other key values. It also includes a collection of BaselineMeasure records that contain 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. | |
| 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. |
Baseline Measure
The baseline's measures contain an array of BaselineMeasure objects. Each measure has an index (i) that increases in chronological order from 1 to 8,760 for hourly intervals or 4 x 8,760 for 15-minute intervals, and a value (v) for that interval.
| Name | Type | 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 objects when you request them. They use the same structure as intervals returned when requesting a profile.
| Name | Type | 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 retrieve the baseline that best fits your criteria. Pass a location using an address string, ZIP or postal code with country code, or latitude/longitude. You should also pass a building definition, either as customerClass (RESIDENTIAL, GENERAL, or SPECIAL_USE) or a more specific buildingType, such as singleFamilyDetached, smallOffice, or hospital.
Resource URI
GET /rest/v1/typicals/baselines/bestRequest parameters
| Name | Type | Description |
|---|---|---|
| zipCode or postCode | String | ZIP code or postal code used to look up local buildings. Optional. |
| country | String | The ISO country code. Use in conjunction with zipCode | postCode parameters. |
| addressString | String | Address string to geocode for local building lookup. Optional. |
| lat | Double | Latitude to look up. Use with lng. Optional. |
| lng | Double | Longitude to look up. Use with lat. Optional. |
| customerClass | String | Customer class. Choices are RESIDENTIAL, GENERAL, and SPECIAL_USE. Optional. |
| buildingType | String | Building type that best describes the building. Use RESIDENTIAL for a residential default, or use one of the explicit choices returned from buildingTypeResidential or buildingTypeCommercial. Optional. |
| serviceType | String | Service type. Currently limited to ELECTRICITY. Optional. |
| buildingArea | Long | Building size in square feet. If omitted, defaults to the average for the region and buildingType. Optional. |
| buildingVintage | String | Construction era of the building. Options include Pre1980, Post1980 (1980 to 2003), and New (2003+). Optional. |
| excludeMeasures | Boolean | When true, omits measures to make the call faster when you do not need measure data. Defaults to false. Optional. |
| measuresUnit | String | Measure unit to return. Defaults to total usage per interval. Use intensity for energy intensity, such as per square foot or meter. Use proportion when each value in the year should add up to 100. Optional. |
| groupBy | String | Period to roll up measures into. Possible values are MONTH, DAY, and YEAR. Optional. |
| sizingKeyName | String | Pass when you want to adjust load size. Currently supports loadSize. Use with sizingDataValue and sizingUnit. Optional. |
| sizingDataValue | Number | Quantity to size, such as 12000 for 12,000 kWh. Use with sizingKeyName. Optional. |
| sizingUnit | String | Unit of measure for sizingDataValue. Currently supports only kWh. Use with sizingKeyName. Optional. |
| intervalFromDateTime | DateTime | Start date for populating intervals, such as 2024-01-01. Optional. |
| intervalToDateTime | DateTime | End date for populating intervals, such as 2025-01-01. Optional. |
Example 1: Residential home in San Francisco
GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=RESIDENTIAL&excludeMeasures=false&groupBy=MONTHThis request asks for a residential building in downtown San Francisco and groups the results by month to keep the response small. To return all 8,760 hourly values, omit the groupBy parameter.
{
"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.16342,
"longitude": -122.156195
}
},
"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.0000,
"meanIntensity": 4.04874,
"buildingArea": 1667.0000
},
"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.640080
},
{
"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
This example is more specific about the buildingType by using Single Family Home. It also scales the annual load (sizingKeyName) to 12,000 kWh using sizingDataValue and sizingUnit.
GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=singleFamilyDetached&excludeMeasures=false&groupBy=MONTH&sizingKeyName=loadSize&sizingDataValue=12000&sizingUnit=kWhLike example 1, the output is grouped by month. In this example, the full year adds up to the requested 12,000 kWh target. The request models the Single Family Detached buildingType.
{
"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.16342,
"longitude": -122.156195
}
},
"properties": [
{
"keyName": "buildingVintage",
"dataType": "STRING",
"dataValue": "Post1980"
},
{
"keyName": "customerClass",
"dataType": "INTEGER",
"dataValue": "1"
}
],
"factors": {
"peakDemand": 3.51307,
"monthlyConsumption": 1000.00,
"annualConsumption": 11999.999995,
"meanAnnualConsumption": 11135.0000,
"meanBuildingArea": 2108.0000,
"meanIntensity": 5.28226,
"buildingArea": 2108.0000
},
"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.854220
},
{
"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
This example requests a Large Hotel baseline with buildingType=largeHotel. It also requests a specific one-year period with intervalFromDateTime and intervalToDateTime. When you pass both dates, Arcadia maps the typical data to the requested period while accounting for weekdays, weekends, leap days, and daylight saving time.
GET /rest/v1/typicals/baselines/best?postCode=94105&country=US&buildingType=largeHotel&excludeMeasures=false&groupBy=MONTH&intervalFromDateTime=2024-01-01&intervalToDateTime=2025-01-01Like example 1, the output is grouped by month. It also includes the intervals list with IntervalInfo for the requested range.
{
"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.16342,
"longitude": -122.156195
}
},
"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.0000,
"meanBuildingArea": 122120.0000,
"meanIntensity": 14.6964,
"buildingArea": 122120.0000,
"intervalConsumption": 1799151.6533
},
"measureDuration": 3600000,
"measureValue": "kWh",
"measureUnit": "total",
"startDay": 7,
"measures": [
{
"i": 1,
"v": 144693.5199
},
{
"i": 2,
"v": 134257.838
},
{
"i": 3,
"v": 145410.8380
},
{
"i": 4,
"v": 143265.826
},
{
"i": 5,
"v": 151190.957
},
{
"i": 6,
"v": 148748.816
},
{
"i": 7,
"v": 158989.110
},
{
"i": 8,
"v": 159172.299
},
{
"i": 9,
"v": 159241.901
},
{
"i": 10,
"v": 159299.100
},
{
"i": 11,
"v": 146003.821
},
{
"i": 12,
"v": 144450.0804
}
],
"intervals": [
{
"fromDateTime": "2024-01-01T00:00:00.000Z",
"toDateTime": "2024-02-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 144643.0469,
"rateAmount": 0
},
"kW": {
"quantityAmount": 344.495,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-02-01T00:00:00.000Z",
"toDateTime": "2024-03-01T00:00:00.000Z",
"duration": 2505600000,
"kWh": {
"quantityAmount": 139193.055,
"rateAmount": 0
},
"kW": {
"quantityAmount": 364.082,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-03-01T00:00:00.000Z",
"toDateTime": "2024-04-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 145001.2170,
"rateAmount": 0
},
"kW": {
"quantityAmount": 345.085,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-04-01T00:00:00.000Z",
"toDateTime": "2024-05-01T00:00:00.000Z",
"duration": 2592000000,
"kWh": {
"quantityAmount": 143791.282,
"rateAmount": 0
},
"kW": {
"quantityAmount": 365.563,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-05-01T00:00:00.000Z",
"toDateTime": "2024-06-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 150715.070,
"rateAmount": 0
},
"kW": {
"quantityAmount": 361.790,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-06-01T00:00:00.000Z",
"toDateTime": "2024-07-01T00:00:00.000Z",
"duration": 2592000000,
"kWh": {
"quantityAmount": 151755.661,
"rateAmount": 0
},
"kW": {
"quantityAmount": 421.966,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-07-01T00:00:00.000Z",
"toDateTime": "2024-08-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 156676.260,
"rateAmount": 0
},
"kW": {
"quantityAmount": 371.609,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-08-01T00:00:00.000Z",
"toDateTime": "2024-09-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 159485.974,
"rateAmount": 0
},
"kW": {
"quantityAmount": 367.567,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-09-01T00:00:00.000Z",
"toDateTime": "2024-10-01T00:00:00.000Z",
"duration": 2592000000,
"kWh": {
"quantityAmount": 159002.152,
"rateAmount": 0
},
"kW": {
"quantityAmount": 419.424,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-10-01T00:00:00.000Z",
"toDateTime": "2024-11-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 159008.393,
"rateAmount": 0
},
"kW": {
"quantityAmount": 382.977,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-11-01T00:00:00.000Z",
"toDateTime": "2024-12-01T00:00:00.000Z",
"duration": 2592000000,
"kWh": {
"quantityAmount": 145573.520,
"rateAmount": 0
},
"kW": {
"quantityAmount": 355.998,
"rateAmount": 0
}
},
{
"fromDateTime": "2024-12-01T00:00:00.000Z",
"toDateTime": "2025-01-01T00:00:00.000Z",
"duration": 2678400000,
"kWh": {
"quantityAmount": 144306.0224,
"rateAmount": 0
},
"kW": {
"quantityAmount": 343.259,
"rateAmount": 0
}
}
]
}
]
}