API Reference

Authentication

All endpoints except /v1/signup and the OpenAPI docs require an API key. Pass it as an HTTP header:

x-api-key: YOUR_API_KEY

Get a free key (1,000 requests/month) on the home page or via the API:

curl -X POST https://api.kwhpulse.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response:

{
  "api_key": "abc123xyz...",
  "message": "API key created. Keep it safe — it won't be shown again."
}

Common parameters

GET /v1/prices/state/{state}

Returns historical monthly electricity prices for a US state.

Path parameters

Query parameters

Example request

curl "https://api.kwhpulse.com/v1/prices/state/OR?sector=RES&start=2020-01" \
  -H "x-api-key: YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.kwhpulse.com/v1/prices/state/OR",
    params={"sector": "RES", "start": "2020-01"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(r.json())

const res = await fetch(
  "https://api.kwhpulse.com/v1/prices/state/OR?sector=RES&start=2020-01",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data);

Example response

{
  "state": "OR",
  "sector": "RES",
  "data": [
    {
      "price_cents_per_kwh": 1392,
      "price_dollars_per_kwh": 13.92,
      "sector": "RES",
      "source": "eia861m",
      "period": "2024-01"
    }
  ]
}

GET /v1/prices/zip/{zip}

Returns historical monthly electricity prices for a US ZIP code, resolved via the ZIP→utility→state mapping.

Path parameters

Query parameters

Example request

curl "https://api.kwhpulse.com/v1/prices/zip/97333?sector=RES" \
  -H "x-api-key: YOUR_API_KEY"

GET /v1/prices/utility/{utility_id}

Returns historical monthly electricity prices for a specific utility, identified by its EIA utility ID.

Path parameters

Example request

curl "https://api.kwhpulse.com/v1/prices/utility/14354?sector=RES" \
  -H "x-api-key: YOUR_API_KEY"

GET /v1/utilities

Returns the list of utilities serving a given ZIP code.

Query parameters

Example response

{
  "zip": "97333",
  "state": "OR",
  "utility_ids": ["14354", "4743"]
}

GET /v1/rankings/states

Returns all 50 states + DC ranked by current average price for a given sector.

Query parameters

Example request

curl "https://api.kwhpulse.com/v1/rankings/states?sector=RES&order=asc" \
  -H "x-api-key: YOUR_API_KEY"

GET /v1/compare/zips

Compare current and historical prices across multiple ZIP codes side-by-side.

Query parameters

Example request

curl "https://api.kwhpulse.com/v1/compare/zips?zips=97333,94102,10001&sector=RES" \
  -H "x-api-key: YOUR_API_KEY"

GET /openapi.json

OpenAPI 3.1 specification for the entire kWhPulse API. No API key required.

curl "https://api.kwhpulse.com/openapi.json"

Error codes