pvgis-api 1.0.0
A clean and intuitive Python library for making API calls to the Photovoltaic Geographical Information System (PVGIS)
License: MIT
Requires Python: >=3.7
Keywords: pvgis, photovoltaic, solar, pv, renewable-energy, solar-energy, api-client, solar-radiation, energy-calculation

# PVGIS API - Python Client Library

[![PyPI version](https://badge.fury.io/py/pvgis-api.svg)](https://badge.fury.io/py/pvgis-api)
[![Python Versions](https://img.shields.io/pypi/pyversions/pvgis-api.svg)](https://pypi.org/project/pvgis-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A clean and intuitive Python library for making API calls to the **Photovoltaic Geographical Information System (PVGIS)**.

PVGIS is a free web application developed by the European Commission that provides solar radiation and PV system performance data for any location in the world. This library provides a Pythonic interface to all PVGIS API endpoints.

## Features

- **Simple & Intuitive API** - Clean, well-documented methods for all PVGIS endpoints
- **Type Hints** - Full type annotations for better IDE support and code quality
- **Comprehensive Coverage** - Support for all PVGIS v5.3 API endpoints
- **Flexible Output** - JSON, CSV, or EPW format support
- **Error Handling** - Graceful handling of API errors and rate limiting
- **Zero Configuration** - Works out of the box with sensible defaults

## Installation

Install using pip:

```bash
pip install pvgis-api
```

For development:

```bash
pip install pvgis-api[dev]
```

## Quick Start

```python
from pvgis_api import PVGISClient, RadiationDatabase

# Create a client
client = PVGISClient()

# Calculate PV system performance
result = client.pv_calculation(
    lat=45.0,
    lon=8.0,
    peakpower=1.0,    # 1 kWp system
    loss=14,          # 14% system losses
    angle=35,         # 35° tilt
    aspect=0,         # South-facing
)

# Get results
print(f"Annual Production: {result['outputs']['totals']['fixed']['E_y']:.2f} kWh/year")
print(f"Monthly Average: {result['outputs']['totals']['fixed']['E_m']:.2f} kWh/month")
```

## API Methods

### Grid-Connected PV Systems

```python
# Basic PV calculation
result = client.pv_calculation(
    lat=45.0, lon=8.0,
    peakpower=5.0,
    loss=14,
    angle=35,
    aspect=0
)

# Calculate optimal tilt angle
result = client.pv_calculation(
    lat=45.0, lon=8.0,
    peakpower=5.0,
    loss=14,
    optimal_inclination=True
)

# Two-axis tracking system
from pvgis_api import TrackingType

result = client.pv_calculation(
    lat=45.0, lon=8.0,
    peakpower=10.0,
    loss=14,
    tracking_type=TrackingType.TWO_AXIS
)
```

### Off-Grid PV Systems

```python
result = client.off_grid_calculation(
    lat=35.0, lon=25.0,
    peakpower=3000,        # Watts
    battery_size=10000,    # Wh
    consumption_day=5000,  # Wh/day
    cutoff=20,            # % minimum battery charge
    angle=30,
    aspect=0
)
```

### Solar Radiation Data

```python
# Monthly radiation
result = client.monthly_radiation(
    lat=45.0, lon=8.0,
    horizontal=True
)

# Daily radiation profile
result = client.daily_radiation(
    lat=45.0, lon=8.0,
    month=7,  # July
    global_irradiance=True,
    show_temperatures=True
)

# Hourly time series
result = client.hourly_radiation(
    lat=45.0, lon=8.0,
    year=2020,
    pv_calculation=True,
    peakpower=4.0,
    loss=14
)

# Typical Meteorological Year (TMY)
result = client.typical_meteorological_year(
    lat=45.0, lon=8.0,
    startyear=2005,
    endyear=2020
)
```

### Horizon Profile

```python
# Get terrain horizon data
result = client.horizon_profile(lat=46.5, lon=8.0)

# Use custom horizon in calculations
horizon_heights = [h['H_hor'] for h in result['outputs']['horizon_profile']]

pv_result = client.pv_calculation(
    lat=46.5, lon=8.0,
    peakpower=5.0,
    loss=14,
    user_horizon=horizon_heights
)
```

## Output Formats

Choose between JSON, CSV, or EPW formats:

```python
from pvgis_api import OutputFormat

# JSON (default)
result = client.monthly_radiation(
    lat=45.0, lon=8.0,
    horizontal=True,
    output_format=OutputFormat.JSON
)

# CSV format
result = client.monthly_radiation(
    lat=45.0, lon=8.0,
    horizontal=True,
    output_format=OutputFormat.CSV
)

# Save CSV to file
with open('radiation.csv', 'w') as f:
    f.write(result['data'])
```

## Radiation Databases

PVGIS offers multiple radiation databases:

```python
from pvgis_api import RadiationDatabase

# SARAH3 - Europe, Africa, parts of Asia (2005-2020)
result = client.pv_calculation(
    lat=45.0, lon=8.0,
    peakpower=1.0, loss=14,
    radiation_db=RadiationDatabase.SARAH3
)

# ERA5 - Global coverage (2005-2020)
result = client.pv_calculation(
    lat=45.0, lon=8.0,
    peakpower=1.0, loss=14,
    radiation_db=RadiationDatabase.ERA5
)

# NSRDB - Americas (1998-2020)
result = client.pv_calculation(
    lat=40.0, lon=-100.0,
    peakpower=1.0, loss=14,
    radiation_db=RadiationDatabase.NSRDB
)
```

## Examples

See the [examples.py](examples.py) file for comprehensive examples including:

- Basic PV system calculations
- Optimal angle calculations
- Tracking systems
- Off-grid system sizing
- Monthly, daily, and hourly radiation data
- TMY data retrieval
- Horizon profiles
- Custom horizons
- Database comparisons
- CSV exports

Run examples:

```bash
python examples.py
```

## API Reference

### PVGISClient

The main client class for interacting with the PVGIS API.

#### Methods

- **`pv_calculation()`** - Calculate grid-connected PV system performance
- **`off_grid_calculation()`** - Calculate off-grid system performance
- **`monthly_radiation()`** - Get monthly radiation values
- **`daily_radiation()`** - Get daily radiation profiles
- **`hourly_radiation()`** - Get hourly radiation time series
- **`typical_meteorological_year()`** - Get TMY data
- **`horizon_profile()`** - Get terrain horizon data
- **`get_location_info()`** - Get comprehensive location information

### Enums

- **`RadiationDatabase`** - Available radiation databases (SARAH3, ERA5, NSRDB)
- **`OutputFormat`** - Output format options (JSON, CSV, BASIC, EPW)
- **`TrackingType`** - PV tracking system types (FIXED, HORIZONTAL_AXIS, TWO_AXIS, VERTICAL_AXIS, INCLINED_AXIS)

## Error Handling

The library handles common API errors:

```python
try:
    result = client.pv_calculation(lat=45.0, lon=8.0, peakpower=1.0, loss=14)
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 529:
        print("PVGIS API is overloaded. Please retry after a few seconds.")
    else:
        print(f"HTTP error occurred: {e}")
except requests.exceptions.RequestException as e:
    print(f"Connection error occurred: {e}")
```

## Requirements

- Python 3.7+
- requests >= 2.25.0

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Development Setup

```bash
# Clone the repository
git clone https://github.com/dajakus/pvgis-api.git
cd pvgis-api

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=pvgis_api --cov-report=html

# Format code
black pvgis_api tests

# Type checking
mypy pvgis_api
```

## Testing

```bash
# Run all tests
pytest

# Run with coverage report
pytest --cov=pvgis_api --cov-report=term-missing

# Run specific test file
pytest tests/test_client.py
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- **PVGIS** - Photovoltaic Geographical Information System developed by the European Commission's Joint Research Centre
- Official PVGIS Documentation: https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/

## Disclaimer

This is an unofficial library and is not affiliated with or endorsed by the European Commission or the PVGIS team.

## Links

- **PyPI**: https://pypi.org/project/pvgis-api/
- **GitHub**: https://github.com/dajakus/pvgis-api
- **PVGIS Official Site**: https://re.jrc.ec.europa.eu/pvg_tools/en/
- **PVGIS API Documentation**: https://joint-research-centre.ec.europa.eu/pvgis-online-tool/getting-started-pvgis/api-non-interactive-service_en

## Changelog

### 1.0.0 (2025-01-XX)

- Initial release
- Support for all PVGIS v5.3 API endpoints
- Full type hints and documentation
- Comprehensive test suite
- Examples for all major use cases