Developer API · Tariffs

Verified tariff intelligence without a bulk-data leak

Query one jurisdiction, utility, category and schedule at a time. Every response is authenticated, metered, bounded and sourced to the effective regulator order.

No public dataset download

The national tariff corpus is not published as CSV, PDF or raw JSON. The public /tariffs page is for human review; integrations must use this API. A determined user can always record values that are visibly rendered, but there is no official unmetered bulk-export surface.

Access and protection

Send your key in X-API-Key. Tariff endpoints inherit the Developer API's hashed-key authentication, per-minute and per-day quotas, rolling export controls, request audit log, plan headers, and response watermark. Raw keys are shown once and are never stored.

Control	Behaviour
Entitlement	Institutional, Starter, Growth and Enterprise keys
Scope	One state per request; one utility/category/schedule for rate data
Rate limits	Plan-specific; returned in X-RateLimit-* headers
Audit	Key id, endpoint, status, latency, row count and request metadata
Caching	Never expose API keys in browser code; call from your server

Keep the API key server-side

Do not put a tariff key in NEXT_PUBLIC_*, a client component, mobile bundle or source-controlled configuration. Proxy requests through your own backend and rotate a key immediately if it appears in browser developer tools.

Schedule catalogue

GET/developer/v1/tariff/cataloguestarter+

Discover utilities and exact regulator schedule codes inside one state. Omitting utility returns metadata only; it never returns a national rate dump.

statestringRequired
State name or canonical slug.
utilitystring
DISCOM acronym, name or slug. Omit to list the state's utilities.
rate_classstring
Optional residential, commercial, industrial, solar or agricultural filter.

bash

curl --get 'https://api.energymap.in/developer/v1/tariff/catalogue' --header 'X-API-Key: iea_live_…' --data-urlencode 'state=maharashtra' --data-urlencode 'utility=msedcl'

Current rate and ToD resolver

GET/developer/v1/tariff/currentstarter+

Resolve the verified marginal energy rate and the ToD/ToU band at an IST instant. Ambiguous utilities and schedules fail closed with their valid choices.

statestringRequired
State name or slug.
utilitystring
Required when the state has multiple DISCOMs.
rate_classstringdefault: residential
Category or common alias such as home, shop or factory.
schedule_codestring
Required whenever more than one current schedule exists.
atISO-8601
Instant to resolve; timezone-less input is interpreted as IST.
monthly_kwhnumber
Pins the marginal residential slab; this does not calculate a total bill.
contract_demand_kwnumber
Exact kW eligibility gate for ToD rules.
contract_demand_kvanumber
Exact kVA eligibility gate for ToD rules.
meter_typesmart | tod | other
Used when the order requires a capable meter.

bash

curl --get 'https://api.energymap.in/developer/v1/tariff/current' \
  --header 'X-API-Key: iea_live_…' \
  --data-urlencode 'state=andhra-pradesh' \
  --data-urlencode 'utility=apcpdcl' \
  --data-urlencode 'rate_class=industrial' \
  --data-urlencode 'schedule_code=HT-I-A' \
  --data-urlencode 'contract_demand_kva=500' \
  --data-urlencode 'meter_type=tod'

Fail-closed bill estimate

POST/developer/v1/tariff/estimatestarter+

Calculate a base residential estimate only when the reviewed source explicitly marks the schedule bill-ready and every required unit and slab bound is exact.

bash

curl 'https://api.energymap.in/developer/v1/tariff/estimate' \
  --request POST \
  --header 'X-API-Key: iea_live_…' \
  --header 'Content-Type: application/json' \
  --data '{
    "state": "andhra-pradesh",
    "utility": "apcpdcl",
    "rate_class": "residential",
    "schedule_code": "LT-I-A",
    "monthly_kwh": 250,
    "connected_load_kw": 3
  }'

Includes progressive energy slabs, supported fixed-charge bases, an exact per-kWh FPPCA, and an exact connection-level monthly minimum where present.
Does not silently apply duty, subsidy, arrears, meter rent, late fees or a ToD adjustment without the required billing inputs and approved formula.
Returns estimate_not_supported instead of a plausible but incomplete number.
The result is a tariff estimate, not a utility invoice or billing determination.

Provenance contract

Rate responses preserve the dimensions needed to audit a number:

effective date and regulator tariff-order id
official source URL, reviewed source-document id and source page
verification status and verification timestamp
kWh versus kVAh, fixed/demand-charge denominator and exact schedule code
ToD season, window, signed adder or multiplier, load gates, meter requirement and conditional-consumption scope

Rates are not state averages

A tariff belongs to a utility, consumer category and regulator schedule. Never label one schedule as “the electricity price” for an entire state. Preserve the response's query echo and source object in downstream records.

Errors and safe retries

Status	Code	Meaning
401	invalid_api_key	Key missing, revoked or invalid
403	upgrade_required	Key is valid but lacks Tariff API entitlement
404	state_not_found / utility_not_found	Requested jurisdiction is not resolved
422	utility_required / schedule_required	Request is ambiguous; use the returned choices
422	estimate_not_supported	The schedule cannot be calculated without inventing a billing rule
429	quota_exceeded	Per-minute, daily or rolling export allowance reached

Create API key Open interactive reference

Developer API · Tariffs

Verified tariff intelligence without a bulk-data leak

Query one jurisdiction, utility, category and schedule at a time. Every response is authenticated, metered, bounded and sourced to the effective regulator order.

No public dataset download

Access and protection

Control	Behaviour
Entitlement	Institutional, Starter, Growth and Enterprise keys
Scope	One state per request; one utility/category/schedule for rate data
Rate limits	Plan-specific; returned in X-RateLimit-* headers
Audit	Key id, endpoint, status, latency, row count and request metadata
Caching	Never expose API keys in browser code; call from your server

Keep the API key server-side

Schedule catalogue

GET/developer/v1/tariff/cataloguestarter+

Discover utilities and exact regulator schedule codes inside one state. Omitting utility returns metadata only; it never returns a national rate dump.

statestringRequired
State name or canonical slug.
utilitystring
DISCOM acronym, name or slug. Omit to list the state's utilities.
rate_classstring
Optional residential, commercial, industrial, solar or agricultural filter.

bash

curl --get 'https://api.energymap.in/developer/v1/tariff/catalogue' --header 'X-API-Key: iea_live_…' --data-urlencode 'state=maharashtra' --data-urlencode 'utility=msedcl'

Current rate and ToD resolver

GET/developer/v1/tariff/currentstarter+

Resolve the verified marginal energy rate and the ToD/ToU band at an IST instant. Ambiguous utilities and schedules fail closed with their valid choices.

statestringRequired
State name or slug.
utilitystring
Required when the state has multiple DISCOMs.
rate_classstringdefault: residential
Category or common alias such as home, shop or factory.
schedule_codestring
Required whenever more than one current schedule exists.
atISO-8601
Instant to resolve; timezone-less input is interpreted as IST.
monthly_kwhnumber
Pins the marginal residential slab; this does not calculate a total bill.
contract_demand_kwnumber
Exact kW eligibility gate for ToD rules.
contract_demand_kvanumber
Exact kVA eligibility gate for ToD rules.
meter_typesmart | tod | other
Used when the order requires a capable meter.

bash

curl --get 'https://api.energymap.in/developer/v1/tariff/current' \
  --header 'X-API-Key: iea_live_…' \
  --data-urlencode 'state=andhra-pradesh' \
  --data-urlencode 'utility=apcpdcl' \
  --data-urlencode 'rate_class=industrial' \
  --data-urlencode 'schedule_code=HT-I-A' \
  --data-urlencode 'contract_demand_kva=500' \
  --data-urlencode 'meter_type=tod'

Fail-closed bill estimate

POST/developer/v1/tariff/estimatestarter+

Calculate a base residential estimate only when the reviewed source explicitly marks the schedule bill-ready and every required unit and slab bound is exact.

bash

curl 'https://api.energymap.in/developer/v1/tariff/estimate' \
  --request POST \
  --header 'X-API-Key: iea_live_…' \
  --header 'Content-Type: application/json' \
  --data '{
    "state": "andhra-pradesh",
    "utility": "apcpdcl",
    "rate_class": "residential",
    "schedule_code": "LT-I-A",
    "monthly_kwh": 250,
    "connected_load_kw": 3
  }'

Includes progressive energy slabs, supported fixed-charge bases, an exact per-kWh FPPCA, and an exact connection-level monthly minimum where present.
Does not silently apply duty, subsidy, arrears, meter rent, late fees or a ToD adjustment without the required billing inputs and approved formula.
Returns estimate_not_supported instead of a plausible but incomplete number.
The result is a tariff estimate, not a utility invoice or billing determination.

Provenance contract

Rate responses preserve the dimensions needed to audit a number:

effective date and regulator tariff-order id
official source URL, reviewed source-document id and source page
verification status and verification timestamp
kWh versus kVAh, fixed/demand-charge denominator and exact schedule code
ToD season, window, signed adder or multiplier, load gates, meter requirement and conditional-consumption scope

Rates are not state averages

Errors and safe retries

Status	Code	Meaning
401	invalid_api_key	Key missing, revoked or invalid
403	upgrade_required	Key is valid but lacks Tariff API entitlement
404	state_not_found / utility_not_found	Requested jurisdiction is not resolved
422	utility_required / schedule_required	Request is ambiguous; use the returned choices
422	estimate_not_supported	The schedule cannot be calculated without inventing a billing rule
429	quota_exceeded	Per-minute, daily or rolling export allowance reached

Create API key Open interactive reference