{"openapi":"3.1.0","info":{"title":"Average Electric Bill API","version":"1.0.0","description":"U.S. household electricity data from the U.S. Energy Information Administration (EIA): check whether a bill is normal for similar homes, average rates and bills by state, and utility rates. Free, no key. Statistical comparisons, not bill audits."},"servers":[{"url":"https://averageelectricbill.com"}],"paths":{"/api/v1/check":{"get":{"operationId":"checkElectricBill","summary":"Check whether a U.S. household's electric bill is normal","description":"Compares one month's kWh and price with similar homes (same state climate, home size, household size, month). Returns the usage percentile, typical kWh range, rate vs. state or utility average, dollar gap to a typical home, estimated AC or heating share, likely causes, and a link to the full result.","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"U.S. state or D.C.: two-letter code or name","example":"TX"},{"name":"home_size_sqft","in":"query","required":true,"schema":{"type":"number"},"description":"Home size in square feet","example":1800},{"name":"household_size","in":"query","required":true,"schema":{"type":"number"},"description":"Number of people in the home (1-20)","example":3},{"name":"kwh","in":"query","required":true,"schema":{"type":"number"},"description":"kWh used on the bill (one month)","example":1500},{"name":"amount_due","in":"query","required":false,"schema":{"type":"number"},"description":"Total amount due in USD; enables the rate comparison","example":240},{"name":"month","in":"query","required":false,"schema":{"type":"number"},"description":"Month the bill covers, 1-12; recommended","example":7},{"name":"utility","in":"query","required":false,"schema":{"type":"string"},"description":"Electric utility or retail provider name","example":"Oncor"}],"responses":{"200":{"description":"summary is a short plain-English answer; data holds every figure and a link to the full page.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/states":{"get":{"operationId":"getStateElectricityStats","summary":"Average electricity rate, use and bill by U.S. state","description":"Latest 12 months of EIA data: cents per kWh, monthly kWh, monthly bill, 1- and 5-year price change. Omit state for all 50 states and D.C. sorted by price.","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Two-letter code, state name, or US. Omit for every state.","example":"CA"}],"responses":{"200":{"description":"summary is a short plain-English answer; data holds every figure and a link to the full page.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/utilities":{"get":{"operationId":"findUtilityRate","summary":"Look up a U.S. electric utility's average residential rate","description":"Search utilities and retail providers by name or initials (PG&E, SRP, Duke Energy). Average price per kWh paid by residential customers over the year (EIA Form 861), not current plan offers.","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Utility name or initials","example":"Duke Energy"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Optional state filter","example":"NC"}],"responses":{"200":{"description":"summary is a short plain-English answer; data holds every figure and a link to the full page.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}