Getting started shouldn’t slow you down. Arcadia’s Typical Baseline feature gives you instant access to realistic usage curves based on your location, no existing data required. It’s the quick and easy way to kick off your energy insights with confidence.
A Typical Baseline provides typical hourly (8,760-hour) energy usage profiles for various residential and commercial building types across specific geographic locations. Arcadia offers a large portfolio of these baselines, each linked to optional parameters (physical characteristics of the building) to improve the accuracy of usage estimates. By providing a location such as an address, ZIP or postal code, or latitude and longitude, and optionally additional details about the building you are modeling, the API can estimate what an average building of that type would consume each hour of the year. This helps you quickly assess and qualify leads, fill gaps in billing history, and compare customers with similar usage patterns even when real-world data is not available.
The core components that drive a typical baseline are:
- The customer class which denotes if it is residential, commercial and industrial (C&I), or specialty site.
- 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 simply when the building was constructed.
Location - Where the building is located
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 the building is 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.
{
"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"
}
]
}
]
}{
"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 - When the building was constructed
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-2003), and New (2003+). If you do not specifically define a buildingVintage we default to Post1980.
Where are typical baselines currently available?
Our baselines are limited to use for locations within the United States.
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 Baseline Measure 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. | |
| 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. 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 | 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 | 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. |
Method: 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 code or postal code with a country code, or a latitude & longitude). You'll also likely have some definition of the type of building you are interested in, either as a customer class ( RESIDENTIAL, GENERAL or SPECIAL_USE) or a more specifically (and recommended) buildingType (like "Single Family Detached", "Small Commercial", or even "Hospital").
Resource URI
GET /rest/v1/typicals/baselines/bestRequest 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 code or postal code we will use to look up local buildings. (Optional) |
| country | String | The ISO country code. Use in conjunction with zipCode | postCode parameters. |
| addressString | String | The address string we will geo-tag (isolate latitude & longitude) to look up local buildings. (Optional) |
| lat | Double | Latitude to look up. Use in concert with lng if you choose this method. (Optional) |
| lng | Double | Longitude to look up. Use in concert with lat if you choose this method. (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 for a residential default or one of the more explicit choices returned from the property key buildingTypeResidential or buildingTypeCommercial. (Optional) |
| serviceType | String | This is currently limited to ELECTRICITY. (Optional) |
| buildingArea | Long | If you have the site footprint, pass in size of the building in square feet. If this is not passed directly we will default to the average for the region and buildingType. (Optional) |
| buildingVintage | String | The construction year of the building, options include Pre1980, Post1980 (1980 - 2003), or New (2003+). |
| excludeMeasures | Boolean | Setting to true will omit the measures (makes the call faster if you don't need this data). 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 square foot or meter). Your final choice is proportion which means that each value in the year will add up to 100. |
| groupBy | String | When supplied the response will roll up measures into this period. Possible values are MONTH, DAY, YEAR. (Optional) |
| sizingKeyName | String | Pass this parameter when you want to adjust the size of the load. Currently supports loadSize. Used in concert with sizingDataValue and sizingUnit. (Optional) |
| sizingDataValue | Number | This should be set to the quantity to size (e.g. 12000 for 12,000 kWh). (Optional, see sizingKeyName above) |
| sizingUnit | String | This denotes the unit of measure for the accompanying sizingDataValue. Currently, we support only kWh. (Optional, see sizingKeyName above) |
| intervalFromDateTime | DateTime | Pass this parameter when you want the "intervals" to be populated from a certain date (e.g. 2024-01-01). (Optional) |
| intervalToDateTime | DateTime | Pass this parameter when you want the "intervals" to be populated to a certain date (e.g. 2025-01-01). (Optional) |
Example 1: Residential Home in San Francisco
GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=RESIDENTIAL&excludeMeasures=false&groupBy=MONTHThe above request 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.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
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=kWhLike example 1, the output is in months (adjust the groupBy parameter 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 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
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=2024-01-01&intervalToDateTime=2025-01-01Like example 1, the output is in months (adjust the groupBy parameter 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.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
}
}
]
}
]
}