---
title: "Utility tariff schedules (NREL / OpenEI URDB)"
method: GET
path: "/api/v2/energy/tariffs"
tags: ["Energy"]
---

# Utility tariff schedules (NREL / OpenEI URDB)

`GET /api/v2/energy/tariffs`

Electricity utility tariff schedules from the NREL / OpenEI U.S. Utility Rate Database (URDB): energy and demand rate structures with their time-of-use period schedules, and fixed and minimum charges, by utility. Select a utility from the periodically ingested URDB snapshot by EIA utility id (eiaid) or by a case-insensitive name substring (utility - an ambiguous substring returns the candidate utilities to choose from); or pass lat and lon (with an optional radius in miles, default 5, max 200) for a location lookup served live from OpenEI. Filter by sector (residential, commercial, industrial, lighting). Community- and utility-submitted schedules, provided as-is under CC BY 4.0; verify against the utility tariff sheet before billing use.

## Query parameters

- `eiaid` integer, nullable — EIA utility id to load from the URDB snapshot.
- `utility` string, nullable — Case-insensitive utility-name substring (URDB snapshot).
- `lat` number, nullable — Latitude for a geo lookup (pair with lon).
- `lon` number, nullable — Longitude for a geo lookup (pair with lat).
- `radius` number — Geo search radius in miles (geo lookup only).
- `sector` 'residential' | 'commercial' | 'industrial' | 'lighting' | 'all'
- `approved` boolean — Restrict to NREL-approved schedules (catalog is approved-only; geo passes it through).
- `limit` integer — Maximum tariffs (or candidate utilities) returned.

## Response `200`

Successful Response

- EnvelopeTariffsFeed
  - `data` TariffsFeed, required
    - `query` TariffsQuery, required
      - `eiaid` integer, nullable — Catalog selector: EIA utility id.
      - `utility` string, nullable — Catalog selector: case-insensitive name substring.
      - `lat` number, nullable — Geo selector latitude (with lon).
      - `lon` number, nullable — Geo selector longitude (with lat).
      - `radius` number, nullable — Geo search radius in miles (geo mode only).
      - `sector` string, required — residential | commercial | industrial | lighting | all.
      - `approved` boolean, required
      - `limit` integer, required
    - `mode` string, required — catalog (blob snapshot) | geo (live OpenEI lookup).
    - `snapshot_date` string, nullable — Ingested URDB snapshot date in catalog mode; null in geo mode.
    - `utility` TariffUtility
      - `eiaid` integer, nullable
      - `name` string, nullable
    - `matches` TariffMatch[], nullable — Candidate utilities when a name substring is ambiguous; null otherwise.
      - `eiaid` integer, nullable
      - `name` string, nullable
      - `sectors` object, nullable — {sector: rate_count} for this utility in the snapshot.
    - `count` integer, required — Number of tariffs returned.
    - `tariffs` Tariff[], required
      - `label` string, nullable — URDB rate identifier.
      - `name` string, nullable
      - `utility` string, nullable
      - `eiaid` integer, nullable — EIA utility id; may be null on live records.
      - `sector` string, nullable — Residential | Commercial | Industrial | Lighting.
      - `description` string, nullable
      - `source` string, nullable — Source reference URL, if provided.
      - `uri` string, nullable
      - `approved` boolean — Whether NREL has approved this schedule.
      - `is_default` boolean — Whether this is the utility's default schedule for the sector.
      - `start_date` string, nullable — Effective date (ISO YYYY-MM-DD); null if unknown.
      - `end_date` string, nullable — Superseded date (ISO YYYY-MM-DD); null if still effective.
      - `fixed_charge` FixedCharge
        - `amount` number, nullable — Charge amount; null if the source omitted it.
        - `unit` string, nullable
      - `min_charge` FixedCharge
        - `amount` number, nullable — Charge amount; null if the source omitted it.
        - `unit` string, nullable
      - `energy` EnergyBlock
        - `tiers_by_period` array[] — Energy rate tiers grouped by time-of-use period (list of periods, each a tier list).
          - TariffTier[]
            - `rate` number — Base rate for this tier (currency per unit).
            - `adj` number, nullable — Per-tier fuel/rider adjustment added to rate; null if none.
            - `effective_rate` number — rate + (adj or 0); the price to bill against.
            - `max` number, nullable — Tier upper bound (kWh for energy, kW for demand); null = unbounded / last tier.
            - `unit` string, nullable
        - `weekday_schedule` array[], nullable — 12x24 matrix of period INDICES into tiers_by_period for weekdays (month x hour); null if flat.
          - integer[]
        - `weekend_schedule` array[], nullable — 12x24 matrix of period indices for weekends/holidays; null if flat.
          - integer[]
      - `demand` DemandBlock
        - `tiers_by_period` array[] — Time-of-use demand rate tiers grouped by period.
          - TariffTier[]
            - `rate` number — Base rate for this tier (currency per unit).
            - `adj` number, nullable — Per-tier fuel/rider adjustment added to rate; null if none.
            - `effective_rate` number — rate + (adj or 0); the price to bill against.
            - `max` number, nullable — Tier upper bound (kWh for energy, kW for demand); null = unbounded / last tier.
            - `unit` string, nullable
        - `weekday_schedule` array[], nullable — 12x24 period-index matrix for weekdays.
          - integer[]
        - `weekend_schedule` array[], nullable — 12x24 period-index matrix for weekends.
          - integer[]
        - `unit` string, nullable
        - `flat_tiers_by_period` array[] — Flat (month-based) demand rate tiers grouped by period.
          - TariffTier[]
            - `rate` number — Base rate for this tier (currency per unit).
            - `adj` number, nullable — Per-tier fuel/rider adjustment added to rate; null if none.
            - `effective_rate` number — rate + (adj or 0); the price to bill against.
            - `max` number, nullable — Tier upper bound (kWh for energy, kW for demand); null = unbounded / last tier.
            - `unit` string, nullable
        - `flat_months` integer[], nullable — 12-length month->period index for the flat demand structure; null if none.
    - `attribution` GridAttributionSet, required
      - `sources` GridSourceAttribution[] — Every sovereign source that contributed to this response.
        - `registry_key` string, required
        - `source_name` string, required
        - `licence` string, required
        - `citation` string, required
        - `disclaimer` string, required
      - `effective_reexport` string, required — Most-restrictive re-export verdict across the sources.
    - `disclaimer` string, required
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4c4530760ba1/schema)