Understanding URDB JSON Structure

⚠️ Disclaimer: This guide was generated by an LLM (Claude Opus 4.5) based on URDB API documentation and the model's understanding of rate structures. The content looks reasonable but has not been verified by domain experts. Please verify any claims before relying on them for production use.

This guide walks through the NREL Utility Rate Database (URDB) JSON format using progressively more complex rate structures. By the end, you'll understand how fixed charges, energy charges, and demand charges are represented—and how they combine.

For the complete API reference, see the OpenEI URDB API Documentation.

Core Structure

Every URDB rate has these common metadata fields:

{
  "label": "5374efea9bef51471a6965d0",
  "utility": "Example Electric Co",
  "name": "Residential Standard",
  "sector": "Residential",
  "description": "Standard residential service",
  "source": "https://example.com/tariff.pdf",
  "startdate": 1704067200,
  "enddate": null
}

Field	Description
`label`	Unique identifier for this rate
`utility`	Utility company name
`name`	Rate schedule name
`sector`	Customer class: Residential, Commercial, Industrial, Lighting
`startdate` / `enddate`	Unix timestamps for when the rate is effective

Beyond metadata, a rate can include:

Fixed charges — Flat monthly fees regardless of usage
Energy charges — Per-kWh charges based on consumption
Demand charges — Per-kW charges based on peak power draw (common for commercial/industrial)
Adjustments — Fuel cost pass-throughs, distributed generation rules, and other modifiers

We will walk through each in turn, building intuition via examples.

Rate Tier Properties

This will make more sense when we get to the examples, but throughout this guide, you'll see tier objects inside rate structures. The available properties depend on the structure type:

Property	`energyratestructure`	`flatdemandstructure`	`demandratestructure`
`rate`	✓	✓	✓
`max`	✓	✓	✓
`unit`	✓	—	—
`adj`	✓	✓	✓
`sell`	✓	—	✓

rate — The rate amount ($/kWh or $/kW)
max — Cumulative upper limit for this tier
unit — Unit of measurement (energy tiers only; demand uses flatdemandunit or demandrateunit)
adj — Adjustment factor (multiplier applied to rate)
sell — Sell-back rate for net metering

Example energy tier:

{
  "max": 500,
  "rate": 0.08,
  "unit": "kWh",
  "sell": 0.04
}

This means: up to 500 kWh at $0.08/kWh, with a sell-back rate of $0.04/kWh for exported solar.

Fixed Charges

Fixed charges are flat monthly fees that don't depend on how much electricity you use. Typically, they cover the utility's cost of maintaining your connection to the grid.

Example: Fixed Charge Only

The simplest possible rate—just a monthly customer charge with no usage-based fees.

{
  "label": "fixed_only_example",
  "utility": "Simple Electric Co",
  "name": "Basic Service",
  "sector": "Residential",

  "fixedchargefirstmeter": 15.00,
  "fixedchargeunits": "$/month",

  "mincharge": 15.00,
  "minchargeunits": "$/month"
}

Field	Description
`fixedchargefirstmeter`	Monthly fixed charge (customer charge)
`fixedchargeunits`	Unit for the fixed charge
`mincharge`	Minimum bill amount (floor)
`minchargeunits`	Unit for minimum charge

Bill Calculation

Fixed charge: $15.00
──────────────────────
Total:        $15.00

The mincharge field sets a floor on the total bill. If energy + demand charges would result in less than $15, the customer still pays $15.

Energy Charges

Energy charges are based on how many kilowatt-hours (kWh) you consume.

Note: "Energy charge" here means "volumetric charge"—it can represent supply charges (generation/procurement), delivery charges (transmission/distribution), or both bundled together. URDB doesn't distinguish between them; they're all in energyratestructure.

Energy charges can be flat, tiered, seasonal, time-of-use, or any combination.

Example 1: Flat Rate

The Concept

A flat rate is the simplest electricity pricing: every kWh costs the same amount, regardless of how much you use or when you use it. This is still quite common across utilities.

URDB JSON

{
  "label": "flat_example",
  "utility": "Simple Electric Co",
  "name": "Residential Flat",
  "sector": "Residential",

  "fixedchargefirstmeter": 12.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [
      {
        "rate": 0.10,
        "unit": "kWh"
      }
    ]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

Key Concepts Introduced

energyratestructure — The core rate data. It's an array of periods, where each period is an array of tiers (see Rate Tier Properties for the full list of tier fields):

energyratestructure[period_index][tier_index] = { rate, unit, max, adj, sell }

For a flat rate, there's just one period (index 0) with one tier:

rate: 0.10 ($/kWh)
unit: "kWh"

energyweekdayschedule and energyweekendschedule — These 12×24 arrays map every hour of every month to a period index. Each row is a month (0=January, 11=December), each column is an hour (0=midnight, 23=11pm).

For a flat rate, every cell is 0, meaning "use period 0" — the single flat rate.

Bill Calculation

Monthly bill = $12.00 (fixed) + (500 kWh × $0.10/kWh) = $62.00

Example 2: Tiered Rate

The Concept

A tiered rate charges different prices based on how much you use. Tiers can be inclining (prices increase with usage) or declining (prices decrease with usage). Inclining block rates are more common for residential customers—they encourage conservation by making the first kWh cheapest and charging more as usage grows.

This example shows an inclining tiered rate:

First 500 kWh: $0.08/kWh
Next 500 kWh (501-1000): $0.12/kWh
Over 1000 kWh: $0.15/kWh

URDB JSON

{
  "label": "tiered_example",
  "utility": "Conservation Electric",
  "name": "Residential Tiered",
  "sector": "Residential",

  "fixedchargefirstmeter": 15.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [
      {
        "max": 500,
        "rate": 0.08,
        "unit": "kWh"
      },
      {
        "max": 1000,
        "rate": 0.12,
        "unit": "kWh"
      },
      {
        "rate": 0.15,
        "unit": "kWh"
      }
    ]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

What Changed

Recall that energyratestructure is an array of periods, where each period is an array of tiers. We still have just one period (index 0), but now it contains three tiers:

Tier	`max`	`rate`	Meaning
0	500	0.08	First 500 kWh at $0.08
1	1000	0.12	Next 500 kWh (501-1000) at $0.12
2	(none)	0.15	Everything above 1000 kWh at $0.15

The max field indicates the cumulative upper limit for that tier (see Rate Tier Properties). The final tier has no max — it applies to all remaining usage.

Bill Calculation

For 800 kWh usage:

Tier 1: 500 kWh × $0.08 = $40.00
Tier 2: 300 kWh × $0.12 = $36.00
Fixed:                    $15.00
─────────────────────────────────
Total:                    $91.00

Example 3: Seasonal Rate

The Concept

A seasonal rate has different prices for different times of year. Summer rates are typically higher because peak demand (air conditioning) strains the grid. Winter rates are lower.

This example has two seasons with flat (non-tiered) rates:

Summer (June-September): $0.12/kWh
Winter (October-May): $0.08/kWh

URDB JSON

{
  "label": "seasonal_example",
  "utility": "Seasonal Electric Co",
  "name": "Residential Seasonal",
  "sector": "Residential",

  "fixedchargefirstmeter": 15.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [
      {
        "rate": 0.08,
        "unit": "kWh"
      }
    ],
    [
      {
        "rate": 0.12,
        "unit": "kWh"
      }
    ]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

What Changed

Recall that energyratestructure is an array of periods, where each period is an array of tiers. We now have two periods, each with just one tier (no tiering):

Period	Season	Rate
0	Winter	$0.08/kWh
1	Summer	$0.12/kWh

The schedules now vary by month:

Month index:  0   1   2   3   4   5   6   7   8   9  10  11
Month:       Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
Period:       0   0   0   0   0   1   1   1   1   0   0   0
                                  ↑───────────↑
                                  Summer (Jun-Sep)

Rows 5-8 (June-September) contain all 1s, pointing to period 1 (Summer rate). The rest contain 0s for period 0 (Winter rate).

Bill Calculation

For 700 kWh in July (summer):

Energy:  700 kWh × $0.12 = $84.00
Fixed:                     $15.00
──────────────────────────────────
Total:                     $99.00

For 700 kWh in January (winter):

Energy:  700 kWh × $0.08 = $56.00
Fixed:                     $15.00
──────────────────────────────────
Total:                     $71.00

Example 4: Time-of-Use Rate

The Concept

A time-of-use (TOU) rate charges different prices depending on the time of day. Peak hours (when demand is highest) cost more than off-peak hours. This incentivizes shifting usage to times when the grid is less stressed.

This example has two periods year-round (no seasonal variation, no tiers):

Peak: 2pm-6pm weekdays — $0.20/kWh
Off-Peak: All other times — $0.08/kWh

URDB JSON

{
  "label": "tou_example",
  "utility": "TOU Electric Co",
  "name": "Residential TOU",
  "sector": "Residential",

  "fixedchargefirstmeter": 15.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [
      {
        "rate": 0.08,
        "unit": "kWh"
      }
    ],
    [
      {
        "rate": 0.20,
        "unit": "kWh"
      }
    ]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

What Changed

Recall that energyratestructure is an array of periods, where each period is an array of tiers. We have two periods, each with one tier:

Period	TOU	Rate
0	Off-Peak	$0.08/kWh
1	Peak	$0.20/kWh

The schedules now vary by hour (not month). Every row is identical because there's no seasonal variation:

Weekday (any month):
Hour:    0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Period:  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  1  1  1  1  0  0  0  0  0
                                                   ↑───────────↑
                                                   2pm-7pm peak (hours 14-18)

energyweekendschedule is all 0s — weekends are always off-peak.

Bill Calculation

For 700 kWh, with 200 kWh during peak and 500 kWh off-peak:

Off-Peak: 500 kWh × $0.08 = $40.00
Peak:     200 kWh × $0.20 = $40.00
Fixed:                      $15.00
──────────────────────────────────
Total:                      $95.00

Example 5: Seasonal Tiered Time-of-Use Rate

The Concept

This final example combines all three dimensions we've covered:

Seasons: Summer vs. Winter (different base rates)
Time-of-Use: Peak vs. Off-Peak (different prices by hour)
Tiers: First 500 kWh vs. over 500 kWh (different prices by consumption)

Season	TOU Period	Hours	Tier 1 (≤500)	Tier 2 (>500)
Summer	Peak	2pm-7pm weekdays	$0.25	$0.35
Summer	Off-Peak	All other times	$0.10	$0.15
Winter	Peak	6am-9am, 5pm-8pm weekdays	$0.15	$0.20
Winter	Off-Peak	All other times	$0.08	$0.10

URDB JSON

{
  "label": "seasonal_tiered_tou_example",
  "utility": "Modern Electric Co",
  "name": "Residential Seasonal TOU",
  "sector": "Residential",

  "fixedchargefirstmeter": 20.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [
      { "max": 500, "rate": 0.08, "unit": "kWh" },
      { "rate": 0.10, "unit": "kWh" }
    ],
    [
      { "max": 500, "rate": 0.15, "unit": "kWh" },
      { "rate": 0.20, "unit": "kWh" }
    ],
    [
      { "max": 500, "rate": 0.10, "unit": "kWh" },
      { "rate": 0.15, "unit": "kWh" }
    ],
    [
      { "max": 500, "rate": 0.25, "unit": "kWh" },
      { "rate": 0.35, "unit": "kWh" }
    ]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,2,2,2,2,2],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0],
    [0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
    [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

What Changed

This combines everything from the previous examples. Recall that energyratestructure is an array of periods, where each period is an array of tiers. We now have four periods (2 seasons × 2 TOU periods), each with two tiers:

Period	Season	TOU	Tier 1 (≤500)	Tier 2 (>500)
0	Winter	Off-Peak	$0.08	$0.10
1	Winter	Peak	$0.15	$0.20
2	Summer	Off-Peak	$0.10	$0.15
3	Summer	Peak	$0.25	$0.35

energyweekdayschedule varies by both month AND hour:

Winter weekday (January, row 0):
Hour:    0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Period:  0  0  0  0  0  0  1  1  1  0  0  0  0  0  0  0  0  1  1  1  0  0  0  0
                           ↑─────↑                          ↑─────↑
                           6-9am peak                       5-8pm peak

Summer weekday (July, row 6):
Hour:    0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Period:  2  2  2  2  2  2  2  2  2  2  2  2  2  2  3  3  3  3  3  2  2  2  2  2
                                                   ↑───────────↑
                                                   2-7pm peak (hours 14-18)

energyweekendschedule — weekends are always off-peak:

Winter weekends: all 0 (Winter Off-Peak)
Summer weekends: all 2 (Summer Off-Peak)

Reading the Schedule

To find the rate for a specific hour:

Is it a weekday or weekend? → choose weekday or weekend schedule
Determine the month → row index (0-11)
Determine the hour → column index (0-23)
Look up the value → this is the period index
Go to energyratestructure[period] → get the tiers
Apply usage to tiers → calculate cost

Example: Wednesday, July 15th at 3pm, first 100 kWh of the month:

Wednesday = weekday schedule
July = row 6
3pm = column 15
energyweekdayschedule[6][15] = 3
energyratestructure[3] = Summer Peak tiers
100 kWh × $0.25 = $25.00 (within tier 1)

Demand Charges

Demand charges are based on your peak power draw (kW), not total consumption (kWh). They're common for commercial and industrial customers because a customer who briefly draws 100 kW requires more grid infrastructure than one who steadily draws 10 kW—even if both use the same total kWh.

Demand charges use structures parallel to energy charges:

Energy Field	Demand Equivalent	Description
`energyratestructure`	`flatdemandstructure`	Seasonal/monthly demand tiers
`energyratestructure`	`demandratestructure`	TOU demand periods/tiers
`energyweekdayschedule`	`demandweekdayschedule`	Maps hours to TOU demand periods
`energyweekendschedule`	`demandweekendschedule`	Weekend TOU demand schedule
—	`flatdemandmonths`	Maps months to flatdemandstructure periods

Example: Flat Demand Charge

This example shows a rate with only a fixed charge plus a flat demand charge (no energy charges, no time-of-use variation). This isolates the demand charge structure.

{
  "label": "flat_demand_example",
  "utility": "Commercial Electric Co",
  "name": "Demand Only",
  "sector": "Commercial",

  "fixedchargefirstmeter": 25.00,
  "fixedchargeunits": "$/month",

  "flatdemandunit": "kW",
  "flatdemandstructure": [
    [
      { "rate": 8.50 }
    ]
  ],

  "flatdemandmonths": [0,0,0,0,0,0,0,0,0,0,0,0]
}

Key Fields

flatdemandunit — Units for the demand charge: "kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily".

flatdemandstructure — Array of periods containing arrays of tiers. Note: tiers here don't have unit or sell—units come from flatdemandunit.

flatdemandmonths — Array of 12 integers mapping each month to a period in flatdemandstructure. All 0s means period 0 applies year-round.

Bill Calculation

For 50 kW peak demand:

Fixed:   $25.00
Demand:  50 kW × $8.50 = $425.00
───────────────────────────────
Total:                   $450.00

Example: Time-of-Use Demand Charge

This example shows demand charges that vary by time of day. Peak demand during expensive hours costs more than peak demand during off-peak hours. No energy charges—just fixed + TOU demand.

{
  "label": "tou_demand_example",
  "utility": "Commercial Electric Co",
  "name": "TOU Demand Only",
  "sector": "Commercial",

  "fixedchargefirstmeter": 50.00,
  "fixedchargeunits": "$/month",

  "demandrateunit": "kW",
  "demandratestructure": [
    [{ "rate": 5.00 }],
    [{ "rate": 15.00 }]
  ],

  "demandweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0]
  ],

  "demandweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ]
}

Key Fields

demandrateunit — Units for TOU demand: "kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily".

demandratestructure — TOU demand periods (tiers don't have unit—it comes from demandrateunit):

Period	TOU	Rate
0	Off-Peak	$5.00/kW
1	Peak	$15.00/kW

demandweekdayschedule and demandweekendschedule — Same 12×24 format as energy schedules. Peak demand is measured during hours 14-18 (2pm-6pm) on weekdays.

Bill Calculation

For 60 kW peak demand during peak hours, 40 kW during off-peak:

Fixed:            $50.00
Demand (off-peak): 40 kW × $5.00  = $200.00
Demand (peak):     60 kW × $15.00 = $900.00
─────────────────────────────────────────────
Total:                             $1,150.00

Combining Tiers, Seasons, and TOU with Demand

Just like energy charges, demand charges can be combined with:

Tiers — Different $/kW rates based on peak demand level (e.g., first 50 kW at one rate, additional kW at higher rate)
Seasons — Different demand rates for summer vs. winter
Time-of-use — Different demand rates by time of day (as shown above)

The structure mirrors what we saw in the energy charge examples:

demandratestructure[period][tier] works like energyratestructure[period][tier]
Use max to define tier thresholds (cumulative kW limits)
Use schedules to map months and hours to periods

Combining Fixed + Energy + Demand

Rates can combine all three charge types, and the URDB format supports this naturally—you simply include the relevant fields for each:

Charge Type	Required Fields
Fixed	`fixedchargefirstmeter`, `fixedchargeunits`
Energy	`energyratestructure`, `energyweekdayschedule`, `energyweekendschedule`
Demand (flat/seasonal)	`flatdemandstructure`, `flatdemandmonths`
Demand (TOU)	`demandratestructure`, `demandweekdayschedule`, `demandweekendschedule`

Example: Fixed + Energy + Flat Demand

{
  "label": "combined_example",
  "utility": "Commercial Electric Co",
  "name": "Small Commercial Standard",
  "sector": "Commercial",

  "fixedchargefirstmeter": 25.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [{ "rate": 0.08, "unit": "kWh" }]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "flatdemandunit": "kW",
  "flatdemandstructure": [
    [{ "rate": 8.50 }]
  ],

  "flatdemandmonths": [0,0,0,0,0,0,0,0,0,0,0,0]
}

Bill Calculation

For 5,000 kWh consumption with 50 kW peak demand:

Fixed:   $25.00
Energy:  5,000 kWh × $0.08 = $400.00
Demand:  50 kW × $8.50     = $425.00
─────────────────────────────────────
Total:                       $850.00

Each charge type uses its own independent set of fields. The bill calculation simply sums them all together.

Adjustments and Riders

Beyond the core fixed, energy, and demand charges, utility rates often include various adjustments that modify the base charges.

Field	Type	Description
`fueladjustmentsmonthly`	Array of 12 floats	Monthly $/kWh fuel adjustments
`dgrules`	String	Distributed generation compensation policy
`energyattrs`	Array of objects	Additional energy charge metadata
`demandattrs`	Array of objects	Additional demand charge metadata

Fuel Adjustments

Fuel costs fluctuate with market prices. Rather than constantly revising base rates, utilities apply monthly fuel adjustment charges (or credits) that pass through actual fuel costs.

{
  "label": "fuel_adj_example",
  "utility": "Example Electric Co",
  "name": "Residential with Fuel Adjustment",
  "sector": "Residential",

  "fixedchargefirstmeter": 12.00,
  "fixedchargeunits": "$/month",

  "energyratestructure": [
    [{ "rate": 0.10, "unit": "kWh" }]
  ],

  "energyweekdayschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "energyweekendschedule": [
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  ],

  "fueladjustmentsmonthly": [0.015, 0.012, 0.010, 0.008, 0.005, 0.018, 0.025, 0.028, 0.022, 0.012, 0.010, 0.014]
}

Key Field

fueladjustmentsmonthly — Array of 12 values (one per month, January through December) representing $/kWh adjustments added to the base energy rate.

In this example:

January: base rate ($0.10) + fuel adjustment ($0.015) = $0.115/kWh
August: base rate ($0.10) + fuel adjustment ($0.028) = $0.128/kWh (peak summer fuel costs)

Bill Calculation

For 600 kWh in August:

Fixed:           $12.00
Energy:          600 kWh × $0.10   = $60.00
Fuel adjustment: 600 kWh × $0.028  = $16.80
──────────────────────────────────────────
Total:                               $88.80

Distributed Generation Rules

For customers with solar panels or other generation, the dgrules field specifies how exported energy is compensated.

`dgrules` Value	Meaning
`Net Metering`	Exports offset imports 1:1 at retail rate
`Net Billing Instantaneous`	Exports credited at sell rate, calculated instantaneously
`Net Billing Hourly`	Exports credited at sell rate, calculated hourly
`Buy All Sell All`	All generation sold to utility, all consumption purchased

When using net billing, the sell property in tier objects specifies the export rate:

{
  "energyratestructure": [
    [
      {
        "rate": 0.12,
        "unit": "kWh",
        "sell": 0.04
      }
    ]
  ],
  "dgrules": "Net Billing"
}

Bill Calculation Examples

Consider a solar customer who imports 400 kWh from the grid and exports 200 kWh back. Fixed charge is $12/month, retail rate is $0.12/kWh.

Net Metering (dgrules: "Net Metering"):

Exports offset imports 1:1 at the retail rate. You only pay for net consumption.

Net consumption: 400 kWh imported - 200 kWh exported = 200 kWh
Fixed:   $12.00
Energy:  200 kWh × $0.12 = $24.00
─────────────────────────────────
Total:                     $36.00

Net Billing (dgrules: "Net Billing Instantaneous" or "Net Billing Hourly", sell: 0.04):

Imports and exports are tracked separately. Exports earn a credit at the sell rate.

Fixed:          $12.00
Imports:        400 kWh × $0.12 = $48.00
Export credit:  200 kWh × $0.04 = -$8.00
────────────────────────────────────────
Total:                           $52.00

Buy All Sell All (dgrules: "Buy All Sell All"):

All generation is sold to the utility at the sell rate; all consumption is purchased at the retail rate.

Fixed:          $12.00
Imports:        600 kWh × $0.12 = $72.00  (all consumption)
Export credit:  200 kWh × $0.04 = -$8.00  (all generation)
────────────────────────────────────────────────────────────
Total:                           $76.00

Energy and Demand Attributes

The energyattrs and demandattrs fields provide additional metadata about charges:

{
  "energyattrs": [
    { "label": "Renewable Energy Charge", "value": 0.002 },
    { "label": "Public Benefits Charge", "value": 0.003 }
  ],
  "demandattrs": [
    { "label": "Facilities Charge", "value": 2.50 }
  ]
}

These are typically informational—they may represent line items that are already baked into the main rate structures, or they may be separate adders. Check the utility's actual tariff document to understand how they apply.

Comparison with Arcadia

Aspect	URDB	Arcadia
Schedule granularity	12×24 arrays (month × hour)	Separate season/TOU objects
Period indexing	Zero-based integers in schedules	Named periods with date ranges
Tier structure	`max` is cumulative	`consumptionUpperLimit` is cumulative
Variable rates	Not supported	`variableRateKey` for lookups
Riders	Not separated	Explicit `riderId`/`riderTariffId`

Understanding URDB JSON Structure

Core Structure

Rate Tier Properties

Fixed Charges

Example: Fixed Charge Only

Bill Calculation

Energy Charges

Example 1: Flat Rate

The Concept

URDB JSON

Key Concepts Introduced

Bill Calculation

Example 2: Tiered Rate

The Concept

URDB JSON

What Changed

Bill Calculation

Example 3: Seasonal Rate

The Concept

URDB JSON

What Changed

Bill Calculation

Example 4: Time-of-Use Rate

The Concept

URDB JSON

What Changed

Bill Calculation

Example 5: Seasonal Tiered Time-of-Use Rate

The Concept

URDB JSON

What Changed

Reading the Schedule

Demand Charges

Example: Flat Demand Charge

Key Fields

Bill Calculation

Example: Time-of-Use Demand Charge

Key Fields

Bill Calculation

Combining Tiers, Seasons, and TOU with Demand

Combining Fixed + Energy + Demand

Example: Fixed + Energy + Flat Demand

Bill Calculation

Adjustments and Riders

Fuel Adjustments

Key Field

Bill Calculation

Distributed Generation Rules

Bill Calculation Examples

Energy and Demand Attributes

Comparison with Arcadia

Further Reading