From 3ea21133253609a2693ce904ff8cedfa5148cc5c Mon Sep 17 00:00:00 2001
From: cwasicki <126617870+cwasicki@users.noreply.github.com>
Date: Tue, 17 Jun 2025 18:48:49 +0200
Subject: [PATCH] Update README

Signed-off-by: cwasicki <126617870+cwasicki@users.noreply.github.com>
---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 40 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 70b3074..7bf2e07 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,11 @@
 
 ## Introduction
 
-Reporting API client for Python
+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
 
@@ -37,6 +41,12 @@ pip install frequenz-client-reporting==$VERSION
 
 ### 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.
+
+> **Security Note**
+> Always keep your authentication key and signing secret secure. Do not hard-code them in your source code or share them publicly.
+
 ```python
 from datetime import datetime, timedelta
 import os
@@ -53,28 +63,36 @@ SIGN_SECRET= os.environ['REPORTING_API_SIGN_SECRET'].strip()
 client = ReportingApiClient(server_url=SERVER_URL, auth_key=AUTH_KEY, sign_secret=SIGN_SECRET)
 ```
 
-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
 
-### 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
+- Defining a time range with `start_time` and `end_time`
+- Optional downsampling using `resampling_period` (e.g., `timedelta(minutes=15)`)
 
 ```python
+# Asynchronously collect metric data samples into a list
 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_time=datetime.fromisoformat("2024-05-01T00:00:00"),
-        end_time=datetime.fromisoformat("2024-05-02T00:00:00"),
-        resampling_period=timedelta(seconds=1),
+        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:
+
+### Query metrics for a single microgrid and sensor
+
+To query sensor data for a specific microgrid, you can use the following method.
 
 ```python
 data = [
@@ -93,6 +111,8 @@ data = [
 
 ### Query metrics for multiple microgrids and components
 
+It is possible to query data for multiple microgrids and their components in a single request.
+
 ```python
 # Set the microgrid ID and the component IDs that belong to the microgrid
 # Multiple microgrids and components can be queried at once
@@ -121,6 +141,8 @@ 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.
+
 ```python
 # Set the microgrid ID and the sensor IDs that belong to the microgrid
 # Multiple microgrids and sensors can be queried at once
@@ -148,6 +170,8 @@ data = [
 
 ### Optionally convert the data to a pandas DataFrame
 
+For easier data manipulation and analysis, you can convert the collected data into a pandas DataFrame.
+
 ```python
 import pandas as pd
 df = pd.DataFrame(data)
@@ -156,8 +180,9 @@ print(df)
 
 ## Command line client tool
 
-The package contains a command-line tool that can be used to request 
+The package contains a command-line tool that can be used to request
 microgrid component data from the reporting API.
+
 ```bash
 reporting-cli \
     --url localhost:4711 \
@@ -172,4 +197,4 @@ reporting-cli \
     --states \
     --bounds
 ```
-In addition to the default CSV format the data can be output as individual samples or in `dict` format.
+In addition to the default CSV format, individual samples can also be output using the `--format iter` option.