Frequenz Reporting API Client

Introduction

A Python client for interacting with the Frequenz Reporting API to efficiently retrieve metric and state data from microgrids.

Who should use this? This client is for developers building applications on top of Frequenz's platform who need structured access to historical component or sensor data via Python or CLI.

Supported Platforms

The following platforms are officially supported (tested):

• Python: 3.11
• Operating System: Ubuntu Linux 20.04
• Architectures: amd64, arm64

Contributing

If you want to know how to build this project and contribute to it, please check out the Contributing Guide.

Usage

Please also refer to source of the CLI tool for a practical example of how to use the client.

Installation

pip install frequenz-client-reporting

Initialize the client

To use the Reporting API client, you need to initialize it with the server URL and authentication credentials. The server URL should point to your Frequenz Reporting API instance, and you will need an authentication key and a signing secret. See this documentation for further details.

Security Note Always keep your authentication key and signing secret secure. Do not hard-code them in your source code or share them publicly.

from datetime import datetime, timedelta
import os

from frequenz.client.common.metric import Metric
from frequenz.client.reporting import ReportingApiClient

# Change server address
SERVER_URL = "grpc://replace-this-with-your-server-url:port"
AUTH_KEY = os.environ['REPORTING_API_AUTH_KEY'].strip()
# It is recommended to use a proper secret store to get the secret
# For local development, make sure not to leave it in the shell history
SIGN_SECRET= os.environ['REPORTING_API_SIGN_SECRET'].strip()
client = ReportingApiClient(server_url=SERVER_URL, auth_key=AUTH_KEY, sign_secret=SIGN_SECRET)

Query metrics for a single microgrid and component

This method supports:

• Selecting specific microgrid_id and component_id.
• Choosing one or more metrics to retrieve. Available metrics are listed here.
• Defining a time range with start_time and end_time.
• Optional downsampling using resampling_period (e.g., timedelta(minutes=15)).

# Asynchronously collect metric data samples into a list
data = [
    sample async for sample in
    client.receive_single_component_data(
        microgrid_id=1,  # ID of the microgrid to query
        component_id=100,  # ID of the specific component to query
        metrics=[  # List of metrics to retrieve
            Metric.AC_ACTIVE_POWER,      # AC active power
            Metric.AC_REACTIVE_POWER,      # AC reactive power
        ],
        start_time=datetime.fromisoformat("2024-05-01T00:00:00"),  # Start of query range (UTC)
        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),    # End of query range (UTC)
        resampling_period=timedelta(seconds=5),  # Optional: downsample data to 5-second intervals
    )
]

Query metrics for a single microgrid and sensor

To query sensor data for a specific microgrid, you can use the following method.

data = [
    sample async for sample in
    client.receive_single_sensor_data(
        microgrid_id=1,
        sensor_id=100,
        metrics=[Metric.SENSOR_IRRADIANCE],
        start_time=datetime.fromisoformat("2024-05-01T00:00:00"),
        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),
        resampling_period=timedelta(seconds=1),
    )
]

Query metrics for multiple microgrids and components

It is possible to query data for multiple microgrids and their components in a single request.

# Set the microgrid ID and the component IDs that belong to the microgrid
# Multiple microgrids and components can be queried at once
microgrid_id1 = 1
component_ids1 = [100, 101, 102]
microgrid_id2 = 2
component_ids2 = [200, 201, 202]
microgrid_components = [
    (microgrid_id1, component_ids1),
    (microgrid_id2, component_ids2),
]

data = [
    sample async for sample in
    client.receive_microgrid_components_data(
        microgrid_components=microgrid_components,
        metrics=[Metric.AC_ACTIVE_POWER, Metric.AC_REACTIVE_POWER],
        start_time=datetime.fromisoformat("2024-05-01T00:00:00"),
        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),
        resampling_period=timedelta(seconds=1),
        include_states=False, # Set to True to include state data
        include_bounds=False, # Set to True to include metric bounds data
    )
]

Query metrics for multiple microgrids and sensors

Similar to the previous example, you can query multiple microgrids and their sensors in a single request.

# Set the microgrid ID and the sensor IDs that belong to the microgrid
# Multiple microgrids and sensors can be queried at once
microgrid_id1 = 1
sensor_ids1 = [100, 101, 102]
microgrid_id2 = 2
sensor_ids2 = [200, 201, 202]
microgrid_sensors = [
    (microgrid_id1, sensor_ids1),
    (microgrid_id2, sensor_ids2),
]

data = [
    sample async for sample in
    client.receive_microgrid_sensors_data(
        microgrid_sensors=microgrid_sensors,
        metrics=[Metric.SENSOR_IRRADIANCE],
        start_time=datetime.fromisoformat("2024-05-01T00:00:00"),
        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),
        resampling_period=timedelta(seconds=1),
        include_states=False, # Set to True to include state data
    )
]

Usage of formulas

Formulas can be used to calculate a metric aggregated over multiple components or sensors. Note that this endpoint must be used with a resampling_period. Details on the formula syntax can be found here.

# Example formula to sum the values of two components.
formula = "#1 + #2"
data = [
    sample async for sample in
    client.receive_aggregated_data(
        microgrid_id=microgrid_id,
        metric=Metric.AC_ACTIVE_POWER,
        aggregation_formula=formula,
        start_time=datetime.fromisoformat("2024-05-01T00:00:00"),
        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),
        resampling_period=resampling_period,
    )
]

Optionally convert the data to a pandas DataFrame

For easier data manipulation and analysis, you can convert the collected data into a pandas DataFrame.

import pandas as pd
df = pd.DataFrame(data)
print(df)

Plotting data with matplotlib

pip install matplotlib

Using the data variable from any of the examples above:

import matplotlib.pyplot as plt
import matplotlib.dates as mdates

timestamps = [s.timestamp for s in data]
values = [s.value for s in data]

fig, ax = plt.subplots(figsize=(14, 5))
ax.plot(timestamps, values)

# Optional: customize the plot
ax.set_title("AC Active Power")
ax.set_ylabel("Power (W)")
ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M"))
ax.grid(True)
fig.tight_layout()

plt.show()

Command line client tool

The package contains a command-line tool that can be used to request microgrid component data from the reporting API.

reporting-cli \
    --url localhost:4711 \
    --auth_key=$AUTH_KEY
    --sign_secret=$SIGN_SECRET
    --mid 42 \
    --cid 23 \
    --metrics AC_ACTIVE_POWER AC_REACTIVE_POWER \
    --start 2024-05-01T00:00:00 \
    --end 2024-05-02T00:00:00 \
    --format csv \
    --states \
    --bounds

In addition to the default CSV format, individual samples can also be output using the --format iter option.