Getting Started with EI API
Access
If you don't have an API key yet, sign up for free limited access here!
When logged in, your API Key will appear here:
{user.apiKey}
Free limited access includes 500 monthly successful requests to the /calculate
endpoint. Your API key can also be used for our Sandbox Demo Application! If you prefer the Swagger or Redoc flavor of API documentation, we have those too!
For any questions or to report bugs, please reach out to ei-api@palmetto.com.
What is this page
The API Reference lays out every parameter you can pass in to a request, and every element you can expect to be returned in a response. This page provides context on how to think about those options and data structures, and some tips for getting what you want out of the API.
Stay tuned as we flesh out more content! In the meantime, our Demo Application for the /calculate
endpoint is also a great learning resource — see how the request payload changes as you modify inputs!
Test your credentials
Hit the health endpoint to ensure your connection is working.
Calculate endpoint
This is the workhorse of the Building Energy Modeling API.
Input options
You can start with just 3 parameters, a location ((latitude, longitude) pair), and two datetimes defining the beginning and end of the time period for which you want predictions:
{
"location": {
"latitude": 37.7749,
"longitude": -122.4194
},
"parameters": {
"from_datetime": "2019-01-01T00:00:00",
"to_datetime": "2020-01-01T00:00:00",
}
}
If you have an address and need to transform it into a location pairs, you can do so programmatically using a geocoding API.
- Note that geocoding will be included in the back-end in a near future release.
Home attributes
Next, a set of known home attributes is associated with that location. Where any attributes are unknown, probable estimates are derived from distributions conditioned on building location and other factors.
To ensure the most accurate model, an API user can also choose to explicitly pass in home attributes. Attributes may affect either consumption or production, and are nested accordingly. The structures and allowed values are specified in the /calculate
endpoint docs. An example:
{
"location": {
"latitude": 37.7749,
"longitude": -122.4194
},
"parameters": {
"from_datetime": "2019-01-01T00:00:00",
"to_datetime": "2020-01-01T00:00:00",
},
"consumption": {
"attributes": {
"baseline": [
{
"name": "floor_area",
"value": 800
}
],
"hypothetical": [
{
"name": "ev_charging"
"value": True
},
{
"name": "ev_charging_strategy",
"value": "immediate_fast
}
]
}
},
"production": {
"attributes": {
"baseline": [
{
"name": "capacity",
"value": 9
}
]
}
}
}
Baseline vs. Hypothetical
You'll notice the example above has attributes defined as both baseline
and hypothetical
.
baseline
values will update the digital twin in both direct and indirect ways.
- Directly, any
baseline
value passed to the model will override the estimate that the model had originally made for that attribute. - Indirectly, because attributes are sampled from conditional probability distributions, providing a known value for any attribute may then modify the probabilities associated with other attribute values. For example, if I provide a baseline
WallInsulation
value that's substantially higher than the model's initial estimate, the model will likely update theFoundationWallInsulation
to be higher as well.
Only one set of home attributes is used to generate predictions for the building. If any baseline
values are passed, the home attribute set will include a mix of both estimated and user-provided values, as described above. If hypothetical
values are provided, they will override any of the baseline
or estimated values and be used to generate predictions (but probability distributions for estimated attributes are not updated based on hypothetical
values). The API will return one complete set of home attribute values and one associated forecast.
Input known true values about a building into baseline
and what-if scenario values into hypothetical
.
Calibration
Consumption calibration
Consumption calibration is done in 2 ways:
- Sample size calibration (
calibration
parameters): The default value of1
means we pick the most probable digital twin. Passing a valuen
> 1 will buildn
digital twins. The "median," defined as that with the lowest diversion from median hourly load, will be selected as the building's best digital twin. If consumption actuals are provided, the best digital twin is chosen based on diversion from actuals. - Consumption/Production-based calibration (
actuals
parameters): In addition to influencing sample size calibration,actuals
have an impact on the conditional probabilities of home attributes, thus the model may propose different home attribute values ifactuals
are passed.
Production calibration
Production actuals
scale the time series up or down.
Calibration example
{
"location": {
"latitude": 37.7749,
"longitude": -122.4194
},
"parameters": {
"from_datetime": "2019-01-01T00:00:00",
"to_datetime": "2020-01-01T00:00:00",
},
"consumption": {
"actuals": {
[
{
"from_datetime": "2019-03-01T00:00:00",
"to_datetime": "2019-04-01T00:00:00",
"variable": "consumption.electricity",
"value": 712.34
}
]
}
},
"production": {
"actuals": {
[
{
"from_datetime": "2019-03-01T00:00:00",
"to_datetime": "2019-04-01T00:00:00",
"variable": "production.electricity",
"value": 643.21
}
]
}
}
}
Date ranges & granularity
from_datetime
and to_datetime
define the time period for which the API will estimate the home's energy usage.
{
"location": {
"latitude": 37.7749,
"longitude": -122.4194
},
"parameters": {
"from_datetime": "2019-01-01T00:00:00",
"to_datetime": "2020-01-01T00:00:00",
"group_by": "hour"
}
}
The model defaults to returning aggregated figures, but the group_by
parameter may be specified to return data broken out into units of year/month/day/hour.
Disaggregation
By default, the API only returns total electricity consumption, but disaggregated loads are also available by specifying the variables
parameter. For example, let's say we're curious about emissions from plug loads. We can ask for total electricity usage, plug load usage, and total emissions from electricity usage, and use those returned values to compute emissions from plug loads.
{
"location": {
"latitude": 37.7749,
"longitude": -122.4194
},
"parameters": {
"from_datetime": "2019-01-01T00:00:00",
"to_datetime": "2020-01-01T00:00:00",
"variables": [
"consumption.electricity",
"consumption.electricity.plug_loads",
"emissions.electricity"
]
}
}
You can also use the option all
to return forecasts for all possible variables (or, for succinctness, all_non_zero
).
Performance
If you're reading this doc right now, you know the API is freshly released and still considered "beta." We're using this period of time to evaluate performance and establish SLAs. Please flag to us if you hit any bottlenecks or surprises.
Predictions over a longer time frame, or for a larger number sample_size
of digital twins, will take longer.
Updated 8 days ago