Typical Baseline

Overview

A typical baseline gives you "typical" hourly (8760) or 15 minute 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.

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 keyName "buildingTypeResidential". Similarly, commercial building types are available using the property key "buildingTypeCommercial".

Whats 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 accountId 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 customer class
serviceType String 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 Defines 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, 900000 for 15 min)
measureValue String Unit of quantities
measureUnit String One of "total", "intensity", or "proportion"
measures Array of Baseline Measure Actual hourly or 15 minute intervals. See below for details of Baseline Measures.

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.

Operations

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
addressString String The address string we will geo-tag (we will find the lat-lng for) to look up local buildings. (Optional)
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.
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. 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".

Example

GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=RESIDENTIAL

The above asks for a residential building for downtown San Francisco. An Example of the output is:

{
   "status": "success",
   "count": 1,
   "type": "Baseline",
   "results": [
      {
         "baselineId": "534edc6c3004344710acffb0",
         "name": "Residential",
         "buildingType": {
            "id": "RESIDENTIAL",
            "name": "Residential",
            "description": "Residential 3C - from Midrise Apt Post 1980",
            "customerClass": "RESIDENTIAL"
         },
         "serviceType": "ELECTRICITY",
         "sourceId": "UTILITY",
         "climateZone": {
            "territoryId": 3777,
            "territoryName": null
         },
         "properties": [
            {
               "keyName": "customerClass",
               "dataType": "INTEGER",
               "dataValue": "1"
            }
         ],
         "factors": {
            "peakDemand": 1.97588,
            "monthlyConsumption": 562.437,
            "annualConsumption": 6749.248,
            "meanAnnualConsumption": 6749.242,
            "meanBuildingArea": 1667,
            "meanIntensity": 4.04874,
            "uberAnnualConsumption": 6.807074,
            "buildingArea": 1667
         },
         "measureDuration": 3600000,
         "measureValue": "kWh",
         "measureUnit": "total",
         "measures": [
            {
               "i": 1,
               "v": 0.648263
            },
            {
               "i": 2,
               "v": 0.627797
            },

            /* edited for space */

            {
               "i": 8760,
               "v": 0.734693
            }
         ]
      }
   ]
}