Skip to content

Add data providers and JSON output pages to docs #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jpvelez merged 1 commit into from
Dec 2, 2025
Merged

Add data providers and JSON output pages to docs #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/providers/arcadia/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Arcadia — Signal Tariffs API

Arcadia's Signal Tariffs API (formerly Genability) provides comprehensive US utility tariff data with detailed rate structures, variable rate lookups, and bill calculation capabilities.

## Overview

- **Provider**: Arcadia
- **Product**: Signal Tariffs API
- **Energy Types**: Electricity
- **Coverage**: ~3,000+ US utilities, 100,000+ tariffs
- **Features**: Variable rate lookups, bill calculations, historical versions
- **Authentication**: API key required

## Data Format

The Signal API uses a custom JSON objects to represent tariffs, with a complex hierarchical structure.

- **[Short guide to the Tariff JSON](tariff-json-structure.md)**
- [Official API docs on Tariff JSON](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff)

## Key Endpoints

| Endpoint | Purpose |
|----------|---------|
| `GET /tariffs` | Search and retrieve tariffs |
| `GET /tariffs/{tariffId}` | Get a specific tariff with rates |
| `GET /tariffs/{masterTariffId}/history` | Historical versions |
| `GET /properties/{key}/lookups` | Variable rate values |
| `POST /calculate` | Bill calculations |


## Pricing

Arcadia charges based on API usage. See their [pricing page](https://www.arcadia.com/signal) for current rates.

204 changes: 204 additions & 0 deletions docs/providers/arcadia/tariff-json-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
# Understanding Arcadia Tariff JSON

> ⚠️ **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.

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).

## Data Hierarchy

Tariff data follows a three-level hierarchy:

```
Tariff (header)
├── properties[] → Input parameters needed for bill calculations
└── rates[] → Array of TariffRate objects (line items)
└── rateBands[] → Array of TariffRateBand objects (tiers/bands)
```

- **Tariff** — The top-level object with metadata about the rate plan (name, utility, customer class, effective dates)
- **TariffRate** — Individual charges like "Customer Charge" or "Summer Rate" — think of these as line items on a bill
- **TariffRateBand** — Tiers within a rate (e.g., first 250 kWh at one price, remaining kWh at another)

## Key Tariff Fields

| Field | Description |
|-------|-------------|
| `tariffId` | Unique ID for *this version* of the tariff |
| `masterTariffId` | Persistent ID across all revisions of a tariff |
| `tariffCode` | Utility's shortcode (e.g., "EL1", "E-1") |
| `tariffName` | Official tariff name |
| `lseId` | Load Serving Entity (utility) ID |
| `effectiveDate` | When this version became effective |
| `priorTariffId` | Previous version's `tariffId` |
| `customerClass` | Target segment: RESIDENTIAL, COMMERCIAL, INDUSTRIAL, etc. |
| `customerCount` | Approximate customers on this tariff |

### `tariffId` vs `masterTariffId`

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`.

- Use **`masterTariffId`** when tracking a tariff over time or fetching historical versions
- Use **`tariffId`** when you need to reference a specific version

To get historical versions, use the [Tariff History API](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history).

### Boolean Flags

These flags tell you what features a tariff has without parsing all the rates:

| Flag | What It Tells You |
|------|-------------------|
| `hasTimeOfUseRates` | Rates vary by time of day (peak/off-peak) |
| `hasTieredRates` | Some rates have consumption-based tiers |
| `hasContractedRates` | Includes supply charges (for bundled service) |
| `hasNetMetering` | Net metering is available for solar customers |
| `isActive` | Tariff is currently in effect |

---

## Properties

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.

### What Properties Tell You

Before running any calculations, the properties array reveals:

- **What inputs you need** — `consumption` (kWh), `demand` (kW), time-of-use period, etc.
- **What choices exist** — Territory/zone options, service types, rate schedules
- **Default assumptions** — What values are assumed if you don't specify (e.g., `systemSize: 0` assumes no solar)
- **Tariff complexity** — More properties usually means more rate variations

### Common Property Types

| `propertyTypes` | Meaning |
|-----------------|---------|
| `RATE_CRITERIA` | Input that affects which rates apply or how they're calculated |
| `SERVICE_TERMS` | Describes service characteristics (informational, not an input) |

### Common Properties

| Property | Description | Typical Use |
|----------|-------------|-------------|
| `consumption` | Energy usage (kWh) | All consumption-based charges |
| `demand` | Peak demand (kW) | Demand charges (commercial tariffs) |
| `territoryId` | Service zone/region | Zone-specific rates |
| `systemSize` | Solar system capacity (kW) | Solar-related charges (CBC, net metering) |
| `connectionType` | Single-phase vs. three-phase | Service charges |
| `chargeClass` | Categories to include | Filtering SUPPLY vs. DISTRIBUTION |

### Property Structure

Each property has metadata explaining what it is and how to use it:

```json
{
"keyName": "territoryId",
"displayName": "Territory",
"description": "Rate Baseline Region",
"dataType": "CHOICE",
"propertyTypes": "RATE_CRITERIA",
"choices": [
{ "displayValue": "Zone H", "value": "3632" },
{ "displayValue": "Zone I", "value": "3633" },
{ "displayValue": "Zone J", "value": "3634" }
],
"isDefault": true
}
```

- **`keyName`** — The key to use in API calls
- **`dataType`** — DECIMAL, CHOICE, STRING, BOOLEAN, etc.
- **`choices`** — For CHOICE types, the valid options
- **`propertyValue`** / **`isDefault`** — Default value if not specified

---

## Rates

The `rates` array contains the actual charges. Each `TariffRate` object represents a line item like "Customer Charge" or "Summer Delivery Rate."

### Key Rate Fields

| Field | Description |
|-------|-------------|
| `rateName` | Human-readable name |
| `rateGroupName` | Category grouping (e.g., "Delivery Charges") |
| `chargeType` | How it's calculated: FIXED_PRICE, CONSUMPTION_BASED, QUANTITY, MINIMUM |
| `chargeClass` | Category: DISTRIBUTION, SUPPLY, TRANSMISSION, TAX |
| `variableRateKey` | If present, rate value must be looked up via API |
| `territory` | If present, rate is zone-specific |
| `season` | If present, rate is seasonal |
| `rateBands` | Tier structure with actual rate amounts |

### Charge Types

| `chargeType` | Meaning | Unit |
|--------------|---------|------|
| `FIXED_PRICE` | Flat monthly fee | $/month |
| `CONSUMPTION_BASED` | Per-kWh charge | $/kWh |
| `QUANTITY` | Based on a property value | Varies ($/kW, %) |
| `DEMAND` | Based on peak demand | $/kW |
| `MINIMUM` | Floor on total bill | $/month |

### Variable Rates

Some rates change frequently (monthly supply charges, adjustment factors). These have:

- `rateAmount: 0.0` — Placeholder value
- `variableRateKey` — Key to use with the [Lookups API](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups)

---

## Rate Bands

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.

### Key Rate Band Fields

| Field | Description |
|-------|-------------|
| `rateAmount` | The actual rate value |
| `rateUnit` | COST_PER_UNIT, PERCENTAGE, etc. |
| `consumptionUpperLimit` | For tiered rates, the kWh threshold |
| `rateSequenceNumber` | Order of tiers (1, 2, 3...) |
| `isCredit` | True if this is a credit (negative charge) |

### Tiered Rate Example

```json
"rateBands": [
{
"rateSequenceNumber": 1,
"consumptionUpperLimit": 250.0,
"rateAmount": 0.16107
},
{
"rateSequenceNumber": 2,
"rateAmount": 0.18518
}
]
```

This means: First 250 kWh at $0.16107/kWh, remaining kWh at $0.18518/kWh.

---

## Riders

Riders are modular tariff components that can be attached to multiple base tariffs. They appear in the rates array with special fields:

- **`riderId`** — Reference to a rider tariff (placeholder, no rate details)
- **`riderTariffId`** — The actual rider implementation (contains rate details)

For bill calculations, use rates with `riderTariffId` — they have all the charge details already resolved.

---

## Further Reading

- [Arcadia Tariff API Reference](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff) — Complete field definitions
- [Lookups API](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups) — Retrieving variable rate values
- [Calculate API](https://docs.arcadia.com/v2022-12-21-Signal/reference/calculate) — Running bill calculations
- [Tariff History API](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history) — Historical tariff versions

24 changes: 24 additions & 0 deletions docs/providers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Data Providers

`tariff_fetch` can retrieve tariff data from multiple sources. Each provider has different coverage, data formats, and API conventions.

## Supported Providers

| Provider | Product | Energy Types | Coverage | Data Format |
|----------|---------|--------------|----------|-------------|
| [Arcadia](arcadia/index.md) | Signal Tariffs API | Electricity | US utilities, comprehensive | Tariff JSON object |
| [NREL](nrel/index.md) | Utility Rate Database (URDB) | Electricity | US utilities | URDB JSON format |
| [Rate Acuity](rateacuity/index.md) | Web Portal | Electricity, Gas | US utilities | CSV exports |

## Choosing a Provider

**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.

**Arcadia Signal Tariffs API** is the most comprehensive option for US electricity tariff data. It is paid and includes:

- Detailed rate structures with tiers, seasons, and TOU periods
- Variable rate lookups via API
- Historical tariff versions

**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.

43 changes: 43 additions & 0 deletions docs/providers/nrel/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# NREL / OpenEI — Utility Rate Database (URDB)

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.

## Overview

- **Provider**: NREL / OpenEI
- **Product**: Utility Rate Database (URDB)
- **Energy Types**: Electricity
- **Coverage**: US utilities (coverage varies)
- **Features**: Free access, open data
- **Authentication**: API key (free registration)

## Data Format

URDB outputs data in the an open data standard called URDB JSON. Many NREL tools already accept this standard.

- **[Short guide to URDB JSON](urdb-json-structure.md)**
- [Official API docs on URDB JSON](https://openei.org/services/doc/rest/util_rates/?version=7)

## Key Endpoints

| Endpoint | Purpose |
|----------|---------|
| `GET /utility_rates` | Search and retrieve rates |
| `GET /utility_rates?getpage={label}` | Get a specific rate by ID |
| `GET /utility_rates?ratesforutility={name}` | Get all rates for a utility |
| `GET /utility_rates?lat={lat}&lon={lon}` | Find rates by location |

## Resources

- [Browse URDB Rates](https://openei.org/apps/USURDB/) — Interactive rate browser
- [NREL Developer Network](https://developer.nrel.gov/) — API key registration (free)

## Comparison with Arcadia

| Aspect | URDB | Arcadia |
|--------|------|---------|
| Cost | Free | Paid |
| Coverage | OK, community-maintained | Comprehensive, professionally maintained |
| Update frequency | Annual | Regular updates |
| Variable rates | Not supported | Lookups API |

Loading
Loading