pvgis-api 1.0.0

A clean and intuitive Python library for making API calls to the Photovoltaic Geographical Information System (PVGIS)

PVGIS API - Python Client Library

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:

pip install pvgis-api

For development:

pip install pvgis-api[dev]

Quick Start

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

# 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

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

# 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

# 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:

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:

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 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:

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:

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

# 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

# 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 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