Get Best Baseline

get

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Retrieve the typical baseline that best matches a location and building description.

Use this endpoint when you need an estimated electricity usage profile and do not have real-world usage data. Pass a location and, when available, building details such as buildingType, buildingArea, and buildingVintage.

Resource URI

GET /rest/v1/typicals/baselines/best

Required input

Provide at least one location input:

addressString
zipCode or postCode with country
lat and lng

For better matching, also pass buildingType or customerClass.

Common query parameters

Parameter	Type	Description
`zipCode`	String	ZIP or postal code used to look up local buildings. Use with `country`. Optional.
`country`	String	ISO country code. Use with `zipCode` or `postCode`. Optional.
`addressString`	String	Address string used for geocoding. Optional.
`lat`	Number	Latitude. Use with `lng`. Optional.
`lng`	Number	Longitude. Use with `lat`. Optional.
`customerClass`	String	Customer class, such as `RESIDENTIAL`, `GENERAL`, or `SPECIAL_USE`. Optional.
`buildingType`	String	Building type, such as `RESIDENTIAL`, `singleFamilyDetached`, or `largeHotel`. Optional.
`serviceType`	String	Service type. Currently limited to `ELECTRICITY`. Optional.
`buildingArea`	Integer	Building size in square feet. Optional.
`buildingVintage`	String	Construction era: `Pre1980`, `Post1980`, or `New`. Optional.
`excludeMeasures`	Boolean	When `true`, omits measures for a faster response. Defaults to `false`. Optional.
`measuresUnit`	String	Controls how measures are returned. Use `total` for total usage, `intensity` for energy intensity, or `proportion` for values that add up to 100. Optional.
`groupBy`	String	Rolls up measures by `MONTH`, `DAY`, or `YEAR`. Optional.
`sizingKeyName`	String	Set to `loadSize` to scale the load. Use with `sizingDataValue` and `sizingUnit`. Optional.
`sizingDataValue`	Number	Target quantity used for sizing, such as `12000` for 12,000 kWh. Optional.
`sizingUnit`	String	Unit for `sizingDataValue`. Currently supports `kWh`. Optional.
`intervalFromDateTime`	Date	Start date for populated intervals. Use with `intervalToDateTime`. Optional.
`intervalToDateTime`	Date	End date for populated intervals. Use with `intervalFromDateTime`. Optional.

For the full data model, building type guidance, and response examples, see Typical Baselines.

Example

GET /rest/v1/typicals/baselines/best?addressString=94105&buildingType=RESIDENTIAL&excludeMeasures=false&groupBy=MONTH

A successful response returns a standard response payload with type set to Baseline and one best-fit baseline in the results array.

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

Resource URI

Required input

Common query parameters

Example

200200

400400