Metadata-Version: 2.4
Name: tariff_fetch
Version: 0.1
Summary: A CLI tool and a python library to simplify downloading electric and gas utility tariff data.
Project-URL: Repository, https://github.com/switchbox-data/tariff_fetch
Project-URL: Documentation, https://switchbox-data.github.io/tariff_fetch/
Author-email: Switchbox <hello@switch.box>
License-File: LICENSE
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4.0,>=3.11
Requires-Dist: fastexcel>=0.16.0
Requires-Dist: fuzzywuzzy>=0.18.0
Requires-Dist: pathvalidate>=3.3.1
Requires-Dist: polars>=1.34.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: python-levenshtein>=0.27.1
Requires-Dist: questionary>=2.1.1
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.2.0
Requires-Dist: selenium>=4.36.0
Requires-Dist: tenacity>=9.1.2
Requires-Dist: typedload>=2.38
Requires-Dist: typer>=0.19.2
Requires-Dist: typing-extensions>=4.15.0
Description-Content-Type: text/markdown

# Tariff Fetch

[![Release](https://img.shields.io/github/v/release/switchbox-data/tariff_fetch)](https://img.shields.io/github/v/release/switchbox-data/tariff_fetch)
[![Build status](https://img.shields.io/github/actions/workflow/status/switchbox-data/tariff-fetch/main.yml?branch=main)](https://github.com/switchbox-data/tariff_fetch/actions/workflows/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]
```

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.
