oma-helen-cli 1.7.0

Oma Helen API library and CLI

Oma Helen CLI

An interactive CLI to use Oma Helen from your command line. Offers an API client to get contract data and electricity measurements in JSON format.

What is Oma Helen?

Oma Helen is the user portal for a Finnish electricity company, Helen Oy.

How to install and use

Install from pypi and run:

pip install oma-helen-cli
oma-helen-cli

Then just enter you Oma Helen credentials and start entering commands.

Tip: in order to list all the commands within the CLI, enter ?

Available functions

Function name	What it does
get_api_access_token	Get the access token to the Oma Helen API. With the token, you can make manual curl requests to the API
refresh_token	Re-authenticate the session. Tries to refresh the access token, but if that fails, logs in again with username and password
get_contract_base_price	Get the monthly base price of your current electricity contract
get_contract_data_json	Returns the whole contract data as JSON. Will return all active contracts you have with Helen
get_daily_measurements_json	Returns your daily energy consumption for the on-going month of the on-going year as JSON
get_market_prices_json	Returns the prices for the Market Price Electricity contract as JSON. The JSON includes the price for last month, the current month and next month if available
get_monthly_measurements_json	Returns your monthly energy consumption for the on-going year as JSON
calculate_the_impact_of_usage_between_dates	Calculates your impact of usage (in c/kwh) between given dates for the Helen Smart Electricity Guarantee
calculate_spot_cost_between_dates	Calculates the total costs (eur) between given dates of a spot price contract in an hourly precision
get_exchange_margin_price_json	Get the margin price of the Exchange Electricity contract
get_contract_energy_unit_price	Get the energy unit price (c/kwh) from your contract data. Note that this only works for fixed price contracts. For spot electricity contract, this returns 0.0
get_contract_transfer_fee	Get the transfer fees (c/kwh) from your contract. Note that if Helen is not your transfer company, this returns 0.0
calculate_transfer_fees_between_dates	Calculates total transfer fees (eur) based on your consumption between dates
get_contract_transfer_base_price	Get the monthly transfer base price (eur) from your contract. Note that if Helen is not your transfer company, this returns 0.0
get_all_delivery_sites	Get all delivery sites across your active contracts
get_all_gsrn_ids	Get all GSRN ids across your active contracts
select_delivery_site	Select a delivery site by id for the CLI to use. Accepts both GSRN ids and delivery site ids as input. Useful if you have multiple contracts with Helen. Use get_all_delivery_sites or get_all_gsrn_ids to find out all your delivery sites / GSRN ids. After selecting a delivery site, all measurements and other requested data will be about the selected delivery site.
get_contract_type	Get the contract type (e.g., exchange electricity, market price) from your contract data
get_spot_prices_chart_data	Get spot prices from chart data API for a single day, including 15-minute intervals
get_hourly_measurements_with_spot_prices_json	Get the measurements with spot prices for each hour between given dates
get_quarterly_measurements_with_spot_prices_json	Get the measurements with spot prices for each quarter between given dates
exit	Exit the CLI application

Installing from sources and running the project for local development

First clone this repo.

This project uses uv for fast dependency management. Make sure you have uv installed.

1. In the project root folder run uv sync to install dependencies
2. Launch the CLI with uv run oma-helen-cli
3. Enter your username and password as they are prompted
4. Type ? into the CLI prompt to see all available functions

For development with test dependencies: uv sync --extra test

Testing

Install test dependencies uv sync --extra test

Run tests uv run pytest tests/test_api_client.py

Run with verbose output uv run pytest tests/test_api_client.py -v