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.
- 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
Install using pip:
pip install pvgis-apifrom 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")# 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
)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
)# 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
)# 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
)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'])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
)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.pyThe main client class for interacting with the PVGIS API.
pv_calculation()- Calculate grid-connected PV system performanceoff_grid_calculation()- Calculate off-grid system performancemonthly_radiation()- Get monthly radiation valuesdaily_radiation()- Get daily radiation profileshourly_radiation()- Get hourly radiation time seriestypical_meteorological_year()- Get TMY datahorizon_profile()- Get terrain horizon dataget_location_info()- Get comprehensive location information
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)
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}")- Python 3.7+
- requests >= 2.25.0
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
# 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# Run all tests
pytest
# Run with coverage report
pytest --cov=pvgis_api --cov-report=term-missing
# Run specific test file
pytest tests/test_client.pyThis project is licensed under the MIT License - see the LICENSE file for details.
- 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/
This is an unofficial library and is not affiliated with or endorsed by the European Commission or the PVGIS team.
- 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
- Initial release
- Support for all PVGIS v5.3 API endpoints
- Full type hints and documentation
- Comprehensive test suite
- Examples for all major use cases