Get Best Typical Baseline

get

https://api.genability.com/rest/v1/typicals/baselines/best

Retrieve the baseline that best fits the provided location, building type, and optional building details.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Use this endpoint to retrieve the baseline that best fits the location, building type, and optional building details you provide.

When to use this endpoint

Use GET /rest/v1/typicals/baselines/best when you need to:

Estimate hourly usage for a residential or commercial building.
Build a usage baseline when real usage data is unavailable.
Fill gaps in billing history with typical usage data.
Request interval data for a specific date range.
Scale a typical baseline to a known annual kWh value with sizing parameters.

Location inputs

Provide one of these location input patterns:

Parameter	Type	Description
`zipCode` or `postCode`	String	ZIP code or postal code for location lookup.
`country`	String	ISO country code. Use with `zipCode` or `postCode`.
`addressString`	String	Address string used for geo-tagging and local building lookup.
`lat` / `lng`	Double	Latitude and longitude coordinates. Use together.

Building and output parameters

Parameter	Type	Description
`customerClass`	String	Customer class, such as `RESIDENTIAL`, `GENERAL`, or `SPECIAL_USE`.
`buildingType`	String	Building type. Use values from `buildingTypeResidential` or `buildingTypeCommercial` Property Keys, or use `RESIDENTIAL` for the residential default.
`serviceType`	String	Currently limited to `ELECTRICITY`.
`buildingArea`	Long	Building footprint size in square feet. Defaults to the regional average for the building type if omitted.
`buildingVintage`	String	Construction era: `Pre1980`, `Post1980`, or `New`. Defaults to `Post1980` if omitted.
`excludeMeasures`	Boolean	Set to `true` to omit measures. Defaults to `false`.
`measuresUnit`	String	Returns `total` usage per interval by default. Use `intensity` or `proportion` for alternate output units.
`groupBy`	String	Groups measures by `YEAR`, `MONTH`, `DAY`, or `HOUR`. This value is case-sensitive.
`intervalFromDateTime`	DateTime	Start date for interval population.
`intervalToDateTime`	DateTime	End date for interval population.

Sizing parameters

Use these parameters together when scaling a baseline to a known load size:

Parameter	Type	Description
`sizingKeyName`	String	Load size adjustment key. Currently supports `loadSize`.
`sizingDataValue`	Number	Quantity for sizing, such as `12000` for 12,000 kWh. Required when using `sizingKeyName`.
`sizingUnit`	String	Unit of measure for `sizingDataValue`. Currently supports `kWh`. Required when using `sizingKeyName`.

Related endpoints

chart-line

Typical Baseline Overview

Learn how typical baseline data is modeled.

key

List Properties

Retrieve building type Property Keys such as buildingTypeResidential and buildingTypeCommercial.

map-marked-alt

Territories Overview

Review territory data used for utility climate zones.

Query Params

zipCode

string

The zip code or postal code we will use to look up local buildings.

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.

lat

double

Latitude to look up. Use in concert with lng if you choose this method.

lng

double

Longitude to look up. Use in concert with lat if you choose this method.

customerClass

string

The class of customer, which is one of RESIDENTIAL, GENERAL, or SPECIAL_USE.

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.

serviceType

string

This is currently limited to ELECTRICITY.

buildingArea

int64

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.

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.

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.

sizingDataValue

int32

This should be set to the quantity to size (e.g. 12000 for 12,000 kWh). (See sizingKeyName above)

sizingUnit

string

This denotes the unit of measure for the accompanying sizingDataValue. Currently, we support only kWh. (See sizingKeyName above)

intervalFromDateTime

date

Pass this parameter when you want the "intervals" to be populated from a certain date (e.g. 2024-01-01).

intervalToDateTime

date

Pass this parameter when you want the "intervals" to be populated to a certain date (e.g. 2025-01-01).

Responses

When to use this endpoint

Location inputs

Building and output parameters

Sizing parameters

Related endpoints

200200

400400