API Documentation

PriceOfElectricity.com provides public, read-only JSON endpoints for electricity rate data. The versioned v1 contract is the recommended integration point.

v1 Public Data Contract

The v1 endpoints return structured, deterministic JSON with a stable schema. Fields may be added over time but existing fields will not be removed or renamed within the same version.

GET /api/v1/states

Returns all 50 states with summary metrics.

{
  "version": "v1",
  "generatedAt": "2026-02-22T00:00:00.000Z",
  "states": [
    {
      "slug": "alabama",
      "name": "Alabama",
      "avgResidentialRate": 14.53,
      "avgMonthlyBill": 145.30,
      "affordabilityIndex": 62,
      "valueScore": 58,
      "lastUpdated": "January 2026"
    }
  ]
}

GET /api/v1/state/<slug>

Returns detailed data for a single state, including driver IDs, open rate case count, and timeline event count.

{
  "version": "v1",
  "generatedAt": "2026-02-22T00:00:00.000Z",
  "state": {
    "slug": "texas",
    "name": "Texas",
    "avgResidentialRate": 14.01,
    "avgMonthlyBill": 140.10,
    "affordabilityIndex": 65,
    "valueScore": 60,
    "drivers": ["tx-gen-mix", "tx-demand-growth"],
    "openRateCases": 1,
    "timelineEvents": 3,
    "lastUpdated": "January 2026"
  }
}

Response Headers

  • Content-Type: application/json
  • Cache-Control: public, max-age=3600, stale-while-revalidate=86400

Stability Guarantee

Within the v1 version, existing fields will not be removed or renamed. New fields may be added to response objects. Consumers should ignore unknown keys to maintain forward compatibility.

Example URLs

Legacy Endpoints (unversioned)

These endpoints predate the v1 contract and remain available. They are not covered by the v1 stability guarantee.

  • /api/states.json – full state list
  • /api/state/<slug>.json – single state
  • /api/compare.json?sort=low|high|alpha – comparison feed

Related