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
Each endpoint below has a short intro, a live request builder, and copy-paste code. Change a field and the snippets update instantly. 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 estimate builder.
API reference
/api/public/estimateEstimate
The quick “what would I save?” endpoint. Pick a category — cooktop, dryer, HVAC, water heater, and more — tell us what you have now and what you’re comparing to, add a ZIP code, and you’re most of the way there. Estimate fills in sensible defaults so you can embed a savings number in a widget or landing page without modeling every detail. Use calculate below when you need full control over specs and usage.
Existing vehicle
New vehicle
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",
"state": "CA",
"year": 2025,
"fuelType": "Gasoline",
"vehicleType": "Sedan",
"annualMileage": 13500
}'{
"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": { "low": 2020.55, "high": 2233.23, "avg": 2126.89 }
},
"comparison": {
"label": "Electric",
"annualCostUsd": { "low": 1073.49, "high": 1186.49, "avg": 1129.99 }
},
"amountSavedConvention": "positive_means_savings",
"amountSaved": {
"low": 834.06,
"high": 1159.74,
"avg": 996.9
},
"low": 834.06,
"high": 1159.74,
"avg": 996.9,
"savingsClass": "big-savings",
"savingsSummary": "Big savings"
}/api/public/v1/calculateFull calculate
The detailed workbook version of the same engine. Use calculate when you're building a custom configurator or need to match a specific home — exact equipment, thermostat behavior, usage, optional monthly breakdown, and more. Estimate above is the fast comparison; calculate is where you dial everything in. The request snippets update as you change the fields below.
Existing vehicle
New vehicle
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",
"year": 2025,
"usage": {
"annualMileage": 13500,
"chargingHabits": 0,
"electricMiles": 0,
"vehicleType": "Sedan"
},
"vehicleType": "Sedan",
"state": "CA"
}'{
"api": "Denkiya Public Savings API V1",
"route": "/api/public/v1/calculate",
"version": 1,
"amountSavedConvention": "positive_means_savings",
"success": true,
"method": "calculated",
"data": {
"primarySpend": { "low": 2020.55, "high": 2233.23, "avg": 2126.89 },
"comparisonSpend": { "low": 1073.49, "high": 1186.49, "avg": 1129.99 },
"amountSaved": { "low": 834.06, "high": 1159.74, "avg": 996.9 },
"savingsClass": "big-savings",
"savingsSummary": "Big savings"
}
}/api/public/rates/tickerRates ticker
Current energy prices — gasoline, electricity, propane, and natural gas — by state or region. Use this when you need rate data for labels, dropdowns, or your own math. It does not run a savings comparison and does not count against your monthly calculation quota.
Unmetered for monthly quota — fair-use per-minute limits still apply.
curl 'https://www.denkiya.app/api/public/rates/ticker?state=CA&period=last-12-months' \
-H "Accept: application/json" \
-H "x-api-key: YOUR_API_KEY"{
"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"
}
]
}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
Powered by
<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, andX-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.
| 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.