energy_data_retrieval.sources.pvgis.client#
Complete, versioned PVGIS 5 and 6 API access with unmodified provider outputs.
PVGIS outputs are modelled resource and PV estimates, not measured plant data. Coordinates are decimal degrees. PVGIS 5 aspect uses south=0, west=90; PVGIS 6 surface orientation uses north=0, east=90. Read returned metadata for output units, source grids, time zones and model assumptions before combining products.
- energy_data_retrieval.sources.pvgis.client.endpoints(version='6')[source]#
List every supported operation, including GET/POST variants and metadata.
- Parameters:
version (str)
- Return type:
tuple[str, …]
- energy_data_retrieval.sources.pvgis.client.describe_endpoint(endpoint, *, version='6', method='GET')[source]#
Return a fresh copy of accepted native parameters and validation constraints.
The v6 contract is pinned to the source URL/hash and review date packaged with the connector, not fetched on import. Upstream may change independently.
- Parameters:
endpoint (str)
version (str)
method (str)
- Return type:
dict[str, Any]
- class energy_data_retrieval.sources.pvgis.client.PVGISResponse(body, request, content_type, request_id, version)[source]#
Bases:
objectExact response bytes and provenance; JSON metadata and missing values survive.
CSV, EPW, GeoJSON, PNG, ZIP, HTML and BibTeX can be saved without conversion. These public calculation responses are not cached by this connector.
- Parameters:
body (bytes)
request (RequestRecord)
content_type (str)
request_id (str | None)
version (str)
- body: bytes#
- request: RequestRecord#
- content_type: str#
- request_id: str | None#
- version: str#
- classmethod from_http(response, version)[source]#
- Parameters:
response (BytesResponse)
version (str)
- Return type:
- text()[source]#
Decode a UTF-8 native text output, without removing headers or metadata.
- Return type:
str
- json()[source]#
Read the complete JSON payload; reject malformed or nonfinite values.
- Return type:
JSONValue
- table(*path, columns=None)[source]#
Select a native record/column table without inferring timestamps or units.
Example:
response.table('outputs', 'hourly')for PVGIS 5 seriescalc. TMY timestamps belong to different source years; do not sort them into a supposed continuous observed year. Original payload remains available.- Parameters:
path (str)
columns (tuple[str, ...] | None)
- Return type:
DataFrame
- energy_data_retrieval.sources.pvgis.client.load_response(path)[source]#
Read an unmodified saved response after checking its byte count and SHA-256.
The neighboring manifest is written by
PVGISResponse.save. Integrity checks detect accidental changes; they do not authenticate the data provider.- Parameters:
path (Path)
- Return type:
- class energy_data_retrieval.sources.pvgis.client.PVGISClient(http, version='5.3')[source]#
Bases:
objectAll seven PVGIS 5 endpoints; explicit version defaults to 5.3.
Use native parameter names through
requestor the named methods. OptionalNonevalues are omitted. PVGIS chooses its database if none is supplied; availability and vintage must be inspected in the returned metadata.- Parameters:
http (HTTPClient)
version (Literal['5.2', '5.3'])
- http: HTTPClient#
- version: Literal['5.2', '5.3']#
- request(endpoint, **parameters)[source]#
Call a documented endpoint with validated native parameters.
The default output is JSON; outputformat=’csv’/’basic’ preserves native text and outputformat=’epw’ is available for TMY. No key is required.
- Parameters:
endpoint (str)
parameters (Any)
- Return type:
- grid_connected(latitude, longitude, *, peakpower, loss, **parameters)[source]#
PVcalc: rated peakpower in kW and aggregate system loss in percent.
- Parameters:
latitude (float)
longitude (float)
peakpower (float)
loss (float)
parameters (Any)
- Return type:
- off_grid(latitude, longitude, *, peakpower, batterysize, consumptionday, cutoff, **parameters)[source]#
SHScalc: peakpower W, battery Wh, daily demand Wh, cutoff percent.
Optional hourconsumption is 24 nonnegative fractions summing to one, ordered by local standard time, without daylight saving.
- Parameters:
latitude (float)
longitude (float)
peakpower (float)
batterysize (float)
consumptionday (float)
cutoff (float)
parameters (Any)
- Return type:
- monthly_radiation(latitude, longitude, **parameters)[source]#
MRcalc: select at least one native radiation/temperature output flag.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- daily_radiation(latitude, longitude, *, month, **parameters)[source]#
DRcalc: representative daily profiles; month=0 requests all months.
Use
**{'global': True}for the native keyword, or select other outputs such as showtemperatures=True. These are not daily observed time series.- Parameters:
latitude (float)
longitude (float)
month (int)
parameters (Any)
- Return type:
- hourly(latitude, longitude, **parameters)[source]#
seriescalc: hourly irradiance/weather and optional PV output.
pvcalculation=True requires peakpower in kW and loss in percent. Returned P is W; radiation fields are W/m². Preserve source timestamp offsets.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- typical_year(latitude, longitude, **parameters)[source]#
tmy: composite meteorological year and source-month selection metadata.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- class energy_data_retrieval.sources.pvgis.client.PVGIS6Client(http)[source]#
Bases:
objectPVGIS 6 operations from the packaged, reviewed OpenAPI request contract.
Coordinates are always explicit for location-dependent operations. A horizon file selects the corresponding multipart POST variant. Every calculation field then goes into the form body, as required by the current v6 service.
- Parameters:
http (HTTPClient)
- http: HTTPClient#
- request(endpoint, *, parameters=None, horizon_file=None, method=None, **kwargs)[source]#
Call any listed endpoint, preserving its JSON/text/binary response.
Use parameters for programmatic native names, or keyword arguments. Lists use repeated query/form keys, not comma joining (unless the provider explicitly defines a comma-separated string). None is omitted.
- Parameters:
endpoint (str)
parameters (Mapping[str, Any] | None)
horizon_file (Path | None)
method (Literal['GET', 'POST'] | None)
kwargs (Any)
- Return type:
- performance(latitude, longitude, **parameters)[source]#
PV performance and energy summaries.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- multiple_surface_performance(latitude, longitude, **parameters)[source]#
Performance for multiple PV surfaces.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- power(latitude, longitude, **parameters)[source]#
PV power, irradiance and meteorological time series.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- multiple_surface_power(latitude, longitude, **parameters)[source]#
PV power time series for multiple surfaces.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- optimize_surface(latitude, longitude, **parameters)[source]#
Optimal surface orientation and tilt.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- solar_position(latitude, longitude, **parameters)[source]#
Solar geometry time series and optional horizon shading.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- typical_year(latitude, longitude, **parameters)[source]#
Composite meteorological year with month-selection metadata.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- degree_days(latitude, longitude, **parameters)[source]#
Heating/cooling degree days with explicit temperature thresholds.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- horizon(latitude, longitude, **parameters)[source]#
Horizon heights; default output angles are radians.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- elevation(latitude, longitude, **parameters)[source]#
Digital terrain elevation in metres.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- available_sources(latitude, longitude, **parameters)[source]#
Irradiance datasets covering this location.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type:
- location_in_source(latitude, longitude, **parameters)[source]#
Test location coverage of an explicitly selected source.
- Parameters:
latitude (float)
longitude (float)
parameters (Any)
- Return type: