Skip to content

Commit 6aa4109

Browse files
jpvelezjpvelez
authored
Merge pull request #18 from switchbox-data/17-add-data-providers-section-to-docs
Add data providers and JSON output pages to docs
2 parents 50b6175 + 1b8aacf commit 6aa4109

File tree

7 files changed

+1449
-0
lines changed

7 files changed

+1449
-0
lines changed

‎docs/providers/arcadia/index.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Arcadia — Signal Tariffs API
2+
3+
Arcadia's Signal Tariffs API (formerly Genability) provides comprehensive US utility tariff data with detailed rate structures, variable rate lookups, and bill calculation capabilities.
4+
5+
## Overview
6+
7+
- **Provider**: Arcadia
8+
- **Product**: Signal Tariffs API
9+
- **Energy Types**: Electricity
10+
- **Coverage**: ~3,000+ US utilities, 100,000+ tariffs
11+
- **Features**: Variable rate lookups, bill calculations, historical versions
12+
- **Authentication**: API key required
13+
14+
## Data Format
15+
16+
The Signal API uses a custom JSON objects to represent tariffs, with a complex hierarchical structure.
17+
18+
- **[Short guide to the Tariff JSON](tariff-json-structure.md)**
19+
- [Official API docs on Tariff JSON](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff)
20+
21+
## Key Endpoints
22+
23+
| Endpoint | Purpose |
24+
|----------|---------|
25+
| `GET /tariffs` | Search and retrieve tariffs |
26+
| `GET /tariffs/{tariffId}` | Get a specific tariff with rates |
27+
| `GET /tariffs/{masterTariffId}/history` | Historical versions |
28+
| `GET /properties/{key}/lookups` | Variable rate values |
29+
| `POST /calculate` | Bill calculations |
30+
31+
32+
## Pricing
33+
34+
Arcadia charges based on API usage. See their [pricing page](https://www.arcadia.com/signal) for current rates.
35+

‎docs/providers/arcadia/tariff-json-structure.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Understanding Arcadia Tariff JSON
2+
3+
> ⚠️ **Disclaimer**: This guide was generated by an LLM (Claude Opus 4.5) based on Arcadia API documentation and tariff data. The content looks reasonable but **has not been verified by domain experts**. Please verify any claims before relying on them for production use.
4+
5+
This page explains the structure of tariff data returned by the Arcadia Signal API. For complete field definitions, see the [Arcadia Tariff API Reference](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff).
6+
7+
## Data Hierarchy
8+
9+
Tariff data follows a three-level hierarchy:
10+
11+
```
12+
Tariff (header)
13+
├── properties[] → Input parameters needed for bill calculations
14+
└── rates[] → Array of TariffRate objects (line items)
15+
└── rateBands[] → Array of TariffRateBand objects (tiers/bands)
16+
```
17+
18+
- **Tariff** — The top-level object with metadata about the rate plan (name, utility, customer class, effective dates)
19+
- **TariffRate** — Individual charges like "Customer Charge" or "Summer Rate" — think of these as line items on a bill
20+
- **TariffRateBand** — Tiers within a rate (e.g., first 250 kWh at one price, remaining kWh at another)
21+
22+
## Key Tariff Fields
23+
24+
| Field | Description |
25+
|-------|-------------|
26+
| `tariffId` | Unique ID for *this version* of the tariff |
27+
| `masterTariffId` | Persistent ID across all revisions of a tariff |
28+
| `tariffCode` | Utility's shortcode (e.g., "EL1", "E-1") |
29+
| `tariffName` | Official tariff name |
30+
| `lseId` | Load Serving Entity (utility) ID |
31+
| `effectiveDate` | When this version became effective |
32+
| `priorTariffId` | Previous version's `tariffId` |
33+
| `customerClass` | Target segment: RESIDENTIAL, COMMERCIAL, INDUSTRIAL, etc. |
34+
| `customerCount` | Approximate customers on this tariff |
35+
36+
### `tariffId` vs `masterTariffId`
37+
38+
Tariff data changes periodically — a residential tariff might update several times per year as rates are adjusted. Each revision gets a new `tariffId`, but they all share the same `masterTariffId`.
39+
40+
- Use **`masterTariffId`** when tracking a tariff over time or fetching historical versions
41+
- Use **`tariffId`** when you need to reference a specific version
42+
43+
To get historical versions, use the [Tariff History API](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history).
44+
45+
### Boolean Flags
46+
47+
These flags tell you what features a tariff has without parsing all the rates:
48+
49+
| Flag | What It Tells You |
50+
|------|-------------------|
51+
| `hasTimeOfUseRates` | Rates vary by time of day (peak/off-peak) |
52+
| `hasTieredRates` | Some rates have consumption-based tiers |
53+
| `hasContractedRates` | Includes supply charges (for bundled service) |
54+
| `hasNetMetering` | Net metering is available for solar customers |
55+
| `isActive` | Tariff is currently in effect |
56+
57+
---
58+
59+
## Properties
60+
61+
The `properties` array defines **input parameters** needed to calculate bills. When you call the Calculate API, you provide values for these properties, and the API uses them to determine which rates apply and compute charges.
62+
63+
### What Properties Tell You
64+
65+
Before running any calculations, the properties array reveals:
66+
67+
- **What inputs you need** — `consumption` (kWh), `demand` (kW), time-of-use period, etc.
68+
- **What choices exist** — Territory/zone options, service types, rate schedules
69+
- **Default assumptions** — What values are assumed if you don't specify (e.g., `systemSize: 0` assumes no solar)
70+
- **Tariff complexity** — More properties usually means more rate variations
71+
72+
### Common Property Types
73+
74+
| `propertyTypes` | Meaning |
75+
|-----------------|---------|
76+
| `RATE_CRITERIA` | Input that affects which rates apply or how they're calculated |
77+
| `SERVICE_TERMS` | Describes service characteristics (informational, not an input) |
78+
79+
### Common Properties
80+
81+
| Property | Description | Typical Use |
82+
|----------|-------------|-------------|
83+
| `consumption` | Energy usage (kWh) | All consumption-based charges |
84+
| `demand` | Peak demand (kW) | Demand charges (commercial tariffs) |
85+
| `territoryId` | Service zone/region | Zone-specific rates |
86+
| `systemSize` | Solar system capacity (kW) | Solar-related charges (CBC, net metering) |
87+
| `connectionType` | Single-phase vs. three-phase | Service charges |
88+
| `chargeClass` | Categories to include | Filtering SUPPLY vs. DISTRIBUTION |
89+
90+
### Property Structure
91+
92+
Each property has metadata explaining what it is and how to use it:
93+
94+
```json
95+
{
96+
"keyName": "territoryId",
97+
"displayName": "Territory",
98+
"description": "Rate Baseline Region",
99+
"dataType": "CHOICE",
100+
"propertyTypes": "RATE_CRITERIA",
101+
"choices": [
102+
{ "displayValue": "Zone H", "value": "3632" },
103+
{ "displayValue": "Zone I", "value": "3633" },
104+
{ "displayValue": "Zone J", "value": "3634" }
105+
],
106+
"isDefault": true
107+
}
108+
```
109+
110+
- **`keyName`** — The key to use in API calls
111+
- **`dataType`** — DECIMAL, CHOICE, STRING, BOOLEAN, etc.
112+
- **`choices`** — For CHOICE types, the valid options
113+
- **`propertyValue`** / **`isDefault`** — Default value if not specified
114+
115+
---
116+
117+
## Rates
118+
119+
The `rates` array contains the actual charges. Each `TariffRate` object represents a line item like "Customer Charge" or "Summer Delivery Rate."
120+
121+
### Key Rate Fields
122+
123+
| Field | Description |
124+
|-------|-------------|
125+
| `rateName` | Human-readable name |
126+
| `rateGroupName` | Category grouping (e.g., "Delivery Charges") |
127+
| `chargeType` | How it's calculated: FIXED_PRICE, CONSUMPTION_BASED, QUANTITY, MINIMUM |
128+
| `chargeClass` | Category: DISTRIBUTION, SUPPLY, TRANSMISSION, TAX |
129+
| `variableRateKey` | If present, rate value must be looked up via API |
130+
| `territory` | If present, rate is zone-specific |
131+
| `season` | If present, rate is seasonal |
132+
| `rateBands` | Tier structure with actual rate amounts |
133+
134+
### Charge Types
135+
136+
| `chargeType` | Meaning | Unit |
137+
|--------------|---------|------|
138+
| `FIXED_PRICE` | Flat monthly fee | $/month |
139+
| `CONSUMPTION_BASED` | Per-kWh charge | $/kWh |
140+
| `QUANTITY` | Based on a property value | Varies ($/kW, %) |
141+
| `DEMAND` | Based on peak demand | $/kW |
142+
| `MINIMUM` | Floor on total bill | $/month |
143+
144+
### Variable Rates
145+
146+
Some rates change frequently (monthly supply charges, adjustment factors). These have:
147+
148+
- `rateAmount: 0.0` — Placeholder value
149+
- `variableRateKey` — Key to use with the [Lookups API](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups)
150+
151+
---
152+
153+
## Rate Bands
154+
155+
Each rate has a `rateBands` array containing one or more `TariffRateBand` objects. For simple rates, there's just one band. For tiered rates, there are multiple bands with consumption limits.
156+
157+
### Key Rate Band Fields
158+
159+
| Field | Description |
160+
|-------|-------------|
161+
| `rateAmount` | The actual rate value |
162+
| `rateUnit` | COST_PER_UNIT, PERCENTAGE, etc. |
163+
| `consumptionUpperLimit` | For tiered rates, the kWh threshold |
164+
| `rateSequenceNumber` | Order of tiers (1, 2, 3...) |
165+
| `isCredit` | True if this is a credit (negative charge) |
166+
167+
### Tiered Rate Example
168+
169+
```json
170+
"rateBands": [
171+
{
172+
"rateSequenceNumber": 1,
173+
"consumptionUpperLimit": 250.0,
174+
"rateAmount": 0.16107
175+
},
176+
{
177+
"rateSequenceNumber": 2,
178+
"rateAmount": 0.18518
179+
}
180+
]
181+
```
182+
183+
This means: First 250 kWh at $0.16107/kWh, remaining kWh at $0.18518/kWh.
184+
185+
---
186+
187+
## Riders
188+
189+
Riders are modular tariff components that can be attached to multiple base tariffs. They appear in the rates array with special fields:
190+
191+
- **`riderId`** — Reference to a rider tariff (placeholder, no rate details)
192+
- **`riderTariffId`** — The actual rider implementation (contains rate details)
193+
194+
For bill calculations, use rates with `riderTariffId` — they have all the charge details already resolved.
195+
196+
---
197+
198+
## Further Reading
199+
200+
- [Arcadia Tariff API Reference](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff) — Complete field definitions
201+
- [Lookups API](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups) — Retrieving variable rate values
202+
- [Calculate API](https://docs.arcadia.com/v2022-12-21-Signal/reference/calculate) — Running bill calculations
203+
- [Tariff History API](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history) — Historical tariff versions
204+

‎docs/providers/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Data Providers
2+
3+
`tariff_fetch` can retrieve tariff data from multiple sources. Each provider has different coverage, data formats, and API conventions.
4+
5+
## Supported Providers
6+
7+
| Provider | Product | Energy Types | Coverage | Data Format |
8+
|----------|---------|--------------|----------|-------------|
9+
| [Arcadia](arcadia/index.md) | Signal Tariffs API | Electricity | US utilities, comprehensive | Tariff JSON object |
10+
| [NREL](nrel/index.md) | Utility Rate Database (URDB) | Electricity | US utilities | URDB JSON format |
11+
| [Rate Acuity](rateacuity/index.md) | Web Portal | Electricity, Gas | US utilities | CSV exports |
12+
13+
## Choosing a Provider
14+
15+
**NREL Utility Rate Database (URDB)** is free and open but may have less detailed or less frequently updated data. Good for basic rate lookups and open-source projects.
16+
17+
**Arcadia Signal Tariffs API** is the most comprehensive option for US electricity tariff data. It is paid and includes:
18+
19+
- Detailed rate structures with tiers, seasons, and TOU periods
20+
- Variable rate lookups via API
21+
- Historical tariff versions
22+
23+
**Rate Acuity** provides both electricity and gas tariffs through their web portal. It is also paid Useful when you need gas rates or prefer a different data source for validation.
24+

‎docs/providers/nrel/index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# NREL / OpenEI — Utility Rate Database (URDB)
2+
3+
The Utility Rate Database (URDB) is a free, open dataset of US utility rates maintained by the National Renewable Energy Laboratory (NREL) and hosted on OpenEI.
4+
5+
## Overview
6+
7+
- **Provider**: NREL / OpenEI
8+
- **Product**: Utility Rate Database (URDB)
9+
- **Energy Types**: Electricity
10+
- **Coverage**: US utilities (coverage varies)
11+
- **Features**: Free access, open data
12+
- **Authentication**: API key (free registration)
13+
14+
## Data Format
15+
16+
URDB outputs data in the an open data standard called URDB JSON. Many NREL tools already accept this standard.
17+
18+
- **[Short guide to URDB JSON](urdb-json-structure.md)**
19+
- [Official API docs on URDB JSON](https://openei.org/services/doc/rest/util_rates/?version=7)
20+
21+
## Key Endpoints
22+
23+
| Endpoint | Purpose |
24+
|----------|---------|
25+
| `GET /utility_rates` | Search and retrieve rates |
26+
| `GET /utility_rates?getpage={label}` | Get a specific rate by ID |
27+
| `GET /utility_rates?ratesforutility={name}` | Get all rates for a utility |
28+
| `GET /utility_rates?lat={lat}&lon={lon}` | Find rates by location |
29+
30+
## Resources
31+
32+
- [Browse URDB Rates](https://openei.org/apps/USURDB/) — Interactive rate browser
33+
- [NREL Developer Network](https://developer.nrel.gov/) — API key registration (free)
34+
35+
## Comparison with Arcadia
36+
37+
| Aspect | URDB | Arcadia |
38+
|--------|------|---------|
39+
| Cost | Free | Paid |
40+
| Coverage | OK, community-maintained | Comprehensive, professionally maintained |
41+
| Update frequency | Annual | Regular updates |
42+
| Variable rates | Not supported | Lookups API |
43+

0 commit comments

Comments
 (0)