## Access  
If you don't have an API key yet, sign up for free limited access [here](https://ei.palmetto.com/)!

When logged in, your API Key will appear here:

`YOUR_API_KEY`

Free limited access includes 100 successful requests every month to the `/calculate` endpoint. Your API key can also be used for our [Sandbox Demo Application](https://ei.palmetto.com/demo). If you prefer the [Swagger](https://ei.palmetto.com/api/v0/swagger) or [Redoc](https://ei.palmetto.com/api/v0/redoc) flavor of API documentation, we have those too!

For any questions or to report bugs, please reach out to [ei-api@palmetto.com](mailto:ei-api@palmetto.com).

## What is this page  
The [API Reference](https://ei.docs.palmetto.com/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](https://ei.palmetto.com/demo) 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](https://ei.docs.palmetto.com/reference/health_api_v0_health_get-1) 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 4 parameters: an address, two datetimes defining the beginning and end of the time period for which you want predictions, and the list of `variables` to return:

### JSON
```json
{
  "location": {
    "address": "123 Maplewood Drive, Springfield, IL 62704"
  },
  "parameters": {
    "from_datetime": "2019-01-01T00:00:00",
    "to_datetime": "2020-01-01T00:00:00",
    "variables": ["consumption.electricity"]
  }
}
```

### Home attributes  
Next, a set of known home attributes is associated with that address. 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:

### JSON
```json
{
  "location": {
    "address": "123 Maplewood Drive, Springfield, IL 62704"
  },
  "parameters": {
    "from_datetime": "2019-01-01T00:00:00",
    "to_datetime": "2020-01-01T00:00:00",
    "variables": ["consumption.electricity"]
  },
  "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": "panel_arrays", "value": [{"tilt": 20, "azimuth": 180, "capacity": 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  
### JSON
```json
{
  "location": {
    "address": "123 Maplewood Drive, Springfield, IL 62704"
  },
  "parameters": {
    "from_datetime": "2019-01-01T00:00:00",
    "to_datetime": "2020-01-01T00:00:00",
    "variables": ["consumption.electricity", "production.electricity"]
  },
  "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.

### JSON
```json
{
  "location": {
    "address": "123 Maplewood Drive, Springfield, IL 62704"
  },
  "parameters": {
    "from_datetime": "2019-01-01T00:00:00",
    "to_datetime": "2020-01-01T00:00:00",
    "variables": ["consumption.electricity"],
    "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  
The required `variables` parameter controls which forecasts the API returns. Pass a list of specific variable names to ask only for what you need — for example, total electricity usage, plug-load usage, and total electricity emissions, which together let you compute emissions from plug loads:

### JSON
```json
{
  "location": {
    "address": "123 Maplewood Drive, Springfield, IL 62704"
  },
  "parameters": {
    "from_datetime": "2019-01-01T00:00:00",
    "to_datetime": "2020-01-01T00:00:00",
    "variables": [
      "consumption.electricity",
      "consumption.electricity.plug_loads",
      "emissions.electricity"
    ]
  }
}
```

For convenience, `variables` also accepts the shortcuts `"all"` (every available forecast variable) and `"all_non_zero"` (drop columns that are zero across every interval).

## 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 27 days ago**