Documentation Index
Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
Use this file to discover all available pages before exploring further.
This page documents the semantic rate ID schema used in WattShift’s normalized rate data.
If you are onboarding a home through the public API, the usual flow is still simple: choose a plan from /v1/utility/get and pass that returned ratePlans[].id as ratePlanId. This page is the deeper reference for understanding the semantic structure behind a normalized rate ID.
In /v1/utility/get:
- Use
ratePlans[].id as ratePlanId in other API requests.
- Use
ratePlans[].rateID when you want the semantic normalized tariff identifier described on this page.
Rate ID Schema by Sector
Residential plans use this 13-segment format:
COUNTRY-STATE-DIST_UTILITY-ENERGY_PROVIDER-SECTOR-STRUCTURE_FLAGS-EQUIPMENT_FLAGS-CLIMATE-EFFECTIVE_START-VINTAGE_YEAR-ENROLLMENT_CLOSE-EFFECTIVE_END-NAME_CODE
C), industrial (I), and agricultural (A) plans use this extended format:
COUNTRY-STATE-DIST_UTILITY-ENERGY_PROVIDER-SECTOR-STRUCTURE_FLAGS-PHASE-VOLTAGE_CLASS-DEMAND_MIN-DEMAND_MAX-DEMAND_UNIT-METERING-USAGE_MIN-USAGE_MAX-CLIMATE-EFFECTIVE_START-VINTAGE_YEAR-ENROLLMENT_CLOSE-EFFECTIVE_END-NAME_CODE
USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES
Residential Segment Breakdown
| Segment | Meaning | Notes |
|---|
COUNTRY | ISO 3166-1 alpha-3 country code | Example: USA, CAN |
STATE | ISO 3166-2 state or province code | Example: CA, TX, ON |
DIST_UTILITY | Distribution utility identifier | Usually the 5-digit EIA utility ID |
ENERGY_PROVIDER | Retail energy provider identifier | Bundled plans usually repeat the distribution utility ID; unknown can be ????? |
SECTOR | Customer sector | Usually the first letter of the sector, such as R, C, or I |
STRUCTURE_FLAGS | 6-character plan-structure block | Encodes structure, demand, export, medical baseline, low-income, and demand-response signals |
EQUIPMENT_FLAGS | 6-character applicability block | For residential plans, this block identifies solar/export participation, full-electric eligibility, electric water heating, electric space heating, EV eligibility, and dwelling type |
CLIMATE | Climate or baseline region code | Two characters, such as B4 |
EFFECTIVE_START | Effective start date | MMDDYYYY or ???????? if unknown |
VINTAGE_YEAR | Vintage year | Usually a 4-digit year or ???? |
ENROLLMENT_CLOSE | Closed-to-new-customer date | MMDDYYYY or ???????? |
EFFECTIVE_END | Effective end date | MMDDYYYY or ???????? |
NAME_CODE | Sanitized plan code or short name | Often derived from the source plan name, plus differentiating suffixes |
STRUCTURE_FLAGS Character Map
The STRUCTURE_FLAGS segment is six characters long:
[structure][demand][export][medical][low_income][demand_response]
| Position | Meaning | Current Values |
|---|
| 1 | Structure | T = tiered/TOU structure present, F = flat, ? = unknown |
| 2 | Demand | T = TOU/tiered demand, F = flat demand, M = mixed demand types, N = no demand charge, ? = unknown |
| 3 | Export | 1 = NEM1, 2 = NEM2, 3 = NEM3/NBT, N = no export program |
| 4 | Medical baseline | M = enrolled, N = not enrolled |
| 5 | Low income | L = enrolled, N = not enrolled |
| 6 | Demand response | Y = enrolled, N = not enrolled, ? = unknown |
EQUIPMENT_FLAGS Character Map
For residential plans, the EQUIPMENT_FLAGS segment is a six-character applicability block:
[rooftop_solar][full_electric][electric_water_heating][electric_space_heating][ev][dwelling_type]
| Position | Meaning | Current Values |
|---|
| 1 | Rooftop solar / export participation | R = export-enabled / solar-enrolled, N = not export-enabled |
| 2 | Full electric | R = required, D = disqualifying, ? = unknown |
| 3 | Electric water heating | R = required, D = disqualifying, ? = unknown |
| 4 | Electric space heating | R = required, D = disqualifying, ? = unknown |
| 5 | EV | R = required, D = disqualifying, ? = unknown |
| 6 | Dwelling type | Usually first-character shorthand such as S, M, E, or ? |
Example Breakdown
For this example:
USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES
USA-CA-14328-14328-R: U.S. residential plan for utility 14328TNNNNN: tiered/TOU-style structure, no demand charge, no export program, no medical baseline, no low-income flag, no demand-response flagN????E: no rooftop-solar/export requirement, unknown equipment flags, dwelling type EB4: climate or baseline region code01012025: effective start date of January 1, 2025????: unknown vintage year????????: unknown enrollment close date????????: unknown effective end dateBES: sanitized name code
Notes
- Date segments use UTC formatting in
MMDDYYYY.
- Unknown date segments are intentionally serialized as
????????.
- Related vintages of the same tariff often differ only in the date segments.
Non-Residential Segment Breakdown
For commercial (C), industrial (I), and agricultural (A) plans, the residential EQUIPMENT_FLAGS block is replaced by dedicated eligibility segments that capture the main splitters used in non-residential tariffs.
In the non-residential shape:
R keeps the residential format shown above.C, I, and A use the extended non-residential format.NAME_CODE remains tariff-family oriented and should not carry phase, voltage, demand, metering, or usage variants that already have dedicated segments.
| Segment | Meaning | Notes |
|---|
PHASE | Service phase eligibility | One-character normalized phase code |
VOLTAGE_CLASS | Voltage eligibility class | One-character normalized voltage class |
DEMAND_MIN | Minimum demand eligibility threshold | Five-character encoded threshold |
DEMAND_MAX | Maximum demand eligibility threshold | Five-character encoded threshold |
DEMAND_UNIT | Demand threshold unit | One-character unit code such as K for kW |
METERING | Metering requirement | One-character metering requirement code |
USAGE_MIN | Minimum usage eligibility threshold | Six-character encoded threshold with one shared usage-basis code |
USAGE_MAX | Maximum usage eligibility threshold | Five-character encoded threshold |
CLIMATE | Climate or baseline region code | Same role as in the current format |
EFFECTIVE_START | Effective start date | Same role as in the current format |
VINTAGE_YEAR | Vintage year | Same role as in the current format |
ENROLLMENT_CLOSE | Closed-to-new-customer date | Same role as in the current format |
EFFECTIVE_END | Effective end date | Same role as in the current format |
NAME_CODE | Sanitized plan code or tariff short id | Same role as in the current format |
Non-Residential Enums
PHASE
| Code | Meaning |
|---|
S | single_phase |
T | three_phase |
B | single_or_three |
? | unknown or unspecified |
VOLTAGE_CLASS
| Code | Meaning |
|---|
S | secondary |
P | primary |
U | subtransmission |
T | transmission |
O | other |
? | unknown or unspecified |
DEMAND_UNIT
| Code | Meaning |
|---|
K | kW |
A | kVA |
R | kVAR |
O | other |
? | unknown or unspecified |
METERING
| Code | Meaning |
|---|
N | none |
S | single_meter |
D | demand_metered |
E | energy_only / non_demand |
I | interval_or_idr |
P | special |
? | unknown or unspecified |
METERING field is meant to capture eligibility conditions such as demand-metered service, energy-only or non-demand service, single-meter service, or interval or IDR requirements.
Threshold Encoding
DEMAND_MIN, DEMAND_MAX, and USAGE_MAX use this five-character format:
USAGE_MIN uses this six-character format so the usage pair shares one basis code:
[basis][exp][strictness][ddd]
Threshold Fields
exp: power-of-10 exponentstrictness: I for inclusive and S for strictddd: three-digit mantissa
Threshold Interpretation
- In a
MIN field:
- In a
MAX field:
Examples:
0S020 in DEMAND_MIN means > 201I100 in DEMAND_MIN means >= 1,0002I250 in DEMAND_MAX means <= 25,000
Use the largest power of 10 that preserves an integer three-digit mantissa. The middle character is I or S depending on whether the tariff rule is inclusive or strict:
20 -> 0I020 or 0S0201,000 -> 1I100 or 1S10012,500 -> 2I125 or 2S125250,000 -> 3I250 or 3S250
Unknown threshold fields use fixed-width unknown values:
DEMAND_MIN, DEMAND_MAX, USAGE_MAX -> ?????USAGE_MIN -> ??????
Usage Basis Codes
| Code | Meaning |
|---|
M | monthly / billing month |
Y | annual |
R | rolling or latest 12-month |
O | other complex period |
? | unknown or unspecified |
M2S125 in USAGE_MIN means monthly > 12,500 kWhR2I150 in USAGE_MIN means rolling-12-month >= 15,000 kWh
The RateID should preserve the normalized usage basis, while the exact legal timing rule remains in the tariff object.
Non-Residential Examples
Example 1:
USA-CA-14328-14328-C-TNNNNN-S-P-0I020-1S100-K-D-M2S125-2I250-B4-01012026-2026-????????-????????-GS2
- commercial tariff
- single-phase service
- primary voltage class
- demand eligibility from
>= 20 kW to < 1,000 kW
- demand-metered service
- monthly usage from
> 12,500 kWh to <= 25,000 kWh
Example 2:
USA-WI-20856-20856-I-TM1NNN-B-S-3I250-?????-A-E-R2S150-?????-B4-01012025-2025-????????-????????-GENERAL
- industrial tariff
- single-phase or three-phase service
- secondary voltage class
- demand eligibility of
>= 250,000 kVA
- no encoded maximum demand threshold
- energy-only or non-demand metering requirement
- rolling-12-month usage threshold of
> 15,000 kWh
This non-residential structure is part of the documented semantic RateID schema for non-residential sectors. Residential plans continue to use the residential format documented earlier on this page.