Note that this API is deprecated. There are a number of APIs that can provide you with similar data to this API that you should consider. For Switch customers this would include the Account Cost Calculation API and for Signal customers, look at the On-demand Cost Calculation API. Ask us if you have any further questions.

A TypicalBuilding object gives you “typical” costs, usage and rates for a specific type building in a specific geography. We have a large (and growing) portfolio of typical buildings to choose from. Using a location and some information to filter to just the types of building you are interested in, you can get an understanding of what an average building of that type might use and spend, down to an hourly level. 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 building are 1) its source of baseline usage data , 2) its building Type, and 3) the region or geography it covers. Some sources of building typicals vary by additional properties such as building vintage (how old it is). Each typical building has hourly granularity of costs and usage. We utilize our comprehensive, national database of tariff rates and our cost calculator to calculate a specific localized charge using actual rates.

Source - where the Usage Data comes from

We have a variety of different sources from where a building type gets its usage data (consumption, demand etc). You have the ability to optionally choose the source or sources you feel are most applicable. The table later in this section shows the sources currently available.

Territory - which geography it applies to

The territory specifies the region or geography that a typical building is applicable for. You’ll notice in the table below that many apply to what we call a “utility climate zone”. A utility climate zone (UCZ) is the intersection of an ASHRAE climate zone and a utility’s service area. There are approx 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 utility climate zone 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. When searching for buildings or picking a best fitting building for an address, lat/lon or zipcode, we use the building region as part of the query.

Building Type - whats the building used for

Some sources have building types just split at a class of customer level (i.e. residential, small commercial etc). Others take building types to a lower level of specificity and distinguish the purpose of the building (e.g. hospital vs small office vs large retail store). We make sure the tariff rates used for typical costs are the ones that match that type and size of business. If you know that a building is, say, a mid-rise apartment vs a single family home, you can find a building type and source that best fits what you know.

What’s Currently Available

Here’s a round-up of the current sources and their regions, types and counts (come back periodically for updates - we continue to add more):

Source Territory Types Approx # Description
UTILITY Utility Climate Zone Residential, S,M,L Commercial 3,300 Usage data from a number of representative profiles published by utilities
DOECRB Utility Climate Zone By 16 commercial building types and 3 vintages 30,000 Usage generated by the EnergyPlus tool using DOE Commercial Reference Buildings
others Utility Climate Zone CEUS, RECS, CEBECS lots! Call us for more details
Your Own Flexible Flexible - If you have MAISY or your own profiles, we can calculate their costs

Data Definitions

The data structure of a typical building is very similar to that of an account. It consists of a “header” that denotes key information about it such as its unique accountId, name and other properties. It also has a collection of IntervalInfo records that contain the actual hourly cost, rates and usage.

Building

Each Building 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
accountId String M Unique Genability ID for this Building.
sourceId String M The source for this buildings usage and/or model data.
buildingTypeId String M What type of building this record is.
territory Territory M Defines the geographic region this record is applicable for.
providerAccountId String M Alternate key for this building type.
accountName String M Descriptive name of the building object.
customerOrgId String   Included for account compatibility. Not usually populated
customerOrgName String   Included for account compatibility. Not usually populated
owner String   Owner of this record. Included for account compatibility. Not usually populated
status String   Status of this record. Usually "ACTIVE", but could also be "INACTIVE" or "DELETED"
type String   Typical buildings have "ARCHETYPE" account type
properties Array of PropertyData   Properties of this building such as customerClass
tariffs Array of Tariff   Usually only one entry that has the summary of the tariff used for calculating costs
profiles Array of Profile   See below for details of profile and its interval info.

Profile

Each building will have one or more profiles that contain the costs and usage for a given service type. The profiles here are the same profiles that are associated with accounts.

Name Type Fields Description
profileId String (UUID) M Unique Genability ID for this Usage Profile.
profileName String M (Optional) Your specified name for this Usage Profile.
description String   Optional description for this Usage Profile.
serviceTypes String   Comma separated strings of the types of service this profile denotes. Current types include ELECTRICITY and SOLAR_PV.
source Source   Optional. Source contains a sourceId and name (both strings). Uniquely identify the source of this profile. e.g. ‘PVWatts’
isDefault Boolean   Denotes whether this is the default profile for the service type. Default profiles are used for calcs when no profile is specified.
properties Array of PropertyData   Our standard collection of PropertyData denoting properties specific to this Profile.
intervals Array of IntervalInfo Data   See below for details of IntervalInfo.

Interval Info

The profiles property contains an array of Profile objects, which in turn contain intervals. Its the intervals property that contains an array of IntervalInfo entries. Each IntervalInfo contain the costs as well as rates and usage data for a given period of time (in this case hour).

Name Type Fields Description
fromDateTime Date   Date and time this interval starts.
toDateTime Date   Date and time this interval ends.
duration Decimal   Length of this interval.
kWh Measure   Holds the quantityAmount and costAmount (decimal) for kWh’s.
kW Measure   Holds the quantityAmount and costAmount (decimal) for kW’s.
total Measure   Holds the quantityAmount and costAmount (decimal) for total charges.

Operations

###Get Buildings Use this method to query for buildings that match your required criteria. Usually you will have an address (or lat/lon or ZIP code). You’ll also likely have some definition of the type of building you are interested in, either a customer class (like residential or general) or a more specific building type (like small commercial or even hospital). A full list of request parameters is listed below.

Resource URI

GET /rest/v1/typicals/buildings

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
sourceId String Source of the usage or model data. Includes "UTILITY", "ENERGYPLUS" (see table above for full list). (Optional)
buildingTypes String Comma separated string of building types to include results for (Optional)
customerClasses String Comma separated string of classes of customer include "RESIDENTIAL" and "GENERAL". (Optional)
serviceTypes String Comma separated string of service types that the Building should have data for, including "ELECTRICITY" and "SOLAR_PV" (Optional)
masterTariffId Long ID of the tariff that you’d like to match to (Optional)
addressString String The address string we will geo-tag (we will find the lat-lng for) to look up local typical buildings. (Optional)
zipCode String The ZIP or post code we will use to look up local typical 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)
maxDistance Double The radius in miles to search around. (Optional)

Example

GET /rest/v1/typicals/buildings?addressString=94105&sourceId=UTILITY

The above asks for buildings for downtown San Francisco with a utility source. An example of the output is:

{
   "status":"success",
   "count":2,
   "type":"Building",
   "results":[
      {
         "accountId":"8701bdf0-9e59-42ae-80b2-95cefb587711",
         "sourceId":"UTILITY",
         "buildingType":{
            "id":"SMALL_COMMERCIAL"
         },
         "territory":{
            "territoryId":3534,
            "territoryName":"Baseline Region P",
            "lseId":734,
            "lseName":"Pacific Gas & Electric Co"
         },
         "providerAccountId":null,
         "accountName":"PG&E A1 dynamic 2011 Small Commercial",
         "customerOrgId":null,
         "customerOrgName":null,
         "owner":null,
         "status":"ACTIVE",
         "type":"ARCHETYPE",
         "properties":{
            "customerClass":{
               "keyName":"customerClass",
               "dataType":"INTEGER",
               "dataValue":"2"
            }
         },
         "tariffs":[
            {
               "masterTariffId":82009,
               "tariffCode":"A-1",
               "tariffName":"Small General",
               "tariffType":"ALTERNATIVE",
               "customerClass":null,
               "customerLikelihood":null,
               "endDate":null,
               "timeZone":"US/Pacific",
               "billingPeriod":"MONTHLY",
               "currency":"USD"
            }
         ],
         "profiles":[
            {
               "profileId":"29b2016f-5d31-48c3-a34e-103038cdf381",
               "profileName":"Electricity",
               "serviceTypes":"ELECTRICITY",
               "source":{
                  "sourceId":"UTILITY",
                  "name":"Third Party Typical"
               },
               "isDefault":true,
               "properties":null
            },
            {
               "profileId":"0c6ede58-1925-45f9-93f8-826f7e5fbbef",
               "profileName":"Solar PV Production",
               "description":"System size: 11.130 Generated by PVWatts",
               "serviceTypes":"SOLAR_PV",
               "source":{
                  "sourceId":"PVWatts",
                  "name":"PVWatts (integrated)"
               },
               "properties":null
            }
         ]
      },
      
	  /* edited for length %/
	  
   ]
}

Get a Building

You can retrieve a specific typical building, with or without its intervals, using this method.

Resource URI

GET /rest/v1/typicals/buildings/{accountId}

Request Parameters

Along with the required security parameters and the accountId for the building, the following parameters are available as part of the request:

Name Type Description
populateIntervals Boolean When true the results will contain intervals. The default is false. (Optional)
fromDateTime DateTime Start date (with or without a time) of the date range to return intervals for. (Optional)
toDateTime DateTime End date (with or without a time) of the date range to return intervals for. (Optional)
groupBy String Use groupBy to roll up the interval data from hours to larger durations. Possible values are: "YEAR", "MONTH", "DAY", and "HOUR"
clipBy String clipBy is optional and is only considered when groupBy (above) is set. clipBy allows you to control the behavior in the case where groupBy and the requested date range do not line up exactly. Possible values are: "OUTER", "INNER". For example, you request interval data and specify groupBy=MONTH with a date range of April 15, 2012 through June 15, 2012. "OUTER" will include all months that overlap at least part of the requested range, and the response will include the months of April, May and June. "INNER" will only include the full months within the requested range, so only May is returned. When you pass in a groupBy but do not specific clipBy, "INNER" is used. (Optional)

Example

GET /rest/v1/typicals/buildings/8701bdf0-9e59-42ae-80b2-95cefb587711?populateIntervals=true&fromDateTime=2012-04-01&toDateTime=2012-04-02

The above retrieves a specific building with April 1st, 2012 intervals populated for both of its profiles (electricity and solar). An example of the output is:

{
   "status":"success",
   "count":1,
   "type":"Building",
   "results":[
      {
         "accountId":"8701bdf0-9e59-42ae-80b2-95cefb587711",
         "sourceId":"UTILITY",
         "buildingType":{
            "id":"SMALL_COMMERCIAL"
         },
         "territory":{
            "territoryId":3534,
            "territoryName":"Baseline Region P",
            "lseId":734,
            "lseName":"Pacific Gas & Electric Co"
         },
         "providerAccountId":null,
         "accountName":"PG&E A1 dynamic 2011 Small Commercial",
         "customerOrgId":null,
         "customerOrgName":null,
         "owner":null,
         "status":"ACTIVE",
         "type":"ARCHETYPE",
         "properties":{
            "customerClass":{
               "keyName":"customerClass",
               "dataType":"INTEGER",
               "dataValue":"2"
            }
         },
         "tariffs":[
            {
               "masterTariffId":82009,
               "tariffCode":"A-1",
               "tariffName":"Small General",
               "tariffType":"ALTERNATIVE",
               "customerClass":null,
               "customerLikelihood":null,
               "endDate":null,
               "timeZone":"US/Pacific",
               "billingPeriod":"MONTHLY",
               "currency":"USD"
            }
         ],
         "profiles":[
            {
               "profileId":"29b2016f-5d31-48c3-a34e-103038cdf381",
               "profileName":"Electricity",
               "serviceTypes":"ELECTRICITY",
               "source":{
                  "sourceId":"UTILITY",
                  "name":"Third Party Typical"
               },
               "isDefault":true,
               "properties":null,
               "intervals":{
                  "totalCount":24,
                  "pageCount":25,
                  "pageStart":0,
                  "list":[
                     {
                        "fromDateTime":"2012-04-01T00:00:00+00:00",
                        "toDateTime":"2012-04-01T01:00:00+00:00",
                        "duration":3600000,
                        "kWh":{
                           "quantityAmount":1.413003,
                           "costAmount":0.204787
                        },
                        "total":{
                           "quantityAmount":1.413003,
                           "costAmount":0.218476
                        }
                     },
					 
					 /* edited for length */
					 
                     {
                        "fromDateTime":"2012-04-01T23:00:00+00:00",
                        "toDateTime":"2012-04-02T00:00:00+00:00",
                        "duration":3600000,
                        "kWh":{
                           "quantityAmount":1.596887,
                           "costAmount":0.231437
                        },
                        "total":{
                           "quantityAmount":1.596887,
                           "costAmount":0.245126
                        }
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Get Best Building

Use this method to get the best fitting typical building based on the supplied criteria. Usually an address and other customer/building identifying inputs are passed in and the best fitting building is returned. You’ll also likely have some definition of the type of building you are interested in, either a customer class (like residential or general) or a more specific building type (like small commercial or even hospital). A full list of request parameters is listed below.

Resource URI

GET /rest/v1/typicals/buildings/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
sourceId String Source of the usage or model data. Includes "UTILITY", "ENERGYPLUS" (see table above for full list). (Optional)
buildingTypeId String The building type you are requesting. (Optional)
customerClass String The class of customer, including "RESIDENTIAL" or "GENERAL". (Optional)
serviceType String The service type that the Building should have data for, including "ELECTRICITY" and "SOLAR_PV" (Optional)
masterTariffId Long ID of the tariff that you’d like to match to (Optional)
addressString String The address string we will geo-tag (we will find the lat-lng for) to look up local typical buildings. (Optional)
zipCode String The ZIP or post code we will use to look up local typical 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)
maxDistance Double The radius in miles to search around. (Optional)
populateIntervals Boolean When true the results will contain intervals. The default is false. (Optional)

Example

GET /rest/v1/typicals/buildings/best?addressString=94105&customerClass=RESIDENTIAL

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

{
   "status":"success",
   "count":1,
   "type":"Building",
   "results":[
      {
         "accountId":"d133ef9b-5662-4650-8e85-fd764f221bc1",
         "sourceId":"GENABILITY",
         "buildingType":{
            "id":"residential"
         },
         "territory":{
            "territoryName":"Pacific Gas & Electric Co - Service area for CA - 3C",
            "lseId":734,
            "lseName":"Pacific Gas & Electric Co",
            "centerPoint":{
               "latitude":37.4343185502959,
               "longitude":-122.102938964497
            }
         },
         "providerAccountId":null,
         "accountName":"Pacific Gas & Electric Co - Service area for CA - 3C",
         "customerOrgId":null,
         "customerOrgName":null,
         "owner":null,
         "status":"ACTIVE",
         "type":"ARCHETYPE",
         "properties":{
            "buildingArea":{
               "keyName":"buildingArea",
               "dataType":"INTEGER",
               "dataValue":"2614"
            },
            "buildingVintage":{
               "keyName":"buildingVintage",
               "dataType":"STRING",
               "dataValue":"Post1980"
            },
            "customerClass":{
               "keyName":"customerClass",
               "dataType":"INTEGER",
               "dataValue":"1"
            }
         },
         "tariffs":[
            {
               "masterTariffId":522,
               "tariffCode":"E-1",
               "tariffName":"Residential",
               "tariffType":"DEFAULT",
               "timeZone":"US/Pacific",
               "billingPeriod":"MONTHLY",
               "currency":"USD"
            }
         ],
         "profiles":[
            {
               "profileId":"57ffdc64-0eba-496f-95a5-6391c8d9ebd0",
               "profileName":"Electricity",
               "serviceTypes":"ELECTRICITY",
               "isDefault":true,
               "properties":null
            }
         ]
      }
   ]
}

History

  • Updated formatting - 3/10/2015
  • Fixed parameter BuildingType to BuildingTypeId - 11/14/2013
  • Updated to include best building - 7/24/2013
  • Initial documentation published - 5/22/2013