https://github.com/frequenz-floss/frequenz-client-reporting-python
A python client for the Frequenz Reporting API
https://github.com/frequenz-floss/frequenz-client-reporting-python
Last synced: about 1 year ago
JSON representation
A python client for the Frequenz Reporting API
- Host: GitHub
- URL: https://github.com/frequenz-floss/frequenz-client-reporting-python
- Owner: frequenz-floss
- License: mit
- Created: 2024-03-15T12:05:55.000Z (about 2 years ago)
- Default Branch: v0.x.x
- Last Pushed: 2025-04-04T09:11:23.000Z (about 1 year ago)
- Last Synced: 2025-04-04T10:24:22.165Z (about 1 year ago)
- Language: Python
- Size: 1.8 MB
- Stars: 0
- Watchers: 4
- Forks: 5
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Frequenz Reporting API Client
[](https://github.com/frequenz-floss/frequenz-client-reporting-python/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-client-reporting/)
[](https://frequenz-floss.github.io/frequenz-client-reporting-python/)
## Introduction
Reporting API client for Python
## 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](CONTRIBUTING.md).
## Usage
Please also refer to [examples](https://github.com/frequenz-floss/frequenz-client-reporting-python/tree/HEAD/examples) for more detailed usage.
### Installation
```bash
# Choose the version you want to install
VERSION=0.12.0
pip install frequenz-client-reporting==$VERSION
```
### Initialize the client
```python
from datetime import datetime, timedelta
from frequenz.client.common.metric import Metric
from frequenz.client.reporting import ReportingApiClient
# Change server address if needed
SERVER_URL = "grpc://reporting.api.frequenz.com:443"
API_KEY = open('api_key.txt').read().strip()
client = ReportingApiClient(server_url=SERVER_URL, key=API_KEY)
```
Besides the `microgrid_id`, `component_id`s, `metrics`, start, and end time,
you can also set the sampling period for resampling using the `resampling_period`
parameter. For example, to resample data every 15 minutes, use
`resampling_period=timedelta(minutes=15)`.
### Query metrics for a single microgrid and component:
```python
data = [
sample async for sample in
client.list_single_component_data(
microgrid_id=1,
component_id=100,
metrics=[Metric.AC_ACTIVE_POWER, Metric.AC_REACTIVE_POWER],
start_dt=datetime.fromisoformat("2024-05-01T00:00:00"),
end_dt=datetime.fromisoformat("2024-05-02T00:00:00"),
resampling_period=timedelta(seconds=1),
)
]
```
### Query metrics for multiple microgrids and components
```python
# 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.list_microgrid_components_data(
microgrid_components=microgrid_components,
metrics=[Metric.AC_ACTIVE_POWER, Metric.AC_REACTIVE_POWER],
start_dt=datetime.fromisoformat("2024-05-01T00:00:00"),
end_dt=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
)
]
```
### Optionally convert the data to a pandas DataFrame
```python
import pandas as pd
df = pd.DataFrame(data)
print(df)
```
## Command line client tool
The package contains a command-line tool that can be used to request data from the reporting API.
```bash
reporting-cli \
--url localhost:4711 \
--key=$(