# Tariff Fetch

[![PyPI version](https://img.shields.io/pypi/v/tariff_fetch)](https://pypi.org/project/tariff_fetch/)
[![Build status](https://img.shields.io/github/actions/workflow/status/switchbox-data/tariff_fetch/python-package-main.yml?branch=main)](https://github.com/switchbox-data/tariff_fetch/actions/workflows/python-package-main.yml?query=branch%3Amain)
[![Commit activity](https://img.shields.io/github/commit-activity/m/switchbox-data/tariff_fetch)](https://img.shields.io/github/commit-activity/m/switchbox-data/tariff_fetch)
[![License](https://img.shields.io/github/license/switchbox-data/tariff_fetch)](https://img.shields.io/github/license/switchbox-data/tariff_fetch)

A CLI tool, and python library, to simplify downloading electric and gas utility tariff data from multiple providers in a consistent data format.

- **Github repository**: <https://github.com/switchbox-data/tariff_fetch/>
- **Documentation**: <https://switchbox-data.github.io/tariff_fetch/>
- **PyPI page**: <https://pypi.org/project/tariff_fetch/>

## Requirements

- Python 3.11+
- Credentials for the providers you intend to call:

  - **Genability / Arcadia Data Platform**: `ARCADIA_APP_ID`, `ARCADIA_APP_KEY`

    [Create an account](https://dash.genability.com/signup), navigate to [Applications dashboard](https://dash.genability.com/org/applications), create an application, then copy the Application ID and Key.

  - **OpenEI**: `OPENEI_API_KEY`

    Request a key at the [OpenEI API signup](https://openei.org/services/api/signup/). The key arrives by email.

  - **RateAcuity Web Portal**: `RATEACUITY_USERNAME`, `RATEACUITY_PASSWORD`

    There is no self-serve signup. [Contact RateAcuity](https://rateacuity.com/contact-us/) to request Web Portal access. No API key is required for `tariff_fetch`.

- Google Chrome or Chromium installed locally (for RateAcuity)

## Configuration

Populate a `.env` file (or export the variables manually). Only set the values you need.

```
ARCADIA_APP_ID=...
ARCADIA_APP_KEY=...
OPENEI_API_KEY=...
RATEACUITY_USERNAME=...
RATEACUITY_PASSWORD=...
```

## Running CLI with uvx

If you have [uv](https://github.com/astral-sh/uv/releases) installed, you can run the cli simply with

```bash
uvx --env-file=.env --from git+https://github.com/switchbox-data/tariff_fetch tariff-fetch
```

Or, for gas tariffs:

```bash
uvx --env-file=.env --from git+https://github.com/switchbox-data/tariff_fetch tariff-fetch-gas
```

## Installation

```bash
uv sync
source .venv/bin/activate
```

Alternative using plain `pip`:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Running the CLI

```bash
python -m tariff_fetch.cli [OPTIONS]
python -m tariff_fetch.cli_gas [OPTIONS]
```

With uv:

```bash
uv run tariff-fetch [OPTIONS]
uv run tariff-fetch-gas [OPTIONS]
uv run tariff-fetch-arcadia-urdb MASTER_TARIFF_ID YEAR [OPTIONS]
```

With Just:

```bash
just cli
just cligas
```

Options:

- `--state` / `-s`: two-letter state abbreviation (default: prompt)
- `--providers` / `-p`: (only for electricity benchmarks) repeat per provider (`genability`, `openei`, `rateacuity`)
- `--output-folder` / `-o`: directory for exports (default: `./outputs`)

Omitted options will trigger interactive prompts.

### Examples

```bash
# Fully interactive run
uv run tariff-fetch

# Scripted run for Genability and OpenEI
uv run tariff-fetch.cli \
  --state ca \
  --providers genability \
  --providers openei \
  --output-folder data/exports
```

The CLI suggests filenames like `outputs/openei_Utility_sector_detail-0_2024-03-18.json` before writing each file so you
can accept or override them.

## Direct Arcadia to URDB Conversion

For direct conversion of a single Arcadia master tariff to URDB JSON:

```bash
uv run tariff-fetch-arcadia-urdb 522 2025
```

Useful options:

- `--output` / `-o`: output file path
- `--apply-percentages` / `--no-apply-percentages`
- `--charge-class`: repeat to include multiple charge classes
- `--force` / `-f`: overwrite an existing output file
