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 the FoundationWallInsulation 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:

  1. Sample size calibration (calibration parameters): The default value of 1 means we pick the most probable digital twin. Passing a value n > 1 will build n 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.
  2. 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 if actuals 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.