energy_api_loader

energy_api_loader

Energy API Loader

Load timeseries data from energy data REST APIs and normalize into the standard ts_shape DataFrame schema (systime, uuid, value_double, is_delta).

Classes: - EnergyAPILoader: Fetch energy data from REST APIs and return DataFrames.

EnergyAPILoader

EnergyAPILoader(
    base_url: str,
    *,
    headers: Optional[Dict[str, str]] = None,
    timeout: int = 30
)

Load energy timeseries data from REST APIs.

Fetches JSON data from energy REST endpoints and normalises the response into the standard ts_shape DataFrame columns.

Example usage::

loader = EnergyAPILoader(
    base_url="https://api.energy-provider.example/v1",
    headers={"Authorization": "Bearer <token>"},
)

# Fetch as DataFrame
df = loader.fetch_data_as_dataframe(
    endpoint="/meters/readings",
    params={"meter_id": "M-001", "start": "2024-01-01", "end": "2024-01-02"},
    time_key="timestamp",
    value_key="value",
    uuid_value="meter:M-001",
)

Initialise the loader.

Parameters:

Name	Type	Description	Default
base_url	str	Root URL of the energy API (no trailing slash).	required
headers	Optional[Dict[str, str]]	Optional HTTP headers (e.g. auth tokens).	None
timeout	int	Request timeout in seconds.	30

fetch_data_as_dataframe

fetch_data_as_dataframe(
    endpoint: str,
    *,
    params: Optional[Dict[str, Any]] = None,
    time_key: str = "timestamp",
    value_key: str = "value",
    uuid_value: str = "energy:default",
    data_root: Optional[str] = None
) -> pd.DataFrame

Fetch energy data from a REST endpoint and return a DataFrame.

Parameters:

Name	Type	Description	Default
endpoint	str	API endpoint path (e.g. /meters/readings).	required
params	Optional[Dict[str, Any]]	Query parameters forwarded to requests.get.	None
time_key	str	JSON key containing the timestamp.	'timestamp'
value_key	str	JSON key containing the numeric reading.	'value'
uuid_value	str	UUID string to assign to every row.	'energy:default'
data_root	Optional[str]	Optional key in the JSON response that contains the list of records (e.g. "data" or "readings"). When None the response is expected to be a list.	None

Returns:

Type	Description
DataFrame	DataFrame with columns: systime, uuid, value_double, is_delta.

fetch_multiple_meters

fetch_multiple_meters(
    endpoint: str,
    meter_ids: List[str],
    *,
    meter_param: str = "meter_id",
    params: Optional[Dict[str, Any]] = None,
    time_key: str = "timestamp",
    value_key: str = "value",
    data_root: Optional[str] = None
) -> pd.DataFrame

Fetch data for several meters and combine into one DataFrame.

Each meter receives its own uuid equal to "energy:<meter_id>".

Parameters:

Name	Type	Description	Default
endpoint	str	API endpoint path.	required
meter_ids	List[str]	List of meter identifiers.	required
meter_param	str	Query-parameter name used to select a meter.	'meter_id'
params	Optional[Dict[str, Any]]	Additional query parameters (shared across calls).	None
time_key	str	JSON key for timestamp.	'timestamp'
value_key	str	JSON key for value.	'value'
data_root	Optional[str]	JSON key wrapping the record list.	None

Returns:

Type	Description
DataFrame	Combined DataFrame sorted by systime.