pvlib.iotools.get_pvgis_hourly#

pvlib.iotools.get_pvgis_hourly(latitude, longitude, start=None, end=None, raddatabase=None, components=True, surface_tilt=0, surface_azimuth=180, outputformat='json', usehorizon=True, userhorizon=None, pvcalculation=False, peakpower=None, pvtechchoice='crystSi', mountingplace='free', loss=0, trackingtype=0, optimal_surface_tilt=False, optimalangles=False, url='https://re.jrc.ec.europa.eu/api/', map_variables=True, timeout=30)[source]#

Get hourly solar irradiation and modeled PV power output from PVGIS.

PVGIS data is freely available at [1].

Changed in version 0.13.0: The function now returns two items (data,meta). Previous versions of this function returned three elements (data,inputs,meta). The inputs dictionary is now included in meta, which has changed structure to accommodate it.

Parameters:

latitude (float) – In decimal degrees, between -90 and 90, north is positive (ISO 19115)
longitude (float) – In decimal degrees, between -180 and 180, east is positive (ISO 19115)
start (int or datetime like, optional) – First year of the radiation time series. Defaults to first year available.
end (int or datetime like, optional) – Last year of the radiation time series. Defaults to last year available.
raddatabase (str, optional) – Name of radiation database. Options depend on location, see [3].
components (bool, default: True) – Output solar radiation components (beam, diffuse, and reflected). Otherwise only global irradiance is returned.
surface_tilt (float, default: 0) – Tilt angle from horizontal plane. Ignored for two-axis tracking.
surface_azimuth (float, default: 180) –
Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270). This is offset 180 degrees from the convention used by PVGIS. Ignored for tracking systems.

Changed in version 0.10.0: The surface_azimuth parameter now follows the pvlib convention, which is clockwise from north. However, the convention used by the PVGIS website and pvlib<=0.9.5 is offset by 180 degrees.
usehorizon (bool, default: True) – Include effects of horizon
userhorizon (list of float, optional) – Optional user specified elevation of horizon in degrees, at equally spaced azimuth clockwise from north, only valid if usehorizon is true, if usehorizon is true but userhorizon is not specified then PVGIS will calculate the horizon [4]
pvcalculation (bool, default: False) – Return estimate of hourly PV production.
peakpower (float, optional) – Nominal power of PV system in kW. Required if pvcalculation=True.
pvtechchoice ({'crystSi', 'CIS', 'CdTe', 'Unknown'}, default: 'crystSi') – PV technology.
mountingplace ({'free', 'building'}, default: free) – Type of mounting for PV system. Options of ‘free’ for free-standing and ‘building’ for building-integrated.
loss (float, default: 0) – Sum of PV system losses in percent. Required if pvcalculation=True
trackingtype ({0, 1, 2, 3, 4, 5}, default: 0) – Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south.
optimal_surface_tilt (bool, default: False) – Calculate the optimum tilt angle. Ignored for two-axis tracking
optimalangles (bool, default: False) – Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking.
outputformat (str, default: 'json') – Must be in ['json', 'csv']. See PVGIS hourly data documentation [2] for more info.
url (str, default: pvlib.iotools.pvgis.URL) – Base url of PVGIS API. seriescalc is appended to get hourly data endpoint. Note, a specific PVGIS version can be specified, e.g., https://re.jrc.ec.europa.eu/api/v5_2/
map_variables (bool, default: True) – When true, renames columns of the Dataframe to pvlib variable names where applicable. See variable VARIABLE_MAP.
timeout (int, default: 30) – Time in seconds to wait for server response before timeout

Returns:

data (pandas.DataFrame) – Time-series of hourly data, see Notes for fields
metadata (dict) – Dictionary containing metadata

Raises:

requests.HTTPError – If the request response status is HTTP/1.1 400 BAD REQUEST, then the error message in the response will be raised as an exception, otherwise raise whatever HTTP/1.1 error occurred

Hint

PVGIS provides access to a number of different solar radiation datasets, including satellite-based (SARAH, SARAH2, and NSRDB PSM3) and re-analysis products (ERA5). Each data source has a different geographical coverage and time stamp convention, e.g., SARAH and SARAH2 provide instantaneous values, whereas values from ERA5 are averages for the hour.

Warning

The azimuth orientation specified in the output metadata does not correspond to the pvlib convention, but is offset 180 degrees. This is despite the fact that the input parameter surface_tilt has to be specified according to the pvlib convention.

Notes

data includes the following fields:

raw, mapped	Format	Description
Mapped field names are returned when the map_variables argument is True
P†	float	PV system power (W)
G(i), poa_global‡	float	Global irradiance on inclined plane (W/m^2)
Gb(i), poa_direct‡	float	Beam (direct) irradiance on inclined plane (W/m^2)
Gd(i), poa_sky_diffuse‡	float	Diffuse irradiance on inclined plane (W/m^2)
Gr(i), poa_ground_diffuse‡	float	Reflected irradiance on inclined plane (W/m^2)
H_sun, solar_elevation	float	Sun height/elevation (degrees)
T2m, temp_air	float	Air temperature at 2 m (degrees Celsius)
WS10m, wind_speed	float	Wind speed at 10 m (m/s)
Int	int	Solar radiation reconstructed (1/0)

†P (PV system power) is only returned when pvcalculation=True.

‡Gb(i), Gd(i), and Gr(i) are returned when components=True, otherwise the sum of the three components, G(i), is returned.