API Documentation

v1.0 — Complete reference for the kwcost API

Base URL https://api.kwcost.com

Authentication — All rate, TOU, and calculator endpoints require an API key. Pass x-api-key: <your-key> on all requests.

POST /auth/signup — register with email + password (public)
Check your email for a 6-digit verification code
POST /auth/confirm — verify your email (public)
POST /auth/login — get your access token (public)
Go to Account or call POST /account/api-key with your Bearer token to generate a key
Pass x-api-key: <your-key> on all rate, TOU, and calculator requests

Rate Limits — API requests are subject to the following limits per API key:

Limit	Value
Burst	20 requests
Sustained rate	10 requests / second
Daily quota	5,000 requests / day

Exceeding the rate limit returns 429 Too Many Requests. Daily quotas reset at midnight UTC. Public pages (/, /docs, /coverage, /signup) are not rate-limited.

🔒 Authentication

POST /auth/signup Register a new account ▶

Creates a new user account and sends a verification code to the provided email address. Public — no key needed.

Request Body (JSON)

Field	Type	Description
`email`required	string	Valid email address
`password`required	string	Min 8 chars, uppercase, lowercase, number, special char

Example

curl -X POST "https://api.kwcost.com/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"MyP@ss123"}'

Response — 200

{
  "message": "Signup successful. Check your email for a verification code.",
  "user_confirmed": false
}

POST /auth/confirm Verify your email ▶

Confirms the account using the 6-digit code sent to your email. Public — no key needed.

Request Body (JSON)

Field	Type	Description
`email`required	string	Email used during signup
`code`required	string	6-digit verification code from email

Example

curl -X POST "https://api.kwcost.com/auth/confirm" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","code":"123456"}'

Response — 200

{
  "message": "Email confirmed. You can now log in."
}

POST /auth/login Get access token ▶

Authenticates with email and password, returns JWT tokens. Use the access_token as a Bearer token when managing your account (e.g. generating API keys). Public — no key needed.

Request Body (JSON)

Field	Type	Description
`email`required	string	Registered email
`password`required	string	Account password

Example

curl -X POST "https://api.kwcost.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"MyP@ss123"}'

Response — 200

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJjdHkiOiJKV1QiLCJl..."
}

🔑 Account

GET /account/api-key Get your current API key ▶

Returns the API key associated with your account. Requires a Cognito Bearer token from POST /auth/login.

Headers

Header	Value
`Authorization`required	Bearer <access_token>

Example

curl "https://api.kwcost.com/account/api-key" \
  -H "Authorization: Bearer <access_token>"

Response — 200

{
  "api_key": "abc123def456...",
  "created_at": "2026-03-15T10:30:00Z"
}

POST /account/api-key Generate a new API key ▶

Creates (or rotates) an API key for your account. Any previously issued key is replaced. Requires a Cognito Bearer token from POST /auth/login.

Headers

Header	Value
`Authorization`required	Bearer <access_token>

Example

curl -X POST "https://api.kwcost.com/account/api-key" \
  -H "Authorization: Bearer <access_token>"

Response — 200

{
  "api_key": "abc123def456...",
  "message": "API key created successfully."
}

$ Rates

GET /rates List all jurisdictions & schedules ▶

Returns all available jurisdictions with their rate schedule names grouped by category.

Example

curl "https://api.kwcost.com/rates" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "metadata": { "source": "Duke Energy published tariffs", ... },
  "jurisdictions": {
    "DEC": {
      "name": "Duke Energy Carolinas",
      "states": ["NC", "SC"],
      "schedules": {
        "residential": { "RS": "Residential Service", ... },
        "business": { "SGS": "Small General Service", ... }
      }
    }
  }
}

GET /rates/{jurisdiction} All schedules for a jurisdiction ▶

Returns complete rate data for a specific jurisdiction including all categories and schedules.

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code: `DEC`, `DEP`, `DEI`, `DEF`, `DEO`, `DEK`

Example

curl "https://api.kwcost.com/rates/DEC" \
  -H "x-api-key: YOUR_KEY"

GET /rates/{jurisdiction}/{category} Schedules by category ▶

Returns rate schedules for a jurisdiction filtered by category (residential or business).

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code
`category`required	string	`residential` or `business`

Example

curl "https://api.kwcost.com/rates/DEC/residential" \
  -H "x-api-key: YOUR_KEY"

GET /rates/{jurisdiction}/{category}/{schedule} Full schedule details ▶

Returns the full details for a specific rate schedule including all charges, tiers, and the effective rate summary.

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code
`category`required	string	`residential` or `business`
`schedule`required	string	Schedule code: `RS`, `SGS`, `LGS`, `OPT-V`, etc.

Example

curl "https://api.kwcost.com/rates/DEC/residential/RS" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "jurisdiction": "DEC",
  "category": "residential",
  "schedule_code": "RS",
  "details": {
    "name": "Residential Service",
    "basic_facilities_charge_dollars": 14.00,
    "energy_charges_per_kwh": [
      { "tier": "all kWh", "rate": 0.117845 }
    ]
  },
  "effective_rate_summary": {
    "effective_rate_per_kwh": 0.117845,
    "note": "Excludes fixed monthly charges"
  }
}

GET /rates/{jurisdiction}/riders All riders (mandatory & optional) ▶

Lists all riders for a jurisdiction. Mandatory riders (Fuel Cost, Energy Efficiency, CPRE, DSM, BPM, etc.) are applied automatically by the calculator. Optional riders vary by jurisdiction — see the coverage tab for a full listing. Filter by category or schedule to see which riders apply to your rate.

DEC mandatory rider codes: FC (Fuel), EE (Energy Efficiency), EDPR (DSM/EE Program Rider), BPM (BPM Prospective), BPMTU (BPM True-Up), CPRE (Competitive Procurement), EDIT4 (Tax Reform), CAR (Cost Adjustment Rider), RDM (Revenue Decoupling), ESM (Earnings Sharing), PIM (Performance Incentive), NPTC (Nuclear Production Tax Credit).

Optional riders by jurisdiction: DEF: BA-1, CEC-1, FCF-1, TS-1 — DEO: AER, NSP, NSU, ORH, SC, SE, SFL-ADPL, TD, TD-CPP — DEK: NSU, SC, SE. DEC optional riders: RSC, NM, NMB.

Path Parameters

Parameter	Type	Description
`jurisdiction`required	string	Jurisdiction code

Query Parameters

Parameter	Type	Description
`category`optional	string	Filter: `residential` or `business`
`schedule`optional	string	Filter by eligible schedule code

Example

curl "https://api.kwcost.com/rates/DEC/riders?category=residential" \
  -H "x-api-key: YOUR_KEY"

GET /rates/taxes/{state} Get electricity tax rates for a state ▶

Returns state sales tax, per-kWh excise taxes, gross receipts tax, regulatory fees, and other applicable tax rates for the specified state.

Path Parameters

Parameter	Type	Description
`state`required	string	Two-letter state code: `NC`, `SC`, `IN`, `FL`, `OH`, `KY`

Example

curl "https://api.kwcost.com/rates/taxes/NC" \
  -H "x-api-key: YOUR_KEY"

Response

{
  "sales_tax_rate": 0.07,
  "regulatory_fee_per_kwh": 0.00019
}

⏳ Time-of-Use

GET /tou/schedules List TOU schedule definitions ▶

Returns all available time-of-use schedule definitions with their seasons and holidays.

Example

curl "https://api.kwcost.com/tou/schedules" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "DEC_RESIDENTIAL_TOU": {
    "description": "Duke Energy Carolinas Residential TOU",
    "seasons": ["summer", "non_summer"],
    "holidays": ["2026-01-01", "2026-05-25", ...]
  },
  "DEC_BUSINESS_TOU": { ... },
  "DEP_RESIDENTIAL_TOU": { ... },
  "DEP_BUSINESS_TOU": { ... }
}

GET /tou/now Current TOU period ▶

Returns the TOU period in effect right now for the given schedule, including the current rate.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name, e.g. `DEC_RESIDENTIAL_TOU`, `DEP_BUSINESS_TOU`

Example

curl "https://api.kwcost.com/tou/now?schedule=DEC_RESIDENTIAL_TOU" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "schedule": "DEC_RESIDENTIAL_TOU",
  "datetime": "2026-07-15T14:30:00",
  "season": "summer",
  "period": "on_peak",
  "periods_info": { ... }
}

GET /tou/lookup Lookup period by date/time ▶

Look up the TOU period for any specific date/time combination. Useful for historical or future planning.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name
`datetime`required	string	ISO 8601 datetime, e.g. `2026-07-15T14:30:00`

Example

curl "https://api.kwcost.com/tou/lookup?schedule=DEC_BUSINESS_TOU&datetime=2026-07-15T14:30:00" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "schedule": "DEC_BUSINESS_TOU",
  "datetime": "2026-07-15T14:30:00",
  "season": "summer",
  "period": "on_peak"
}

GET /tou/daily-profile 24-hour TOU profile ▶

Returns a full 24-hour TOU breakdown for a specific date. Shows which period applies for each hour — useful for planning when to run equipment or shift load.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name
`date`required	string	Date in `YYYY-MM-DD` format

Example

curl "https://api.kwcost.com/tou/daily-profile?schedule=DEC_BUSINESS_TOU&date=2026-07-15" \
  -H "x-api-key: YOUR_KEY"

Response — 200

{
  "schedule": "DEC_BUSINESS_TOU",
  "date": "2026-07-15",
  "day_of_week": "Wednesday",
  "season": "summer",
  "summary": {
    "on_peak": "10 hours",
    "off_peak": "14 hours"
  },
  "hours": [
    { "hour": 0, "time": "00:00", "period": "off_peak" },
    ...
  ]
}

GET /tou/tariff/forecast EVCC-compatible hourly price forecast ▶

Returns an hourly price forecast combining TOU periods with the actual energy rate from a rate schedule. Each slot contains a start, end, and value ($/kWh) — directly compatible with EVCC custom tariff plugins and similar time-varying rate consumers.

Query Parameters

Parameter	Type	Description
`schedule`required	string	TOU schedule name (e.g. `DEC_RESIDENTIAL_TOU`)
`jurisdiction`required	string	Jurisdiction code (e.g. `DEC`)
`category`required	string	`residential` or `business`
`rate_schedule`required	string	Rate schedule code (e.g. `RETC`)
`hours`	integer	Hours to forecast, 1–168 (default 48)

Example

curl "https://api.kwcost.com/tou/tariff/forecast?schedule=DEC_RESIDENTIAL_TOU&jurisdiction=DEC&category=residential&rate_schedule=RETC&hours=6" \
  -H "x-api-key: YOUR_KEY"

Response — 200

[
  {
    "start": "2026-03-25T16:00:00-04:00",
    "end": "2026-03-25T17:00:00-04:00",
    "value": 0.097428
  },
  {
    "start": "2026-03-25T17:00:00-04:00",
    "end": "2026-03-25T18:00:00-04:00",
    "value": 0.097428
  },
  {
    "start": "2026-03-25T18:00:00-04:00",
    "end": "2026-03-25T19:00:00-04:00",
    "value": 0.213412
  },
  ...
]

Tip: The Home Assistant integration (v1.1.0+) creates a Tariff Forecast sensor that auto-refreshes this data every hour and exposes it in a forecast attribute ready for EVCC.

⚡ Calculator

POST /calculate/cost Full cost estimate ▶

Estimates total electricity cost for a billing period. Supports flat-rate, tiered, TOU, and demand-billed schedules. Automatically applies mandatory riders (fuel, EE, CPRE, etc.) unless excluded. Optional riders (RSC, NM, NMB) can be added for solar/generation customers.

Request Body (JSON)

Field	Type	Description
`jurisdiction`required	string	Jurisdiction code: `DEC`, `DEP`, etc.
`category`required	string	`residential` or `business`
`schedule`required	string	Rate schedule code
`total_kwh`optional	number	Total kWh consumed (flat-rate schedules). Default: 0
`usage_breakdown`optional	object	Per-period kWh for TOU: `on_peak_kwh`, `off_peak_kwh`, `super_off_peak_kwh`, `shoulder_kwh`
`demand_kw`optional	number	Peak demand in kW (demand-billed schedules). Default: 0
`on_peak_demand_kw`optional	number	On-peak demand in kW. Default: 0
`include_riders`optional	boolean	Include mandatory riders (fuel, EE, CPRE, etc.). Default: true
`exclude_riders`optional	string[]	Mandatory rider codes to exclude, e.g. `["EE"]`. See `GET /rates/{jur}/riders` for codes
`optional_riders`optional	string[]	Optional rider codes to add: `["RSC"]`, `["NM"]`, `["NMB"]`
`exported_kwh`optional	number	kWh exported to grid (for solar credit calculation). Default: 0
`nameplate_capacity_kw`optional	number	System nameplate capacity in kW (for RSC/NMB per-kW charges). Default: 0

Example — Simple Residential

curl -X POST "https://api.kwcost.com/calculate/cost" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "DEC",
    "category": "residential",
    "schedule": "RS",
    "total_kwh": 1000
  }'

Response — 200

{
  "jurisdiction": "DEC",
  "schedule": "RS",
  "total_kwh": 1000,
  "mandatory_riders_applied": ["FC", "EE", "EDPR", "BPM", ...],
  "mandatory_riders_excluded": [],
  "optional_riders_applied": [],
  "line_items": [
    { "item": "Basic Facilities Charge Dollars", "amount": 14.00 },
    { "item": "Energy charge (all kWh)", "rate_per_kwh": 0.117845, "kwh": 1000, "amount": 117.85 },
    { "item": "Rider FC: Fuel Cost", "rate_per_kwh": 0.02616, "kwh": 1000, "amount": 26.16 },
    "...more riders..."
  ],
  "total_estimated_cost": 136.80,
  "effective_cost_per_kwh": 0.13680
}

Example — TOU with Demand

curl -X POST "https://api.kwcost.com/calculate/cost" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "DEC",
    "category": "business",
    "schedule": "OPT-V",
    "usage_breakdown": {
      "on_peak_kwh": 20000,
      "off_peak_kwh": 50000,
      "super_off_peak_kwh": 10000
    },
    "demand_kw": 150,
    "on_peak_demand_kw": 120
  }'

POST /calculate/quick Quick cost estimate ▶

Simplified cost estimate — just provide jurisdiction, schedule, and kWh. Returns the estimated total without a full line-item breakdown.

Request Body (JSON)

Field	Type	Description
`jurisdiction`required	string	Jurisdiction code
`schedule`required	string	Rate schedule code
`kwh`required	number	Total kWh consumed

Example

curl -X POST "https://api.kwcost.com/calculate/quick" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"DEC","schedule":"RS","kwh":1000}'

Response — 200

{
  "jurisdiction": "DEC",
  "schedule": "RS",
  "kwh": 1000,
  "estimated_cost": 131.85,
  "effective_rate": 0.13185
}

⚠ Error Responses

All errors follow a consistent format. Common HTTP status codes:

Status	Meaning
`400`	Bad request — invalid parameters or body
`401`	Unauthorized — missing or invalid Bearer token
`403`	Forbidden — missing or invalid API key
`404`	Not found — invalid jurisdiction, category, or schedule
`409`	Conflict — account already exists (signup)
`422`	Validation error — request body failed schema validation
`429`	Too many requests — rate limit exceeded

Error Format

{
  "detail": "Schedule 'XYZ' not found. Available: ['RS', 'RSTC', ...]"
}

Jurisdictions

131

Rate Schedules

TOU Schedules

Riders

⚖ Rate Schedules by Jurisdiction

DEC Duke Energy Carolinas NC, SC 8 residential17 business ▶

Residential

Code	Description
`RS`	Residential Service
`RSTC`	Residential Service — Time of Use Critical Peak
`RSTOU`	Residential Service — Time of Use
`RE`	Residential Service — All Electric
`RETC`	Residential Service — All Electric, Time of Use Critical Peak
`RT`	Residential Service — Water & Space Heating
`RT-EV`	Residential Service — Electric Vehicle
`ES`	Residential Service — Economy

Business

Code	Description
`SGS`	Small General Service
`SGSTC`	Small General Service — Time of Use Critical Peak
`LGS`	Large General Service
`I`	Industrial Service
`OPT-V`	Optional Power Service — Voluntary
`TS`	Traffic Signal Service
`PG`	Parallel Generation
`PP`	Purchased Power
`PP-LQF`	Purchased Power — Large Qualifying Facility
`OL`	Outdoor Lighting
`NL`	Night Lighting
`PL`	Public Lighting
`MP`	Municipal Street Lighting — Private
`BC`	Border Customer
`HLF`	High Load Factor

DEP Duke Energy Progress NC, SC 6 residential30 business ▶

Residential

Code	Description
`RES`	Residential Service
`R-TOU`	Residential — Time of Use
`R-TOUD`	Residential — Time of Use with Demand
`R-TOU-CPP`	Residential — Time of Use Critical Peak Pricing
`R-TOU-EV`	Residential — Time of Use Electric Vehicle
`R-STOU`	Residential — Smart Time of Use

Business

Code	Description
`SGS`	Small General Service
`SGS-TOUE`	Small General Service — TOU Energy
`SGS-TOU-CPP`	Small General Service — TOU Critical Peak Pricing
`SGS-TOU-CLR`	Small General Service — TOU Clean Energy Rate
`MGS`	Medium General Service
`MGS-TOU`	Medium General Service — Time of Use
`LGS`	Large General Service
`LGS-TOU`	Large General Service — Time of Use
`LGS-RTP`	Large General Service — Real Time Pricing
`LGS-RTP-TOU`	Large General Service — RTP Time of Use
`LGS-CUR-TOU`	Large General Service — Curtailable TOU
`LGS-HLF`	Large General Service — High Load Factor
`GS`	General Service
`GS-TES`	General Service — Thermal Energy Storage
`SI`	Seasonal Industrial
`CSG`	Community Solar Guest
`CSE`	Clean Schedule Energy
`CH-TOUE`	Church — TOU Energy
`EVSE`	Electric Vehicle Supply Equipment
`HP`	Hourly Pricing
`PP`	Purchased Power
`PPBE`	Purchased Power — Biomass Energy
`PPL-7`	Purchased Power — Long-term (7+ years)
`TFS`	Time of Use Flex Savings
`TSS`	Time Scheduled Service
`ALS`	Area Lighting Service
`APH-TES`	All-Purpose Heat — Thermal Storage
`SLS`	Street Lighting Service
`SFLS`	Security & Flood Lighting Service
`SLR`	Street Lighting Rental

DEF Duke Energy Florida FL 4 residential15 business ▶

Residential

Code	Description
`RS-1`	Residential Service
`RST-1`	Residential Service — Time of Use
`RSL-1`	Residential Service — Low Usage
`RSL-2`	Residential Service — Low Usage (multi-family)

Business

Code	Description
`GS-1`	General Service — Non-Demand
`GSD-1`	General Service — Demand
`GSLM-1`	General Service — Large Demand
`GSLM-2`	General Service — Large Demand (secondary)
`CS-2`	Curtailable Service
`CS-3`	Curtailable Service (interruptible)
`CST-2`	Curtailable Service — Time of Use
`CST-3`	Curtailable Service — Time of Use (interruptible)
`IS-2`	Interruptible Service
`IST-2`	Interruptible Service — Time of Use
`LS-1`	Lighting Service
`SS-1`	Street Lighting Service
`SS-2`	Street Lighting Service (customer-owned)
`SS-3`	Street Lighting Service (LED)

Riders

BA-1 CEC-1 FCF-1 TS-1

DEI Duke Energy Indiana IN 3 residential15 business ▶

Residential

Code	Description
`RS`	Residential Service
`RS-TOU`	Residential Service — Time of Use
`RS-HE`	Residential Service — High Efficiency

Business

Code	Description
`CS`	Commercial Service
`CS-TOU`	Commercial Service — Time of Use
`CS-HE`	Commercial Service — High Efficiency
`HLF`	High Load Factor
`HLF-LLF-TOU`	High Load Factor — Low Load Factor TOU
`LLF-HE`	Low Load Factor — High Efficiency
`MS`	Miscellaneous Service
`WP`	Water Pumping
`EVFC`	Electric Vehicle Fast Charging
`EVSE`	Electric Vehicle Supply Equipment
`SL`	Street Lighting
`MHLS`	Municipal Highway Lighting Service
`MOLS`	Municipal Outdoor Lighting Service
`UOLS`	Utility Outdoor Lighting Service
`USFL`	Utility Security & Flood Lighting

DEO Duke Energy Ohio OH 3 residential14 business ▶

Ohio is a deregulated state — these are distribution-only rates. Generation is purchased separately from a retail supplier.

Residential

Code	Description
`RS`	Residential Service
`RS3P`	Residential Service — Three-Phase
`RSLI`	Residential Service — Low Income

Business

Code	Description
`DS`	Distribution Service
`DP`	Distribution Power
`DM`	Distribution — Master Metered
`GS-FL`	General Service — Flood Lighting
`GSP`	General Service — Primary
`EH`	Electric Heating
`TS`	Traffic Signal Service
`SL`	Street Lighting
`TL`	Traffic Lighting
`OL`	Outdoor Lighting
`LED`	LED Lighting
`UOLS`	Utility Outdoor Lighting Service

Riders

AER NSP NSU ORH SC SE SFL-ADPL TD TD-CPP

DEK Duke Energy Kentucky KY 1 residential16 business ▶

Residential

Code	Description
`RS`	Residential Service

Business

Code	Description
`DS`	Distribution Service
`DP`	Distribution Power
`DT`	Distribution — Transmission
`SP`	Standard Power
`TT`	Transmission — Time of Use
`GS-FL`	General Service — Flood Lighting
`EH`	Electric Heating
`SL`	Street Lighting
`TL`	Traffic Lighting
`LED`	LED Lighting
`UOLS`	Utility Outdoor Lighting Service

Riders

NSU SC SE

⏳ Time-of-Use Schedules

DEC Residential TOU

Duke Energy Carolinas residential time-of-use schedule with seasonal rates and holiday handling.

On-Peak Off-Peak Super Off-Peak

DEC Business TOU

Duke Energy Carolinas business time-of-use schedule with on-peak, shoulder, and off-peak periods.

On-Peak Shoulder Off-Peak

DEP Residential TOU

Duke Energy Progress residential time-of-use schedule for TOU and Smart TOU rate plans.

On-Peak Off-Peak Super Off-Peak

DEP Business TOU

Duke Energy Progress business time-of-use schedule for SGS-TOUE, MGS-TOU, and LGS-TOU rate plans.

On-Peak Shoulder Off-Peak

﹯ Tax Estimation

Estimate state and local electricity taxes across all Duke Energy service territories. Includes 50+ municipalities.

State	State Tax	Local Tax
NC	7% sales tax + $0.00019/kWh regulatory fee	Franchise tax up to 3.09% — 24 municipalities
SC	6% sales tax	Local option 1–2%
IN	7% sales tax	—
FL	2.5% gross receipts tax	Public service tax up to 10%
OH	$0.00465/kWh excise tax	—
KY	6% sales tax	Franchise tax ~3%

Prerequisites — All examples below assume you have an API key. Replace YOUR_KEY with your actual key from Account.

1. Get a Rate

Look up the current residential rate for Duke Energy Carolinas.

curl "https://api.kwcost.com/rates/DEC/residential/RS" \
  -H "x-api-key: YOUR_KEY"

import requests

resp = requests.get(
    "https://api.kwcost.com/rates/DEC/residential/RS",
    headers={"x-api-key": "YOUR_KEY"}
)
data = resp.json()
print(f"Rate: {data['effective_rate_summary']['effective_rate_per_kwh']} $/kWh")

const resp = await fetch("https://api.kwcost.com/rates/DEC/residential/RS", {
  headers: { "x-api-key": "YOUR_KEY" }
});
const data = await resp.json();
console.log(`Rate: ${data.effective_rate_summary.effective_rate_per_kwh} $/kWh`);

2. Check TOU Period

Find out if it is currently on-peak or off-peak for a DEC residential TOU schedule.

curl "https://api.kwcost.com/tou/now?schedule=DEC_RESIDENTIAL_TOU" \
  -H "x-api-key: YOUR_KEY"

import requests

resp = requests.get(
    "https://api.kwcost.com/tou/now",
    params={"schedule": "DEC_RESIDENTIAL_TOU"},
    headers={"x-api-key": "YOUR_KEY"}
)
data = resp.json()
print(f"Period: {data['period']}  Season: {data['season']}")

const resp = await fetch(
  "https://api.kwcost.com/tou/now?schedule=DEC_RESIDENTIAL_TOU",
  { headers: { "x-api-key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(`Period: ${data.period}  Season: ${data.season}`);

3. Calculate a Bill

Estimate a monthly bill for 1,000 kWh on the DEC residential RS schedule, including all mandatory riders.

curl -X POST "https://api.kwcost.com/calculate/cost" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "DEC",
    "category": "residential",
    "schedule": "RS",
    "total_kwh": 1000
  }'

import requests

resp = requests.post(
    "https://api.kwcost.com/calculate/cost",
    headers={
        "x-api-key": "YOUR_KEY",
        "Content-Type": "application/json"
    },
    json={
        "jurisdiction": "DEC",
        "category": "residential",
        "schedule": "RS",
        "total_kwh": 1000
    }
)
bill = resp.json()
print(f"Total: ${bill['total_estimated_cost']:.2f}")
print(f"Effective: ${bill['effective_cost_per_kwh']:.4f}/kWh")
for item in bill["line_items"]:
    print(f"  {item['item']}: ${item['amount']:.2f}")

const resp = await fetch("https://api.kwcost.com/calculate/cost", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    jurisdiction: "DEC",
    category: "residential",
    schedule: "RS",
    total_kwh: 1000
  })
});
const bill = await resp.json();
console.log(`Total: $${bill.total_estimated_cost.toFixed(2)}`);
console.log(`Effective: $${bill.effective_cost_per_kwh.toFixed(4)}/kWh`);

4. Tariff Forecast (EVCC)

Get an hourly price forecast for the next 24 hours, suitable for EVCC smart charging or load shifting.

curl "https://api.kwcost.com/tou/tariff/forecast?schedule=DEC_RESIDENTIAL_TOU&jurisdiction=DEC&category=residential&rate_schedule=RETC&hours=24" \
  -H "x-api-key: YOUR_KEY"

import requests

resp = requests.get(
    "https://api.kwcost.com/tou/tariff/forecast",
    params={
        "schedule": "DEC_RESIDENTIAL_TOU",
        "jurisdiction": "DEC",
        "category": "residential",
        "rate_schedule": "RETC",
        "hours": 24
    },
    headers={"x-api-key": "YOUR_KEY"}
)
slots = resp.json()
for s in slots:
    print(f"{s['start']}  ${s['value']:.6f}/kWh")

const params = new URLSearchParams({
  schedule: "DEC_RESIDENTIAL_TOU",
  jurisdiction: "DEC",
  category: "residential",
  rate_schedule: "RETC",
  hours: "24"
});
const resp = await fetch(
  `https://api.kwcost.com/tou/tariff/forecast?${params}`,
  { headers: { "x-api-key": "YOUR_KEY" } }
);
const slots = await resp.json();
slots.forEach(s =>
  console.log(`${s.start}  $${s.value.toFixed(6)}/kWh`)
);