Recipes

Annual monthly electric bill from one or more known readings

The EI API can predict monthly usage for any home in the US with just an address, but by providing historical usage readings, the predictions are more reliable to your customer.

In this Recipe

1. Set up environment
2. Standard method to hit the EI API
3. Method to build a payload for a customer with known usage

Method to parse a simple month-to-kwh dict from the API response

1. Putting it all together
2. Baseline Example: what if we know nothing?
3. Example with 1 known usage month
4. Example with 2 known usage months

Python Code

import os
import json
import requests
from datetime import datetime

def get_ei_response(payload, ei_api_key=os.getenv("EIAPI_DEV_API_KEY")):
    url = "https://ei.palmetto.com/api/v0/bem/calculate"
    headers = {
        "accept": "application/json",
        "content-type": "application/json",
        "X-API-Key": ei_api_key
    }
    response = requests.post(url, json=payload, headers=headers)
    return response.text

def get_customer_payload(address, usage_dict):
    customer_payload = {
        "parameters": {
            "from_datetime": "2025-01-01T00:00:00",
            "to_datetime": "2025-12-31T23:59:59",
            "variables": ["consumption.electricity"],
            "group_by": "month"
        },
        "location": {
            "address": address
        }
    }
    if usage_dict:
        customer_payload["consumption"] = {
            "actuals": usage_dict
        }
    return customer_payload

def parse_response(json_string, attribute_list=[]):
    parsed = json.loads(json_string)
    predictions = {}
    for prediction_dict in parsed['data']['intervals']:
        predictions[
            datetime.fromisoformat(prediction_dict['from_datetime']).month
        ] = prediction_dict['value']
    return predictions

def interpolate_year_from_known_usage(address, known_usage_dict):
    payload_with_usage = get_customer_payload(address, known_usage_dict)
    ei_response = get_ei_response(payload_with_usage)
    interpolated_year = parse_response(ei_response)
    return interpolated_year

# Baseline Example: passing no known billed usage months
address = "929 Maxwell Ave. Boulder, CO 80304"
twelve_months_from_none = interpolate_year_from_known_usage(address=address, known_usage_dict=None)
twelve_months_from_none

# Example 1: passing a single known billed usage month
address = "929 Maxwell Ave. Boulder, CO 80304"
known_kwh_usage = [
    {
        "from_datetime": "2023-01-01T00:00:00",
        "to_datetime": "2023-01-31T23:59:59",
        "variable":"consumption.electricity",
        "value": 758
    }
]
twelve_months_from_one = interpolate_year_from_known_usage(address=address, known_usage_dict=known_kwh_usage)
twelve_months_from_one

# Example 2: passing a single known billed usage month
address = "929 Maxwell Ave. Boulder, CO 80304"
known_kwh_usage = [
    {
        "from_datetime": "2023-01-01T00:00:00",
        "to_datetime": "2023-01-31T23:59:59",
        "variable":"consumption.electricity",
        "value": 758
    },
    {
        "from_datetime": "2024-07-01T00:00:00",
        "to_datetime": "2024-07-31T23:59:59",
        "variable":"consumption.electricity",
        "value": 708
    }
]
twelve_months_from_two = interpolate_year_from_known_usage(address=address, known_usage_dict=known_kwh_usage)
twelve_months_from_two