Volue Insight API Python Library

0.7.15 · active · verified Fri Apr 17

The `wapi-python` library provides programmatic access to the Volue Insight API (formerly Wattsight API). It allows users to retrieve energy market data, forecasts, and reports. The current version is 0.7.15. It is actively maintained with regular releases, typically multiple times per year, introducing new features and bug fixes.

Common errors

```
wapi.errors.WapiError: Missing credentials. Client ID and Client Secret are required.
```
cause The API client ID and/or client secret were not provided or were incorrect during session initialization.

fix Set the environment variables `WAPI_CLIENT_ID` and `WAPI_CLIENT_SECRET` to your actual credentials, or pass them as arguments to `Session(client_id='your_id', client_secret='your_secret')`.
```
AttributeError: 'WapiSeries' object has no attribute 'to_pandas'
```
cause Since version 0.7.0, `session.get_series` returns a `WapiSeries` object, not a Pandas DataFrame. The `to_pandas` method (common in some other libraries) does not exist on `WapiSeries`.

fix Use the correct method `my_series.as_pandas()` to convert the `WapiSeries` object to a Pandas DataFrame.
```
wapi.errors.WapiError: No series found for series_id=...
```
cause The `series_id` provided to `session.get_series` does not exist, is incorrect, or is not accessible with your current API subscription.

fix Verify the `series_id` in the Volue Insight portal or documentation. Ensure your API client has access rights to the specific series.
```
TypeError: __init__ got an unexpected keyword argument 'headers'
```
cause Attempting to pass custom HTTP headers directly to the `Session` constructor using a `headers` argument, which is not supported.

fix If you need to pass custom headers (e.g., for proxies or specific API versions), use the `proxies` argument for proxy configurations or consult the `wapi-python` documentation for advanced HTTP client configuration, or create a custom `requests.Session` and pass it to `wapi.Session(requests_session=my_requests_session)`.

Warnings

breaking Default output format for `session.get_series` and similar methods changed from Pandas DataFrame to native `WapiSeries` and `WapiTimeSeries` objects.
Fix: Call `.as_pandas()` on the returned `WapiSeries` object to convert it to a DataFrame. Alternatively, you can explicitly configure output using `Session(output_type=PandasDataFrameOutput)`. Example: `my_series.as_pandas()`
deprecated Old data retrieval methods like `session.get_series_data`, `session.get_region_data`, and `session.get_market_data` are deprecated.
Fix: Use the unified `session.get_series(...)` method for all time series data retrieval.
breaking Python 3.7 is no longer supported.
Fix: Upgrade your Python environment to Python 3.8 or higher. The library is tested against Python 3.8, 3.9, 3.10, and 3.11.
gotcha Incorrect API credentials result in authentication errors.
Fix: Ensure `WAPI_CLIENT_ID` and `WAPI_CLIENT_SECRET` environment variables are correctly set, or pass `client_id` and `client_secret` directly to the `Session` constructor. Double-check for typos or leading/trailing spaces.

Install

pip install wapi-python Install latest version

Imports

Session
```
from wapi import Session
```
PandasDataFrameOutput
wrong:
```
from wapi import PandasDataFrameOutput
```
correct:
```
from wapi.output import PandasDataFrameOutput
```
Output formatters are in the `wapi.output` submodule.
get_series_data
wrong:
```
session.get_series_data(...)
```
correct:
```
session.get_series(...)
```
Deprecated in v0.5.0; use `session.get_series` instead.

Quickstart

This quickstart demonstrates how to initialize a session with the Volue Insight API and retrieve a time series by its ID. It highlights the use of environment variables for credentials and shows how to convert the native `WapiSeries` object to a Pandas DataFrame.

import os
from wapi import Session

# Set up session using client ID and secret (from environment variables or direct arguments)
# Ensure WAPI_CLIENT_ID and WAPI_CLIENT_SECRET environment variables are set.
# Alternatively, pass client_id='your_id' and client_secret='your_secret' directly.
session = Session(
    client_id=os.environ.get('WAPI_CLIENT_ID', 'YOUR_CLIENT_ID'),
    client_secret=os.environ.get('WAPI_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')
)

# Example: Get a single time series by ID
# (Replace 10000001 with a valid series_id from your Volue Insight subscription)
series_id = 10000001
start_date = "2023-01-01"
end_date = "2023-01-07"

try:
    ts = session.get_series(
        series_id=series_id,
        start_date=start_date,
        end_date=end_date
    )

    print(f"Retrieved series {series_id} (type: {type(ts)}):")
    if ts:
        # Convert to Pandas DataFrame for easier manipulation and printing
        print(ts.as_pandas())
    else:
        print("No data retrieved for the specified series and date range.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →