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

Exact 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:
Return type:

PVGISResponse

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

save(path)[source]#

Save native bytes and a neighboring .provenance.json manifest.

Parameters:

path (Path)

Return type:

None

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:

PVGISResponse

class energy_data_retrieval.sources.pvgis.client.PVGISClient(http, version='5.3')[source]#

Bases: object

All seven PVGIS 5 endpoints; explicit version defaults to 5.3.

Use native parameter names through request or the named methods. Optional None values 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:

PVGISResponse

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:

PVGISResponse

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:

PVGISResponse

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:

PVGISResponse

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:

PVGISResponse

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:

PVGISResponse

typical_year(latitude, longitude, **parameters)[source]#

tmy: composite meteorological year and source-month selection metadata.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

horizon(latitude, longitude, **parameters)[source]#

printhorizon: native horizon and solar profiles; inspect azimuth convention.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

class energy_data_retrieval.sources.pvgis.client.PVGIS6Client(http)[source]#

Bases: object

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

PVGISResponse

performance(latitude, longitude, **parameters)[source]#

PV performance and energy summaries.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

multiple_surface_performance(latitude, longitude, **parameters)[source]#

Performance for multiple PV surfaces.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

power(latitude, longitude, **parameters)[source]#

PV power, irradiance and meteorological time series.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

multiple_surface_power(latitude, longitude, **parameters)[source]#

PV power time series for multiple surfaces.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

optimize_surface(latitude, longitude, **parameters)[source]#

Optimal surface orientation and tilt.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

solar_position(latitude, longitude, **parameters)[source]#

Solar geometry time series and optional horizon shading.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

typical_year(latitude, longitude, **parameters)[source]#

Composite meteorological year with month-selection metadata.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

degree_days(latitude, longitude, **parameters)[source]#

Heating/cooling degree days with explicit temperature thresholds.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

horizon(latitude, longitude, **parameters)[source]#

Horizon heights; default output angles are radians.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

elevation(latitude, longitude, **parameters)[source]#

Digital terrain elevation in metres.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

available_sources(latitude, longitude, **parameters)[source]#

Irradiance datasets covering this location.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

location_in_source(latitude, longitude, **parameters)[source]#

Test location coverage of an explicitly selected source.

Parameters:
  • latitude (float)

  • longitude (float)

  • parameters (Any)

Return type:

PVGISResponse

coverage_layers()[source]#

List available coverage layers.

Return type:

PVGISResponse

coverage_map()[source]#

Retrieve the native interactive coverage HTML.

Return type:

PVGISResponse

citation()[source]#

Retrieve provider citation metadata.

Return type:

PVGISResponse

publications()[source]#

Retrieve provider bibliography.

Return type:

PVGISResponse

conventions()[source]#

Retrieve coordinate, time and physical conventions.

Return type:

PVGISResponse

license()[source]#

Retrieve provider licensing metadata.

Return type:

PVGISResponse

features()[source]#

Retrieve the current service capability description.

Return type:

PVGISResponse

coverage_layer(name)[source]#

Retrieve a named coverage layer as native GeoJSON.

Parameters:

name (str)

Return type:

PVGISResponse