SolarEdge Client (Monitoring API)

A Python client for the SolarEdge Monitoring API, providing both synchronous and asynchronous interfaces for accessing solar energy data.

See https://www.solaredge.com/sites/default/files/se_monitoring_api.pdf

Table of Contents

• Features
• Installation
• Quick Start
  • Synchronous Usage
  • Asynchronous Usage
  • Error Handling
• Rate Limiting & Best Practices
• Development
• API Documentation

Features

• Sync & Async Support: Choose between MonitoringClient (sync) and AsyncMonitoringClient (async)
• Current API Coverage: Every monitoring endpoint SolarEdge still serves
• Type Hints: Complete type annotations for better IDE support
• Rate Limiting: Built-in awareness of API limits (3 concurrent requests)
• Context Manager Support: Automatic resource cleanup

Installation

pip install solaredge
poetry add solaredge
uv add solaredge

Quick Start

Synchronous Usage

from solaredge import MonitoringClient

# Basic usage
client = MonitoringClient(api_key="YOUR_API_KEY")
sites = client.get_site_list()
client.close()

# Context manager (recommended)
with MonitoringClient("YOUR_API_KEY") as client:
    site_details = []
    sites = client.get_site_list()
    for site in sites["sites"]["list"]:
        site_details.append(
            client.get_site_details(
                site_id=site["id"],
            )
        )

Asynchronous Usage

import asyncio
from solaredge import AsyncMonitoringClient


async def main():
    async with AsyncMonitoringClient(api_key="YOUR_API_KEY") as client:
        sites = await client.get_site_list()

        # Concurrent requests (respecting 3 concurrent limit)
        tasks = []
        for site in sites["sites"]["list"]:
            task = client.get_site_details(site_id=site["id"])
            tasks.append(task)

        site_details = await asyncio.gather(*tasks)


asyncio.run(main())

Error Handling

Every failure raises a SolarEdgeError subclass, so you never need to import httpx to handle one. The originating httpx exception is preserved as __cause__ if you want the transport-level detail.

from solaredge import (
    MonitoringClient,
    SolarEdgeAuthError,
    SolarEdgeRateLimitError,
    SolarEdgeError,
)

with MonitoringClient("YOUR_API_KEY") as client:
    try:
        sites = client.get_site_list()
    except SolarEdgeAuthError:
        ...  # bad or unauthorized API key
    except SolarEdgeRateLimitError as exc:
        ...  # exc.status_code, exc.response_body
    except SolarEdgeError:
        ...  # anything else this library raises

The hierarchy:

Exception	Raised when
SolarEdgeError	Base class for everything below
SolarEdgeValidationError	Arguments rejected locally, before any request. Also a ValueError
SolarEdgeAPIError	The API returned an error status
SolarEdgeAuthError	401 / 403 — key missing, invalid or not permitted
SolarEdgeNotFoundError	404 — no such site, equipment or endpoint
SolarEdgeRateLimitError	429 — quota or concurrency limit exceeded
SolarEdgeServerError	5xx — the API failed to handle a valid request
SolarEdgeResponseError	Success status, but the body could not be parsed

SolarEdgeAPIError and its subclasses carry status_code, response_body and url.

Note on API keys in URLs. SolarEdge authenticates via an api_key query parameter, so the key appears in every request URL. This library redacts it from exception messages, but it will still be present in anything else that records raw URLs — proxy logs, HTTP debug output, httpx event hooks. Take care before sharing those.

Rate Limiting & Best Practices

• Daily limit: 300 requests per API Key and per site ID
• Concurrency: Maximum 3 concurrent requests from same IP
• Bulk operations: Up to 100 site IDs per bulk request

for more information see page 8 of the api documentation

Development

# Install development dependencies
uv sync
uv run prek install -t commit-msg

# Commiting changes
uv run cz c

API Documentation

For detailed API documentation including all parameters and response formats, see:

• SolarEdge Monitoring API Documentation
• Official API Reference