Update README

Author: cwasicki

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
@@ -58,23 +68,37 @@ 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 +117,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 +147,8 @@ data = [
 
 ### Query metrics for multiple microgrids and sensors
 
+Equivalent to the previous example, multiple microgrids and their sensors can be queried 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 +176,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 +186,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 +203,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 the individual samples can also be output using the `--format iter` option.