Adding PVGIS horizon data retrieval method

docs/sphinx/source/reference/iotools.rst

@@ -31,6 +31,7 @@ of sources and file formats relevant to solar energy modeling.
    iotools.read_pvgis_tmy
    iotools.get_pvgis_hourly
    iotools.read_pvgis_hourly
+   iotools.get_pvgis_horizon
    iotools.get_bsrn
    iotools.read_bsrn
    iotools.parse_bsrn

docs/sphinx/source/whatsnew/v0.9.6.rst

@@ -11,7 +11,8 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* Added function to retrieve horizon data from PVGIS 
+  :py:func:`pvlib.iotools.get_pvgis_horizon`. (:issue:`1290`, :pull:`1395`)
 
 Bug fixes
 ~~~~~~~~~
@@ -40,7 +41,15 @@ Contributors
 ~~~~~~~~~~~~
 * Lakshya Garg (:ghuser:`Lakshyadevelops`)
 * Adam R. Jensen (:ghuser:`adamrjensen`)
+* Ben Pierce (:ghuser:`bgpierc`)
+* Joseph Palakapilly (:ghuser:`JPalakapillyKWH`)
+* Cliff Hansen (:ghuser:`cwhanse`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Will Holmgren (:ghuser:`wholmgren`)
+* Mark Mikofski (:ghuser:`mikofski`)
+* Karel De Brabandere (:ghuser:`kdebrab`)
+* Josh Stein (:ghuser:`jsstein`)
+* Kevin Anderson (:ghuser:`kandersolar`)
 * Siddharth Kaul (:ghuser:`k10blogger`)
 * Kshitiz Gupta (:ghuser:`kshitiz305`)
 * Stefan de Lange (:ghuser:`langestefan`)
-

pvlib/data/test_read_pvgis_horizon.csv

@@ -0,0 +1,50 @@
+,horizon_azimuth,horizon_elevation
+0,0.0,9.9
+1,7.5,13.0
+2,15.0,14.5
+3,22.5,15.7
+4,30.0,14.9
+5,37.5,15.3
+6,45.0,15.7
+7,52.5,15.7
+8,60.0,13.0
+9,67.5,11.5
+10,75.0,11.1
+11,82.5,11.5
+12,90.0,10.3
+13,97.5,11.5
+14,105.0,10.3
+15,112.5,9.5
+16,120.0,10.7
+17,127.5,11.8
+18,135.0,11.8
+19,142.5,8.8
+20,150.0,8.4
+21,157.5,7.3
+22,165.0,5.7
+23,172.5,5.7
+24,180.0,4.6
+25,187.5,3.4
+26,195.0,0.8
+27,202.5,0.0
+28,210.0,0.0
+29,217.5,0.0
+30,225.0,0.0
+31,232.5,0.0
+32,240.0,0.0
+33,247.5,0.0
+34,255.0,0.0
+35,262.5,0.0
+36,270.0,0.0
+37,277.5,0.0
+38,285.0,0.0
+39,292.5,0.0
+40,300.0,0.0
+41,307.5,0.0
+42,315.0,1.1
+43,322.5,1.9
+44,330.0,3.8
+45,337.5,5.0
+46,345.0,6.5
+47,352.5,9.2
+48,360.0,9.9

pvlib/iotools/__init__.py

@@ -15,6 +15,7 @@
 from pvlib.iotools.pvgis import get_pvgis_tmy, read_pvgis_tmy  # noqa: F401
 from pvlib.iotools.pvgis import read_pvgis_hourly  # noqa: F401
 from pvlib.iotools.pvgis import get_pvgis_hourly  # noqa: F401
+from pvlib.iotools.pvgis import get_pvgis_horizon  # noqa: F401
 from pvlib.iotools.bsrn import get_bsrn  # noqa: F401
 from pvlib.iotools.bsrn import read_bsrn  # noqa: F401
 from pvlib.iotools.bsrn import parse_bsrn  # noqa: F401

pvlib/iotools/pvgis.py

@@ -665,3 +665,45 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=None):
         data = data.rename(columns=VARIABLE_MAP)
 
     return data, months_selected, inputs, meta
+
+
+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.DataFrame
+        Pandas dataframe of the retrived horizon
+
+    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()
+    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)
+    return data

pvlib/tests/iotools/test_pvgis.py

@@ -9,8 +9,9 @@
 import requests
 from pvlib.iotools import get_pvgis_tmy, read_pvgis_tmy
 from pvlib.iotools import get_pvgis_hourly, read_pvgis_hourly
+from pvlib.iotools import get_pvgis_horizon
 from ..conftest import (DATA_DIR, RERUNS, RERUNS_DELAY, assert_frame_equal,
-                        fail_on_pvlib_version)
+                        fail_on_pvlib_version, assert_series_equal)
 from pvlib._deprecation import pvlibDeprecationWarning
 
 
@@ -509,6 +510,21 @@ def test_get_pvgis_map_variables(pvgis_tmy_mapped_columns):
     assert all([c in pvgis_tmy_mapped_columns for c in actual.columns])
 
 
+@pytest.mark.remote_data
+def test_read_pvgis_horizon():
+    pvgis_data = get_pvgis_horizon(35.171051, -106.465158)
+    horizon_data = pd.read_csv(DATA_DIR / 'test_read_pvgis_horizon.csv',
+                               index_col=0)
+    horizon_data.set_index('horizon_azimuth', inplace=True)
+    assert_frame_equal(pvgis_data, horizon_data)
+
+
+@pytest.mark.remote_data
+def test_read_pvgis_horizon_invalid_coords():
+    with pytest.raises(requests.HTTPError, match='lat: Incorrect value'):
+        _ = get_pvgis_horizon(100, 50)  # unfeasible latitude
+
+
 def test_read_pvgis_tmy_map_variables(pvgis_tmy_mapped_columns):
     fn = DATA_DIR / 'tmy_45.000_8.000_2005_2016.json'
     actual, _, _, _ = read_pvgis_tmy(fn, map_variables=True)