Start with confidence using Arcadia's Typical Baseline feature. Get instant access to realistic, location-based usage curves for any building type without existing data. The smart way to begin your energy insights journey.
A Typical Baseline provides hourly energy usage profiles (8,760 hours annually) for various residential and commercial building types across specific geographic locations. Arcadia offers an extensive portfolio of these baselines, each enhanced by optional parameters that represent the physical characteristics of buildings to improve usage estimate accuracy.
By providing a location—such as an address, ZIP code, postal code, or latitude and longitude coordinates—along with optional building details, the API estimates what an average building of that type would consume each hour throughout the year. This capability 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 unavailable.
Core Components
Four key components drive a typical baseline:
- Customer class - Indicates whether the site is residential, commercial and industrial (C&I), or specialty
- Location - Weather patterns and climate directly correlate to energy usage
- Building type - Specific categories such as single-family home (residential) or hospital (C&I)
- Building vintage - The construction era of the building
Location - Where the Building is Located
The location you provide drives the baseline calculation. We map locations to a Utility Climate Zone (UCZ), which represents 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 United States.
When a utility divides its service area into smaller territories for rate purposes—sometimes called baseline regions (as California IOUs and some northeastern US utilities do)—we also split the UCZ to this granular level. A utility climate zone ensures that important tariff rates and climatic boundaries aren't blended, which would distort local typical costs.
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 follow a hierarchical structure. At the top level, buildings are categorized as residential, small commercial, medium commercial, or large commercial. These categories are then subdivided into building types that distinguish the primary purpose of the building (e.g., hospital vs. small office vs. large retail store).
You can find a complete list of residential building types by examining 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 when it was designed and constructed, encompassing everything from materials and insulation standards to the efficiency of heating, cooling, and lighting systems. We currently support three eras: Pre1980, Post1980 (1980-2003), and New (2003+). If you don't specify a buildingVintage, we default to Post1980.
Geographic Availability
Our baselines are currently available exclusively for locations within the United States.
Data Definitions
The data structure of a baseline consists of a "header" containing key information such as name, building type, and other essential values. It also includes a collection (list) of Baseline Measure records that contain the actual hourly or 15-minute usage data for each interval throughout a year.
Baseline
Each Baseline object has a unique baselineId for identification. Each building also has a descriptive name that can be used for identifying and displaying the typical building in your applications.
| Name | Type | Fields | Description |
|---|---|---|---|
| baselineId | String | M | Unique Arcadia ID for the baseline profile this actual baseline is based on |
| name | String | M | The descriptive name for this baseline |
| buildingType | Map of String to String | M | Building type classification with id, name, optional description, and customerClass |
| serviceType | String | For typical buildings, this is ELECTRICITY | |
| sourceId | String | Data source identifier | |
| startDay | Integer | The day of the week this baseline starts on (1=Monday, 7=Sunday) | |
| climateZone | Territory | M | Territory object of the utility climate zone applicable for this baseline |
| properties | Array of PropertyData | Building properties such as Customer Class | |
| factors | Map of String to Decimal | M | Key factors associated with modeling this baseline (see details 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 details below) | |
| intervals | Array of Interval Info | Optionally returned when requesting an interval range; provides kWh and kW values for that interval |
Baseline Measure
The baseline's measures contain an array of BaselineMeasure objects. These consist of an index (i) that increases chronologically from 1 to 8,760 (if hourly) or 4 × 8,760 (if 15 minutes), and a value (v) that represents that interval's usage amount.
| 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 follow the same structure as the 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 |
Method: Get Best Baseline
Use this method to retrieve a baseline that best fits your specified criteria. You must provide location information (address string, ZIP/postal code with country code, or latitude & longitude coordinates). You'll also likely need to specify the building type, either as a customer class (RESIDENTIAL, GENERAL, or SPECIAL_USE) or more specifically (and recommended) as a buildingType (such as "Single Family Detached", "Small Commercial", or "Hospital").
Resource URI
GET /rest/v1/typicals/baselines/bestRequest Parameters
Include the required security parameters. You can also use standard pagination or search and sort options. The following additional parameters are supported:
| Name | Type | Description |
|---|---|---|
| zipCode or postCode | String | ZIP code or postal code for location lookup (Optional) |
| country | String | ISO country code (use with zipCode or postCode parameters) |
| addressString | String | Address string for geo-tagging (isolating latitude & longitude) to look up local buildings (Optional) |
| lat | Double | Latitude coordinate (use with lng parameter) (Optional) |
| lng | Double | Longitude coordinate (use with lat parameter) (Optional) |
| customerClass | String | Customer class: RESIDENTIAL, GENERAL, or SPECIAL_USE (Optional) |
| buildingType | String | Building type description. Use RESIDENTIAL for residential default or choose from buildingTypeResidential or buildingTypeCommercial property key options (Optional) |
| serviceType | String | Currently limited to ELECTRICITY (Optional) |
| buildingArea | Long | Building footprint size in square feet. Defaults to regional average for the buildingType if not provided (Optional) |
| buildingVintage | String | Construction era: Pre1980, Post1980 (1980-2003), or New (2003+) |
| excludeMeasures | Boolean | Set to true to omit measures (faster response if data not needed). Defaults to false |
| measuresUnit | String | Returns total usage per interval by default. Choose intensity for energy intensity (per square foot/meter) or proportion for values that sum to 100 across the year |
| groupBy | String | Groups measures into specified period: YEAR, MONTH, DAY, or HOUR (Optional) case-sensitive |
| sizingKeyName | String | Parameter for load size adjustment. Currently supports loadSize. Use with sizingDataValue and sizingUnit (Optional) |
| sizingDataValue | Number | Quantity for sizing (e.g., 12000 for 12,000 kWh). Required if using sizingKeyName |
| sizingUnit | String | Unit of measure for sizingDataValue. Currently supports only kWh. Required if using sizingKeyName |
| intervalFromDateTime | DateTime | Start date for interval population (e.g., 2024-01-01) (Optional) |
| intervalToDateTime | DateTime | End date for interval population (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 request above retrieves a residential building baseline for downtown San Francisco and groups results by month (to keep the response concise). Typically, you'll want all 8,760 hours, so simply remove the groupBy parameter. 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 specify a more precise buildingType of Single Family Home and scale 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 months (adjust the groupBy parameter for hourly data), but in this case, the entire year totals the targeted 12,000 kWh. Notice we're 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 request a Large Hotel for the buildingType and specify a particular time period (a full year) using intervalFromDateTime and intervalToDateTime. When you provide both dates, we "map" the typical data to the requested period, accounting for weekdays versus 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 months (adjust the groupBy parameter for hourly data), but also includes the intervals list containing Interval Info for our 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
}
}
]
}
]
}