Client API Reference

The EliaClient class is the main interface for accessing the Elia OpenData API.

Client for interacting with the Elia Open Data Portal API.

This client provides a simple interface to access the Elia OpenData API records endpoint. It handles authentication, request formatting, and error handling for dataset queries.

The client supports various query parameters including filtering, pagination, and sorting options as provided by the Elia OpenData API.

Attributes:

Name	Type	Description
BASE_URL	str	The base URL for the Elia OpenData API.
api_key	Optional[str]	API key for authenticated requests.
timeout	int	Request timeout in seconds.

Example

Basic usage:

client = EliaClient()
data = client.get_records("ods032", limit=100)

Parameters:

Name	Type	Description	Default
timeout	int	Request timeout in seconds. Defaults to 30 seconds. Increase this value for large dataset queries.	30

export(dataset_id: str, limit: Optional[int] = None, where: Optional[str] = None, export_format: str = 'json', **kwargs: Any) -> Any

Export dataset records in a specific format.

This method uses the Elia OpenData API export endpoint to download complete dataset records in various formats (JSON, CSV, or Parquet). Unlike get_records, this endpoint is optimized for bulk data export.

Parameters:

Name	Type	Description	Default
dataset_id	str	The unique identifier for the dataset to export. Examples include "ods032" for PV production data or "ods001" for total load data.	required
limit	Optional[int]	Maximum number of records to export. If None, exports all available records in the dataset.	None
where	Optional[str]	Filter expression in OData format to limit results. Examples: "datetime>'2023-01-01'" or "value>100".	None
export_format	str	The format for the exported data. Supported formats are "json", "csv", and "parquet". Defaults to "json".	'json'
**kwargs	Any	Additional parameters supported by the export endpoint. Common options include: - lang (str): Language for labels, defaults to 'en' - timezone (str): Timezone for datetime fields, defaults to 'UTC' - use_labels (str): Whether to use human-readable labels, defaults to 'false' - compressed (str): Whether to compress the output, defaults to 'false'	{}

Returns:

Type	Description
Any	The exported data in the requested format:
Any	For "json": Dict containing the parsed JSON response
Any	For "csv": str containing the CSV data
Any	For "parquet": bytes containing the Parquet file content

Raises:

Type	Description
ValueError	If an unsupported export format is specified.
APIError	If the API request fails due to server error, invalid dataset ID, or malformed query parameters.
AuthError	If authentication is required but invalid/missing API key is provided.
RateLimitError	If API rate limits are exceeded.
ConnectionError	If network connection fails or times out.

Example

Basic JSON export:

client = EliaClient()
data = client.export("ods032", limit=1000)

CSV export with filtering:

csv_data = client.export(
    "ods001",
    where="datetime>='2023-01-01'",
    export_format="csv",
    use_labels="true"
)

Parquet export:

parquet_data = client.export(
    "ods032",
    export_format="parquet",
    compressed="true"
)

get_records(dataset_id: str, limit: Optional[int] = None, offset: Optional[int] = None, where: Optional[str] = None, **kwargs) -> List[Dict[str, Any]]

Get records from a specific dataset.

This method queries the Elia OpenData API records endpoint to retrieve dataset records with optional filtering and pagination.

Parameters:

Name	Type	Description	Default
dataset_id	str	The unique identifier for the dataset to query. Examples include "ods032" for PV production data or "ods001" for total load data.	required
limit	Optional[int]	Maximum number of records to return in a single request. If None, the API default limit applies (typically 10). Maximum value is usually 10000 per request.	None
offset	Optional[int]	Number of records to skip before starting to return results. Useful for pagination. Defaults to 0 if not specified.	None
where	Optional[str]	Filter expression in OData format to limit results. Examples: "datetime>'2023-01-01'" or "value>100".	None
**kwargs		Additional query parameters supported by the API. Common options include 'order_by', 'select', 'group_by'.	{}

Returns:

Type	Description
List[Dict[str, Any]]	A list of records

Raises:

Type	Description
APIError	If the API request fails due to server error, invalid dataset ID, or malformed query parameters.
AuthError	If authentication is required but invalid/missing API key is provided.
RateLimitError	If API rate limits are exceeded.
ConnectionError	If network connection fails or times out.

Example

Basic usage:

client = EliaClient()
data = client.get_records("ods032", limit=100)

With filtering:

filtered_data = client.get_records(
    "ods001",
    where="datetime>='2023-01-01' AND datetime<'2023-02-01'",
    limit=1000,
    order_by="datetime"
)

Pagination:

page1 = client.get_records("ods032", limit=50, offset=0)
page2 = client.get_records("ods032", limit=50, offset=50)