Metadata-Version: 2.4
Name: salzburgnetz
Version: 0.0.1
Summary: API Client for the Serviceportal of Salzburg Netz GmbH
Author: David Prodinger
License-Expression: MIT
Project-URL: Homepage, https://www.salzburgnetz.at/
Project-URL: Documentation, https://www.salzburgnetz.at/service/serviceportal/programmierschnittstelle.html
Project-URL: Repository, https://github.com/DavidProdinger/py-salzburgnetz
Project-URL: Issues, https://github.com/DavidProdinger/py-salzburgnetz/issues
Keywords: python,api,smartmeter,energy,Salzburg Netz
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Dynamic: license-file

# py-salzburgnetz

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

An asynchronous Python API client for the [Salzburg Netz GmbH](https://www.salzburgnetz.at/) Serviceportal. This library allows you to access smart meter data, including consumption profiles, equipment information, and contract details.

## Important Links
- [Service Portal](https://portal.salzburgnetz.at/)
- [Serviceportal FAQ](https://www.salzburgnetz.at/service/serviceportal.html)
- [Programmierschnittstelle (API) zum automatisierten Abruf von Daten](https://www.salzburgnetz.at/service/serviceportal/programmierschnittstelle.html)
- [API Documentation](./docs/Programmierschnittstelle_Beschreibung_API.pdf) (offline PDF)

## Features

- **Asynchronous**: Built on `aiohttp` for efficient non-blocking I/O.
- **Type-safe**: Uses `Pydantic` models for data validation and IDE autocompletion.
- **Comprehensive**: Supports various endpoints:
    - Load profiles (standard and energy communities)
    - Installation (Anlagen) information
    - Equipment and meter details
    - Partner and outage information
    - Meter readings
    - Contract accounts (Vertragskonto)
- **Flexible Formats**: Supports JSON (default), CSV, and XML response formats.

## Installation

```bash
pip install salzburgnetz
```

*Note: Replace with actual installation command if hosted on PyPI or use `pip install git+https://github.com/DavidProdinger/py-salzburgnetz.git` for GitHub.*

## Usage

You need a **Token** and your **Customer ID** from the Salzburg Netz Serviceportal to use this API.

### Basic Example

```python
import asyncio
from salzburgnetz.api import SalzburgNetzApi

async def main():
    # Authentication details from Salzburg Netz Serviceportal
    TOKEN = "your_api_token"
    CUSTOMER_ID = 12345678

    async with SalzburgNetzApi(token=TOKEN, customer=CUSTOMER_ID) as api:
        # Get all installations
        anlagen = await api.anlage()
        for anlage in anlagen:
            print(f"Anlage: {anlage.Anlage}, Zählpunkt: {anlage.Zählpunkt}")
            
            # Fetch consumption profile for a specific Zählpunkt
            profile = await api.profile(zaehlpunkt=anlage.Zählpunkt)
            for entry in profile:
                print(f"Time: {entry.timestamp}, Value: {entry.Wert} {entry.Einheit}")

if __name__ == "__main__":
    asyncio.run(main())
```

### Advanced Usage

#### Fetching specific formats
You can request data in JSON (parsed to models), CSV, or XML (as strings).

```python
from salzburgnetz.const import ApiFormat

# Returns a string in CSV format
csv_data = await api.profile(zaehlpunkt="...", response_format=ApiFormat.CSV)

# Returns a string in XML format
xml_data = await api.profile(zaehlpunkt="...", response_format=ApiFormat.XML)
```

#### Energy Communities (Energiegemeinschaft)
```python
profile_eg = await api.profile_eg(zaehlpunkt="...")
```

## Data Models

The library maps API responses to Pydantic models:
- `Anlage`: Installation details.
- `Equipment`: Meter and device information.
- `Profile`: Consumption data points with helper properties like `timestamp`.
- `Partner`: Customer profile and outage notifications.
- `Reading`: Historical meter readings.

## Requirements

- Python 3.9+
- `aiohttp`
- `pydantic`

## Development

### Running Tests
Tests require environment variables for authentication:
```bash
export SALZBURGNETZ_TOKEN="your_token"
export SALZBURGNETZ_CUSTOMER="your_customer_id"
export SALZBURGNETZ_ZP1="your_test_zaehlpunkt"
pytest
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This project is not affiliated with, maintained by, or endorsed by Salzburg Netz GmbH. It is an independent community project.
