Source code for pvlib.iotools.pvgis

"""
Get, read, and parse data from `PVGIS <https://ec.europa.eu/jrc/en/pvgis>`_.

For more information, see the following links:
* `Interactive Tools <https://re.jrc.ec.europa.eu/pvg_tools/en/tools.html>`_
* `Data downloads <https://ec.europa.eu/jrc/en/PVGIS/downloads/data>`_
* `User manual docs <https://ec.europa.eu/jrc/en/PVGIS/docs/usermanual>`_

More detailed information about the API for TMY and hourly radiation are here:
* `TMY <https://ec.europa.eu/jrc/en/PVGIS/tools/tmy>`_
* `hourly radiation
  <https://ec.europa.eu/jrc/en/PVGIS/tools/hourly-radiation>`_
* `daily radiation <https://ec.europa.eu/jrc/en/PVGIS/tools/daily-radiation>`_
* `monthly radiation
  <https://ec.europa.eu/jrc/en/PVGIS/tools/monthly-radiation>`_
"""
import io
import json
from pathlib import Path
import requests
import pandas as pd
from pvlib.iotools import read_epw, parse_epw
import warnings
from pvlib._deprecation import pvlibDeprecationWarning

URL = 'https://re.jrc.ec.europa.eu/api/'

# Dictionary mapping PVGIS names to pvlib names
VARIABLE_MAP = {
    'G(h)': 'ghi',
    'Gb(n)': 'dni',
    'Gd(h)': 'dhi',
    'G(i)': 'poa_global',
    'Gb(i)': 'poa_direct',
    'Gd(i)': 'poa_sky_diffuse',
    'Gr(i)': 'poa_ground_diffuse',
    'H_sun': 'solar_elevation',
    'T2m': 'temp_air',
    'RH': 'relative_humidity',
    'SP': 'pressure',
    'WS10m': 'wind_speed',
    'WD10m': 'wind_direction',
}


[docs]def 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=URL, map_variables=True, timeout=30): """Get hourly solar irradiation and modeled PV power output from PVGIS. PVGIS data is freely available at [1]_. 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. .. versionchanged:: 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: :const:`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 :const:`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 inputs : dict Dictionary of the request input parameters 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. See Also -------- pvlib.iotools.read_pvgis_hourly, pvlib.iotools.get_pvgis_tmy Examples -------- >>> # Retrieve two years of irradiance data from PVGIS: >>> data, meta, inputs = pvlib.iotools.get_pvgis_hourly( # doctest: +SKIP >>> latitude=45, longitude=8, start=2015, end=2016) # doctest: +SKIP References ---------- .. [1] `PVGIS <https://ec.europa.eu/jrc/en/pvgis>`_ .. [2] `PVGIS Hourly Radiation <https://ec.europa.eu/jrc/en/PVGIS/tools/hourly-radiation>`_ .. [3] `PVGIS Non-interactive service <https://ec.europa.eu/jrc/en/PVGIS/docs/noninteractive>`_ .. [4] `PVGIS horizon profile tool <https://ec.europa.eu/jrc/en/PVGIS/tools/horizon>`_ """ # noqa: E501 # use requests to format the query string by passing params dictionary params = {'lat': latitude, 'lon': longitude, 'outputformat': outputformat, 'angle': surface_tilt, 'aspect': surface_azimuth-180, 'pvcalculation': int(pvcalculation), 'pvtechchoice': pvtechchoice, 'mountingplace': mountingplace, 'trackingtype': trackingtype, 'components': int(components), 'usehorizon': int(usehorizon), 'optimalangles': int(optimalangles), 'optimalinclination': int(optimal_surface_tilt), 'loss': loss} # pvgis only takes 0 for False, and 1 for True, not strings if userhorizon is not None: params['userhorizon'] = ','.join(str(x) for x in userhorizon) if raddatabase is not None: params['raddatabase'] = raddatabase if start is not None: params['startyear'] = start if isinstance(start, int) else pd.to_datetime(start).year # noqa: E501 if end is not None: params['endyear'] = end if isinstance(end, int) else pd.to_datetime(end).year # noqa: E501 if peakpower is not None: params['peakpower'] = peakpower # The url endpoint for hourly radiation is 'seriescalc' res = requests.get(url + 'seriescalc', params=params, timeout=timeout) # PVGIS returns really well formatted error messages in JSON for HTTP/1.1 # 400 BAD REQUEST so try to return that if possible, otherwise raise the # HTTP/1.1 error caught by requests if not res.ok: try: err_msg = res.json() except Exception: res.raise_for_status() else: raise requests.HTTPError(err_msg['message']) return read_pvgis_hourly(io.StringIO(res.text), pvgis_format=outputformat, map_variables=map_variables)
def _parse_pvgis_hourly_json(src, map_variables): inputs = src['inputs'] metadata = src['meta'] data = pd.DataFrame(src['outputs']['hourly']) data.index = pd.to_datetime(data['time'], format='%Y%m%d:%H%M', utc=True) data = data.drop('time', axis=1) data = data.astype(dtype={'Int': 'int'}) # The 'Int' column to be integer if map_variables: data = data.rename(columns=VARIABLE_MAP) return data, inputs, metadata def _parse_pvgis_hourly_csv(src, map_variables): # The first 4 rows are latitude, longitude, elevation, radiation database inputs = {} # 'Latitude (decimal degrees): 45.000\r\n' inputs['latitude'] = float(src.readline().split(':')[1]) # 'Longitude (decimal degrees): 8.000\r\n' inputs['longitude'] = float(src.readline().split(':')[1]) # Elevation (m): 1389.0\r\n inputs['elevation'] = float(src.readline().split(':')[1]) # 'Radiation database: \tPVGIS-SARAH\r\n' inputs['radiation_database'] = src.readline().split(':')[1].strip() # Parse through the remaining metadata section (the number of lines for # this section depends on the requested parameters) while True: line = src.readline() if line.startswith('time,'): # The data header starts with 'time,' # The last line of the metadata section contains the column names names = line.strip().split(',') break # Only retrieve metadata from non-empty lines elif line.strip() != '': inputs[line.split(':')[0]] = line.split(':')[1].strip() elif line == '': # If end of file is reached raise ValueError('No data section was detected. File has probably ' 'been modified since being downloaded from PVGIS') # Save the entries from the data section to a list, until an empty line is # reached an empty line. The length of the section depends on the request data_lines = [] while True: line = src.readline() if line.strip() == '': break else: data_lines.append(line.strip().split(',')) data = pd.DataFrame(data_lines, columns=names) data.index = pd.to_datetime(data['time'], format='%Y%m%d:%H%M', utc=True) data = data.drop('time', axis=1) if map_variables: data = data.rename(columns=VARIABLE_MAP) # All columns should have the dtype=float, except 'Int' which should be # integer. It is necessary to convert to float, before converting to int data = data.astype(float).astype(dtype={'Int': 'int'}) # Generate metadata dictionary containing description of parameters metadata = {} for line in src.readlines(): if ':' in line: metadata[line.split(':')[0]] = line.split(':')[1].strip() return data, inputs, metadata
[docs]def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True): """Read a PVGIS hourly file. Parameters ---------- filename : str, pathlib.Path, or file-like buffer Name, path, or buffer of hourly data file downloaded from PVGIS. pvgis_format : str, optional Format of PVGIS file or buffer. Equivalent to the ``outputformat`` parameter in the PVGIS API. If ``filename`` is a file and ``pvgis_format`` is not specified then the file extension will be used to determine the PVGIS format to parse. If ``filename`` is a buffer, then ``pvgis_format`` is required and must be in ``['csv', 'json']``. map_variables: bool, default True When true, renames columns of the DataFrame to pvlib variable names where applicable. See variable :const:`VARIABLE_MAP`. Returns ------- data : pandas.DataFrame the time series data inputs : dict the inputs metadata : dict metadata Warning ------- The azimuth orientation specified in the output metadata does not correspond to the pvlib convention, but is offset 180 degrees. Raises ------ ValueError if ``pvgis_format`` is not specified and the file extension is neither ``.csv`` nor ``.json`` or if ``pvgis_format`` is provided as input but isn't in ``['csv', 'json']`` TypeError if ``pvgis_format`` is not specified and ``filename`` is a buffer See Also -------- get_pvgis_hourly, read_pvgis_tmy """ # get the PVGIS outputformat if pvgis_format is None: # get the file extension from suffix, but remove the dot and make sure # it's lower case to compare with csv, or json # NOTE: basic format is not supported for PVGIS Hourly as the data # format does not include a header # NOTE: raises TypeError if filename is a buffer outputformat = Path(filename).suffix[1:].lower() else: outputformat = pvgis_format # parse the pvgis file based on the output format, either 'json' or 'csv' # NOTE: json and csv output formats have parsers defined as private # functions in this module # JSON: use Python built-in json module to convert file contents to a # Python dictionary, and pass the dictionary to the # _parse_pvgis_hourly_json() function from this module if outputformat == 'json': try: src = json.load(filename) except AttributeError: # str/path has no .read() attribute with open(str(filename), 'r') as fbuf: src = json.load(fbuf) return _parse_pvgis_hourly_json(src, map_variables=map_variables) # CSV: use _parse_pvgis_hourly_csv() if outputformat == 'csv': try: pvgis_data = _parse_pvgis_hourly_csv( filename, map_variables=map_variables) except AttributeError: # str/path has no .read() attribute with open(str(filename), 'r') as fbuf: pvgis_data = _parse_pvgis_hourly_csv( fbuf, map_variables=map_variables) return pvgis_data # raise exception if pvgis format isn't in ['csv', 'json'] err_msg = ( "pvgis format '{:s}' was unknown, must be either 'json' or 'csv'")\ .format(outputformat) raise ValueError(err_msg)
[docs]def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True, userhorizon=None, startyear=None, endyear=None, map_variables=True, url=URL, timeout=30): """ Get TMY data from PVGIS. For more information see the PVGIS [1]_ TMY tool documentation [2]_. Parameters ---------- latitude : float Latitude in degrees north longitude : float Longitude in degrees east outputformat : str, default 'json' Must be in ``['csv', 'basic', 'epw', 'json']``. See PVGIS TMY tool documentation [2]_ for more info. 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. If not specified, PVGIS will calculate the horizon [3]_. If specified, requires ``usehorizon=True``. startyear : int, optional first year to calculate TMY endyear : int, optional last year to calculate TMY, must be at least 10 years from first year map_variables: bool, default True When true, renames columns of the Dataframe to pvlib variable names where applicable. See variable :const:`VARIABLE_MAP`. url : str, default: :const:`pvlib.iotools.pvgis.URL` base url of PVGIS API, append ``tmy`` to get TMY endpoint timeout : int, default 30 time in seconds to wait for server response before timeout Returns ------- data : pandas.DataFrame the weather data months_selected : list TMY year for each month, ``None`` for basic and EPW inputs : dict the inputs, ``None`` for basic and EPW metadata : list or dict file metadata, ``None`` for basic Note ---- The PVGIS website uses 10 years of data to generate the TMY, whereas the API accessed by this function defaults to using all available years. This means that the TMY returned by this function may not be identical to the one generated by the website. To replicate the website requests, specify the corresponding 10 year period using ``startyear`` and ``endyear``. Specifying ``endyear`` also avoids the TMY changing when new data becomes available. 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 See Also -------- read_pvgis_tmy References ---------- .. [1] `PVGIS <https://ec.europa.eu/jrc/en/pvgis>`_ .. [2] `PVGIS TMY tool <https://ec.europa.eu/jrc/en/PVGIS/tools/tmy>`_ .. [3] `PVGIS horizon profile tool <https://ec.europa.eu/jrc/en/PVGIS/tools/horizon>`_ """ # use requests to format the query string by passing params dictionary params = {'lat': latitude, 'lon': longitude, 'outputformat': outputformat} # pvgis only likes 0 for False, and 1 for True, not strings, also the # default for usehorizon is already 1 (ie: True), so only set if False if not usehorizon: params['usehorizon'] = 0 if userhorizon is not None: params['userhorizon'] = ','.join(str(x) for x in userhorizon) if startyear is not None: params['startyear'] = startyear if endyear is not None: params['endyear'] = endyear res = requests.get(url + 'tmy', params=params, timeout=timeout) # PVGIS returns really well formatted error messages in JSON for HTTP/1.1 # 400 BAD REQUEST so try to return that if possible, otherwise raise the # HTTP/1.1 error caught by requests if not res.ok: try: err_msg = res.json() except Exception: res.raise_for_status() else: raise requests.HTTPError(err_msg['message']) # initialize data to None in case API fails to respond to bad outputformat data = None, None, None, None if outputformat == 'json': src = res.json() data, months_selected, inputs, meta = _parse_pvgis_tmy_json(src) elif outputformat == 'csv': with io.BytesIO(res.content) as src: data, months_selected, inputs, meta = _parse_pvgis_tmy_csv(src) elif outputformat == 'basic': with io.BytesIO(res.content) as src: data, months_selected, inputs, meta = _parse_pvgis_tmy_basic(src) elif outputformat == 'epw': with io.StringIO(res.content.decode('utf-8')) as src: data, meta = parse_epw(src) months_selected, inputs = None, None else: # this line is never reached because if outputformat is not valid then # the response is HTTP/1.1 400 BAD REQUEST which is handled earlier pass if map_variables: data = data.rename(columns=VARIABLE_MAP) return data, months_selected, inputs, meta
def _parse_pvgis_tmy_json(src): inputs = src['inputs'] meta = src['meta'] months_selected = src['outputs']['months_selected'] data = pd.DataFrame(src['outputs']['tmy_hourly']) data.index = pd.to_datetime( data['time(UTC)'], format='%Y%m%d:%H%M', utc=True) data = data.drop('time(UTC)', axis=1) return data, months_selected, inputs, meta def _parse_pvgis_tmy_csv(src): # the first 3 rows are latitude, longitude, elevation inputs = {} # 'Latitude (decimal degrees): 45.000\r\n' inputs['latitude'] = float(src.readline().split(b':')[1]) # 'Longitude (decimal degrees): 8.000\r\n' inputs['longitude'] = float(src.readline().split(b':')[1]) # Elevation (m): 1389.0\r\n inputs['elevation'] = float(src.readline().split(b':')[1]) # then there's a 13 row comma separated table with two columns: month, year # which contains the year used for that month in the src.readline() # get "month,year\r\n" months_selected = [] for month in range(12): months_selected.append( {'month': month+1, 'year': int(src.readline().split(b',')[1])}) # then there's the TMY (typical meteorological year) data # first there's a header row: # time(UTC),T2m,RH,G(h),Gb(n),Gd(h),IR(h),WS10m,WD10m,SP headers = [h.decode('utf-8').strip() for h in src.readline().split(b',')] data = pd.DataFrame( [src.readline().split(b',') for _ in range(8760)], columns=headers) dtidx = data['time(UTC)'].apply(lambda dt: dt.decode('utf-8')) dtidx = pd.to_datetime(dtidx, format='%Y%m%d:%H%M', utc=True) data = data.drop('time(UTC)', axis=1) data = pd.DataFrame(data, dtype=float) data.index = dtidx # finally there's some meta data meta = [line.decode('utf-8').strip() for line in src.readlines()] return data, months_selected, inputs, meta def _parse_pvgis_tmy_basic(src): data = pd.read_csv(src) data.index = pd.to_datetime( data['time(UTC)'], format='%Y%m%d:%H%M', utc=True) data = data.drop('time(UTC)', axis=1) return data, None, None, None
[docs]def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True): """ Read a file downloaded from PVGIS. Parameters ---------- filename : str, pathlib.Path, or file-like buffer Name, path, or buffer of file downloaded from PVGIS. pvgis_format : str, optional Format of PVGIS file or buffer. Equivalent to the ``outputformat`` parameter in the PVGIS TMY API. If ``filename`` is a file and ``pvgis_format`` is not specified then the file extension will be used to determine the PVGIS format to parse. For PVGIS files from the API with ``outputformat='basic'``, please set ``pvgis_format`` to ``'basic'``. If ``filename`` is a buffer, then ``pvgis_format`` is required and must be in ``['csv', 'epw', 'json', 'basic']``. map_variables: bool, default True When true, renames columns of the Dataframe to pvlib variable names where applicable. See variable :const:`VARIABLE_MAP`. Returns ------- data : pandas.DataFrame the weather data months_selected : list TMY year for each month, ``None`` for basic and EPW inputs : dict the inputs, ``None`` for basic and EPW metadata : list or dict file metadata, ``None`` for basic Raises ------ ValueError if ``pvgis_format`` is not specified and the file extension is neither ``.csv``, ``.json``, nor ``.epw``, or if ``pvgis_format`` is provided as input but isn't in ``['csv', 'epw', 'json', 'basic']`` TypeError if ``pvgis_format`` is not specified and ``filename`` is a buffer See Also -------- get_pvgis_tmy """ # get the PVGIS outputformat if pvgis_format is None: # get the file extension from suffix, but remove the dot and make sure # it's lower case to compare with epw, csv, or json # NOTE: raises TypeError if filename is a buffer outputformat = Path(filename).suffix[1:].lower() else: outputformat = pvgis_format # parse the pvgis file based on the output format, either 'epw', 'json', # 'csv', or 'basic' # EPW: use the EPW parser from the pvlib.iotools epw.py module if outputformat == 'epw': try: data, meta = parse_epw(filename) except AttributeError: # str/path has no .read() attribute data, meta = read_epw(filename) months_selected, inputs = None, None # NOTE: json, csv, and basic output formats have parsers defined as private # functions in this module # JSON: use Python built-in json module to convert file contents to a # Python dictionary, and pass the dictionary to the _parse_pvgis_tmy_json() # function from this module elif outputformat == 'json': try: src = json.load(filename) except AttributeError: # str/path has no .read() attribute with open(str(filename), 'r') as fbuf: src = json.load(fbuf) data, months_selected, inputs, meta = _parse_pvgis_tmy_json(src) # CSV or basic: use the correct parser from this module # eg: _parse_pvgis_tmy_csv() or _parse_pvgist_tmy_basic() elif outputformat in ['csv', 'basic']: # get the correct parser function for this output format from globals() pvgis_parser = globals()['_parse_pvgis_tmy_{:s}'.format(outputformat)] # NOTE: pvgis_parse() is a pvgis parser function from this module, # either _parse_pvgis_tmy_csv() or _parse_pvgist_tmy_basic() try: data, months_selected, inputs, meta = pvgis_parser(filename) except AttributeError: # str/path has no .read() attribute with open(str(filename), 'rb') as fbuf: data, months_selected, inputs, meta = pvgis_parser(fbuf) else: # raise exception if pvgis format isn't in ['csv','basic','epw','json'] err_msg = ( "pvgis format '{:s}' was unknown, must be either 'epw', 'json', " "'csv', or 'basic'").format(outputformat) raise ValueError(err_msg) if map_variables: data = data.rename(columns=VARIABLE_MAP) return data, months_selected, inputs, meta
[docs]def get_pvgis_horizon(latitude, longitude, url=URL, **kwargs): """Get horizon data from PVGIS. Parameters ---------- latitude : float Latitude in degrees north longitude : float Longitude in degrees east url: str, default: :const:`pvlib.iotools.pvgis.URL` Base URL for PVGIS kwargs: Passed to requests.get Returns ------- data : pd.Series Pandas Series of the retrived horizon elevation angles. Index is the corresponding horizon azimuth angles. metadata : dict Metadata returned by PVGIS. Notes ----- The horizon azimuths are specified clockwise from north, e.g., south=180. This is the standard pvlib convention, although the PVGIS website specifies south=0. References ---------- .. [1] `PVGIS horizon profile tool <https://ec.europa.eu/jrc/en/PVGIS/tools/horizon>`_ """ params = {'lat': latitude, 'lon': longitude, 'outputformat': 'json'} res = requests.get(url + 'printhorizon', params=params, **kwargs) if not res.ok: try: err_msg = res.json() except Exception: res.raise_for_status() else: raise requests.HTTPError(err_msg['message']) json_output = res.json() metadata = json_output['meta'] data = pd.DataFrame(json_output['outputs']['horizon_profile']) data.columns = ['horizon_azimuth', 'horizon_elevation'] # Convert azimuth to pvlib convention (north=0, south=180) data['horizon_azimuth'] += 180 data.set_index('horizon_azimuth', inplace=True) data = data['horizon_elevation'] # convert to pd.Series data = data[data.index < 360] # remove duplicate north point (0 and 360) return data, metadata