Denkiya API docs

A short guide to get oriented, then an interactive API reference — change inputs and the request snippets update. Estimate and rates include a live Try it (keys stay on our servers).

Guide

Getting started

How to think about the Denkiya API — then copy a first request in your language of choice.

Access

If you don't have an API key yet, join Community for free evaluation (250 successful calculations / month, non-commercial prototypes), or choose Standard or Pro and check out with Stripe. Custom plans are available by request. After checkout, sign in at denkiya.app with the same email to view your key in Settings.

Base URL: https://www.denkiya.app

Authenticate with x-api-key or Authorization: Bearer …. Replace YOUR_API_KEY with the key we issue you — call from your server for production traffic.

curl -X POST 'https://www.denkiya.app/api/public/estimate' \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"type":"Vehicle","fuelType":"Gasoline","vehicleType":"Sedan","state":"CA"}'

What this page is

The sections below are an interactive API reference: every parameter you can tweak in the builders updates the request. This Getting started section is the guide — tips for picking an endpoint and wiring your first call. Estimate and rates also run live through denkiya.co's proxy so your browser never sees an API key.

Your first request

Start with a gasoline sedan in California — enough to prove auth and see an annual dollar change come back (positive when the upgrade saves money). Swap languages in the tabs, paste your key, and run it from your machine or backend.

curl -X POST 'https://www.denkiya.app/api/public/estimate' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
  -d '{
  "type": "Vehicle",
  "fuelType": "Gasoline",
  "vehicleType": "Sedan",
  "state": "CA",
  "annualMileage": 13500
}'

Prefer clicking around first? Jump to the vehicle estimate builder.

Choose an endpoint

Three public surfaces. Pick the lightest one that fits your product.

Estimate

POST /api/public/estimate

Widget-ready operating costs plus amountSaved (same field and sign as calculate). Pass type (Vehicle, Water Heater, HVAC, Clothes Dryer, Cooktop, Oven) plus a few overrides. Top-level avg / low / high stay as aliases for widgets. HVAC uses envelope (typical, leaky, very-leaky) and may include heating/cooling limbs on amountSaved.

Calculate

POST /api/public/v1/calculate

Fuller inputs and outputs, optional monthly breakdowns. amountSaved is positive when switching current → comparison saves money.

Rates ticker

GET /api/public/rates/ticker

Current EIA-backed residential rates by state (or national). Does not count against your monthly calculation quota.

Reading results

Dollars, signs, and labels so widgets don't invert a cooktop that costs more.

On estimate and public calculate, positive means dollars per year saved by switching current → comparison. Negative means the comparison costs more. Values are cents (two decimal places), not whole dollars.

Prefer savingsClass (and savingsSummary) for UI copy: big-savings, healthy-savings, modest-savings, break-even, no-savings. Use the dollar figure for the number. Render no-savings as “costs more,” not “you save.”

Every /api/public/* JSON body (success and errors) starts with api, route, and version. Savings routes: Denkiya Public Savings API V1. Ticker: Denkiya Public Rates API V1. Ignore unknown extra keys.

Estimate also returns assumptions (usage after defaults), plus current / comparison operating costs and top-level amountSaved. Vehicle estimates echo mpg, mpkwh, whPerMile, and stateName. Estimate and calculate success bodies include amountSavedConvention: "positive_means_savings". Optional period (last-12-months) uses the trailing window's end year on both routes.

Vehicle nuance: estimate with Electric as the primary vs gasoline is the “EV vs gas” story. Calculate is always savings by switching to compareTo.

API reference

POST/api/public/estimate

Vehicle estimate

Annual operating costs and dollar change for a vehicle pair. Same unified estimate route — set type to Vehicle. Omit mpg / Wh/mi to use engine defaults (echoed on the response), or override them as real inputs.

Fuel typeVehicle typeStateAnnual mileageMPG (optional)Wh / mile (optional)

Runs through denkiya.co’s same-origin proxy — your browser never sees an API key.

curl -X POST 'https://www.denkiya.app/api/public/estimate' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
  -d '{
  "type": "Vehicle",
  "fuelType": "Gasoline",
  "vehicleType": "Sedan",
  "state": "CA",
  "annualMileage": 13500
}'

Example response (illustrative)

{
  "api": "Denkiya Public Savings API V1",
  "route": "/api/public/estimate",
  "version": 1,
  "type": "Vehicle",
  "state": "CA",
  "assumptions": {
    "summary": "13,500 miles/year Sedan. Gasoline → Electric.",
    "annualMileage": 13500,
    "vehicleType": "Sedan",
    "mpg": 30.4,
    "mpkwh": 3.5,
    "whPerMile": 286
  },
  "mpg": 30.4,
  "mpkwh": 3.5,
  "whPerMile": 286,
  "stateName": "California",
  "current": {
    "label": "Gasoline Sedan",
    "annualCostUsd": { "avg": 2126.89, "low": 2020.55, "high": 2233.23 }
  },
  "comparison": {
    "label": "Electric",
    "annualCostUsd": { "avg": 1129.99, "low": 1073.49, "high": 1186.49 }
  },
  "amountSavedConvention": "positive_means_savings",
  "amountSaved": {
    "avg": 996.9,
    "low": 834.06,
    "high": 1159.74
  },
  "avg": 996.9,
  "low": 834.06,
  "high": 1159.74,
  "savingsClass": "big-savings",
  "savingsSummary": "Big savings"
}

POST/api/public/estimate

Water heater estimate

Default story: recent gas tank → new efficient heat pump. Same POST /api/public/estimate route — set type to Water Heater. Ages echo on current / comparison when present.

StateHousehold size

Runs through denkiya.co’s same-origin proxy — your browser never sees an API key.

curl -X POST 'https://www.denkiya.app/api/public/estimate' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
  -d '{
  "type": "Water Heater",
  "state": "CA",
  "householdSize": 3
}'

Example response (illustrative)

{
  "api": "Denkiya Public Savings API V1",
  "route": "/api/public/estimate",
  "version": 1,
  "type": "Water Heater",
  "state": "CA",
  "assumptions": {
    "summary": "3-person household, 63 gal/day. Recent natural gas tank → New Efficient Heat Pump.",
    "householdSize": 3,
    "gallonsPerDay": 63
  },
  "current": {
    "label": "Natural Gas Tank",
    "age": "Recent",
    "annualCostUsd": { "avg": 397.76, "low": 377.93, "high": 430.51 }
  },
  "comparison": {
    "label": "Electric Efficient Heat Pump Tank",
    "age": "New",
    "annualCostUsd": { "avg": 291.13, "low": 270.04, "high": 309.55 }
  },
  "amountSavedConvention": "positive_means_savings",
  "amountSaved": {
    "avg": 106.63,
    "low": 68.38,
    "high": 160.47
  },
  "avg": 106.63,
  "low": 68.38,
  "high": 160.47,
  "savingsClass": "modest-savings",
  "savingsSummary": "Modest savings"
}

POST/api/public/estimate

Cooktop estimate

Annual dollar change for switching to induction (default gas → induction). In high-electricity states this is often no-savings — render the sign, don’t assume a win. Same POST /api/public/estimate route — set type to Cooktop. If omitted, mealsPerWeek defaults to 10.

StateMeals per week

Runs through denkiya.co’s same-origin proxy — your browser never sees an API key.

curl -X POST 'https://www.denkiya.app/api/public/estimate' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
  -d '{
  "type": "Cooktop",
  "state": "CA",
  "mealsPerWeek": 10
}'

Example response (illustrative)

{
  "api": "Denkiya Public Savings API V1",
  "route": "/api/public/estimate",
  "version": 1,
  "type": "Cooktop",
  "state": "CA",
  "assumptions": {
    "summary": "3-person household, 10 meals/week. natural gas cooktop → Induction.",
    "householdSize": 3,
    "mealsPerWeek": 10
  },
  "current": {
    "label": "Natural Gas Cooktop",
    "annualCostUsd": { "avg": 111.79 }
  },
  "comparison": {
    "label": "Induction",
    "annualCostUsd": { "avg": 240.53 }
  },
  "amountSavedConvention": "positive_means_savings",
  "amountSaved": {
    "avg": -128.74
  },
  "avg": -128.74,
  "savingsClass": "no-savings",
  "savingsSummary": "Switching costs more"
}

GET/api/public/rates/ticker

Rates ticker

Current EIA-backed residential energy rates for a state (or national). Default window is trailing 12 months; optional ?year=2024 (calendar) or ?period=last-12-months | calendar. Does not count against monthly calculation quota. Item objects may include extra keys — ignore them.

State

Unmetered for monthly quota — fair-use per-minute limits still apply.

curl 'https://www.denkiya.app/api/public/rates/ticker?state=CA' \
  -H "Accept: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Example response (illustrative)

{
  "api": "Denkiya Public Rates API V1",
  "route": "/api/public/rates/ticker",
  "version": 1,
  "state": "CA",
  "period": {
    "label": "Trailing 12 months",
    "startPeriod": "2025-09",
    "endPeriod": "2026-08"
  },
  "items": [
    {
      "id": "electricity",
      "label": "Electricity",
      "avgCost": 0.312,
      "unit": "/kWh",
      "changePct": 2.1,
      "direction": "up"
    }
  ]
}

Full calculate

Vehicles, HVAC, water heaters, dryers, cooktops, and ovens. amountSaved is positive when the comparison costs less than current. amountSavedConvention on success bodies is positive_means_savings. Same year / period rules as estimate.

POST/api/public/v1/calculate

Full calculate

Richer inputs and outputs for custom product UIs. amountSaved is positive when switching current → comparison saves money (same field as estimate). Success bodies include amountSavedConvention and data.savingsClass, plus the api / route / version banner. Optional period last-12-months uses trailing rates, same as estimate. Tune inputs below — the request updates instantly.

TypeStateYearFuel typeVehicle typeAnnual mileageCompare to (optional)Include monthly breakdown

Runs through denkiya.co’s same-origin proxy — your browser never sees an API key.

curl -X POST 'https://www.denkiya.app/api/public/v1/calculate' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
  -d '{
  "type": "Vehicle",
  "fuelType": "Gasoline",
  "usage": {
    "annualMileage": 13500,
    "chargingHabits": 0,
    "electricMiles": 0,
    "vehicleType": "Sedan"
  },
  "year": 2025,
  "vehicleType": "Sedan",
  "state": "CA"
}'

Example response (illustrative)

{
  "api": "Denkiya Public Savings API V1",
  "route": "/api/public/v1/calculate",
  "version": 1,
  "amountSavedConvention": "positive_means_savings",
  "success": true,
  "method": "calculated",
  "data": {
    "primarySpend": { "avg": 2126.89 },
    "comparisonSpend": { "avg": 1129.99 },
    "amountSaved": { "avg": 996.9 },
    "savingsClass": "big-savings",
    "savingsSummary": "Big savings"
  }
}

Policies

Attribution

Community plans require a visible “Powered by Denkiya” credit in proximity to the numbers (same card or result block). On Standard and Pro, attribution is welcome but not required. Link the logo back to denkiya.co. See the API Terms of Service for the legal requirement.

Live preview

<p class="denkiya-attribution">
  Powered by
  <a href="https://denkiya.co/" aria-label="Denkiya">
    <img
      src="https://denkiya.co/denkiya-logo-flat.svg"
      alt="Denkiya"
      height="15"
      style="height: 0.95rem; max-width: 4.25rem; vertical-align: middle;"
    />
  </a>
</p>

Usage & errors

Quota headers, HTTP statuses, and what counts against your plan.

Successful metered responses include X-Denkiya-Plan, X-Denkiya-Usage-Limit, X-Denkiya-Usage-Remaining, and X-Denkiya-Usage-Reset.
Failed calls never count against your monthly calculation allowance.
The rates ticker never uses monthly quota (burst limits still apply).
Burst 429 is the key's plan RPM (Community and Standard 60/min, Pro 120/min) — there is no separate 30/min estimate cap. Monthly included allotment is not a 429. Community includes 250 calculations / UTC month; Standard and Pro continue with overage. See pricing.
Prefer calling from your server. Browser CORS is limited today — tell us your setup if you need client-side access.

Common status codes
Status	When
`401`	Missing or invalid key. Bodies still include `api` / `route` / `version`. The message explains that the key is unknown, inactive, or revoked.
`400`	Validation. Near-miss field names may include `didYouMean` and an `allowed` list. Bad enums and out-of-range usage numbers also return `allowed`. Extra keys that are not close to a real field are ignored.
`403`	Calculate uses the fields you send (type, fuels, usage, and so on). Sending `applianceId` or `vehicleId`, or a key missing `calculate:direct`, is forbidden.
`429`	Burst only: `rate_limit_exceeded` with `retryAfterSec` / `Retry-After`.

Questions? hello@denkiya.co

API Terms of Service

The legal terms that govern access to the Denkiya API — license grant, plan restrictions, payment, acceptable use, disclaimers, and liability.

By requesting an API key or calling the API, you agree to the Denkiya API Terms of Service. They sit alongside our general Terms of Service and Privacy Policy, and control when the subject is the API.