Energy Quantified Time Series API Client

0.15.1 · active · verified Thu Apr 16

The official Python library for Energy Quantified's Time Series API (eq-python-client). It allows users to access thousands of data series directly from Energy Quantified's time series database. The library integrates with popular data science tools like Pandas and Polars for high-performance data analysis and manipulation. Developed for Python 3.10+, it maintains an active release cadence with frequent minor updates.

Common errors

```
energyquantified.exceptions.EnergyQuantifiedException: Authentication failed
```
cause The provided API key is missing or invalid. An API key is required to use the client.

fix Ensure you have a valid API key from Energy Quantified and that it's correctly passed during client initialization, either directly via `api_key='YOUR_KEY'` or from a file via `api_key_file='path/to/key.txt'`, or via an environment variable. For Realto users, use `RealtoConnection` and specify `api_url`.
```
AttributeError: 'Timeseries' object has no attribute 'to_df'
```
cause You are attempting to use an old method name for Pandas DataFrame conversion. The method names were changed in `v0.14`.

fix Update your code to use the new method names: `timeseries.to_pandas_dataframe()` or `timeseries.to_pd_df()`.
```
AttributeError: 'Timeseries' object has no attribute 'to_pandas_dataframe' or 'to_polars_dataframe'
```
cause The `pandas` or `polars` library is not installed in your environment, but the `energyquantified` client attempts to use its integration methods. The `energyquantified` package does not automatically install these data analysis libraries.

fix Install `pandas` or `polars` separately using `pip install pandas` or `pip install polars`.

Warnings

breaking Pandas DataFrame conversion methods `to_df()` and `to_dataframe()` were renamed to `to_pd_df()` and `to_pandas_dataframe()` respectively. The old methods are deprecated and will be removed in a future major release.
Fix: Update your code to use `to_pd_df()` or `to_pandas_dataframe()` for Pandas DataFrame conversions, and `to_pl_df()` or `to_polars_dataframe()` for Polars.
deprecated The method parameter `exlude_tags` has been deprecated in favor of `exclude_tags`. This affects methods like `eq.instances.list()` and `eq.instances.load()`.
Fix: Replace all occurrences of `exlude_tags` with `exclude_tags` in your method calls.
gotcha Users on Python versions >=3.13.1 and <3.13.4 may experience crashes when calling `PeriodSeries.to_timeseries()` due to a regression in Python's iterator behavior. This was patched in client version v0.14.6.
Fix: Upgrade `energyquantified` client to `v0.14.6` or newer. If you must stay on an older client, avoid Python versions 3.13.1-3.13.3.

Install

pip install energyquantified Install stable version

Imports

EnergyQuantified
wrong:
```
import energyquantified.EnergyQuantified
```
correct:
```
from energyquantified import EnergyQuantified
```
The primary client class is directly importable from the top-level package.
RealtoConnection
```
from energyquantified import RealtoConnection
```
Use this class for users subscribing to the API via the Realto marketplace.

Quickstart

This quickstart initializes the EnergyQuantified client using an API key (preferably from an environment variable), searches for a time series, loads data for it, and then converts the result to a Pandas DataFrame.

import os
from datetime import date, timedelta
from energyquantified import EnergyQuantified

# Initialize client with API key from environment variable
api_key = os.environ.get('EQ_API_KEY', 'YOUR_API_KEY')
eq = EnergyQuantified(api_key=api_key)

# Free-text search for curves
curves = eq.metadata.curves(q='de wind production actual')

if curves:
    # Load time series data for the first matching curve
    curve = curves[0]
    timeseries = eq.timeseries.load(
        curve,
        begin=date.today() - timedelta(days=10),
        end=date.today()
    )

    print(f"Loaded {len(timeseries)} values for {curve.name}")

    # Convert to Pandas DataFrame (requires pandas installed)
    try:
        pd_df = timeseries.to_pandas_dataframe()
        print("\nPandas DataFrame head:")
        print(pd_df.head())
    except AttributeError:
        print("\nSkipping Pandas conversion: pandas not installed or old client version.")
else:
    print("No curves found for the query.")

view raw JSON →