pvlib 0.9.5__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/data/test_read_pvgis_horizon.csv

@@ -0,0 +1,49 @@
+horizon_azimuth,horizon_elevation
+0,9.9
+7.5,13
+15,14.5
+22.5,15.7
+30,14.9
+37.5,15.3
+45,15.7
+52.5,15.7
+60,13
+67.5,11.5
+75,11.1
+82.5,11.5
+90,10.3
+97.5,11.5
+105,10.3
+112.5,9.5
+120,10.7
+127.5,11.8
+135,11.8
+142.5,8.8
+150,8.4
+157.5,7.3
+165,5.7
+172.5,5.7
+180,4.6
+187.5,3.4
+195,0.8
+202.5,0
+210,0
+217.5,0
+225,0
+232.5,0
+240,0
+247.5,0
+255,0
+262.5,0
+270,0
+277.5,0
+285,0
+292.5,0
+300,0
+307.5,0
+315,1.1
+322.5,1.9
+330,3.8
+337.5,5
+345,6.5
+352.5,9.2

pvlib/data/variables_style_rules.csv

@@ -7,6 +7,7 @@ dni_extra;direct normal irradiance at top of atmosphere (extraterrestrial)
 dhi;diffuse horizontal irradiance
 bhi;beam/direct horizontal irradiance
 ghi;global horizontal irradiance
+ghi_extra;horizontal irradiance at top of atmosphere (extraterrestrial)
 gri;ground-reflected irradiance
 aoi;angle of incidence between :math:`90\deg` and :math:`90\deg`
 aoi_projection;cos(aoi)
@@ -32,6 +33,8 @@ relative_humidity;relative humidity
 wind_speed;wind speed
 wind_direction;wind direction
 pressure;atmospheric pressure
+albedo;ratio of reflected solar irradiance to global horizontal irradiance, unitless
+precipitable_water;total precipitable water contained in a column of unit cross section from earth to top of atmosphere
 v_mp, i_mp, p_mp;module voltage, current, power at the maximum power point
 v_oc;open circuit module voltage
 i_sc;short circuit module current

pvlib/iam.py

@@ -175,8 +175,12 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None):
     n2costheta2 = n2 * costheta
 
     # reflectance of s-, p-polarized, and normal light by the first interface
-    rho12_s = ((n1costheta1 - n2costheta2) / (n1costheta1 + n2costheta2)) ** 2
-    rho12_p = ((n1costheta2 - n2costheta1) / (n1costheta2 + n2costheta1)) ** 2
+    with np.errstate(divide='ignore', invalid='ignore'):
+        rho12_s = \
+            ((n1costheta1 - n2costheta2) / (n1costheta1 + n2costheta2)) ** 2
+        rho12_p = \
+            ((n1costheta2 - n2costheta1) / (n1costheta2 + n2costheta1)) ** 2
+
     rho12_0 = ((n1 - n2) / (n1 + n2)) ** 2
 
     # transmittance through the first interface
@@ -208,13 +212,22 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None):
         tau_0 *= (1 - rho23_0) / (1 - rho23_0 * rho12_0)
 
     # transmittance after absorption in the glass
-    tau_s *= np.exp(-K * L / costheta)
-    tau_p *= np.exp(-K * L / costheta)
+    with np.errstate(divide='ignore', invalid='ignore'):
+        tau_s *= np.exp(-K * L / costheta)
+        tau_p *= np.exp(-K * L / costheta)
+
     tau_0 *= np.exp(-K * L)
 
     # incidence angle modifier
     iam = (tau_s + tau_p) / 2 / tau_0
 
+    # for light coming from behind the plane, none can enter the module
+    # when n2 > 1, this is already the case
+    if np.isclose(n2, 1).any():
+        iam = np.where(aoi >= 90, 0, iam)
+        if isinstance(aoi, pd.Series):
+            iam = pd.Series(iam, index=aoi.index)
+
     return iam
 
 

pvlib/inverter.py

@@ -335,7 +335,7 @@ def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     NREL's PVWatts inverter model.
 
     The PVWatts inverter model [1]_ calculates inverter efficiency :math:`\eta`
-    as a function of input DC power
+    as a function of input DC power :math:`P_{dc}`
 
     .. math::
 
@@ -369,6 +369,10 @@ def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
 
     Notes
     -----
+    When sourcing ``pdc`` from pvlib functions
+    (e.g. :py:func:`pvlib.pvsystem.pvwatts_dc`) their DC power output is in W,
+    and ``pdc0`` should have the same unit (W).
+
     Note that ``pdc0`` is also used as a symbol in
     :py:func:`pvlib.pvsystem.pvwatts_dc`. ``pdc0`` in this function refers to
     the DC power input limit of the inverter. ``pdc0`` in
@@ -393,6 +397,7 @@ def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     pdc_neq_0 = ~np.equal(pdc, 0)
 
     # eta < 0 if zeta < 0.006. power_ac is forced to be >= 0 below. GH 541
+    # In some published versions of [1] the parentheses are missing
     eta = eta_inv_nom / eta_inv_ref * (
         -0.0162 * zeta - np.divide(0.0059, zeta, out=eta, where=pdc_neq_0)
         + 0.9858)  # noQA: W503

pvlib/iotools/__init__.py

@@ -2,11 +2,10 @@ from pvlib.iotools.tmy import read_tmy2, read_tmy3  # noqa: F401
 from pvlib.iotools.epw import read_epw, parse_epw  # noqa: F401
 from pvlib.iotools.srml import read_srml  # noqa: F401
 from pvlib.iotools.srml import read_srml_month_from_solardat  # noqa: F401
+from pvlib.iotools.srml import get_srml  # noqa: F401
 from pvlib.iotools.surfrad import read_surfrad  # noqa: F401
 from pvlib.iotools.midc import read_midc  # noqa: F401
 from pvlib.iotools.midc import read_midc_raw_data_from_nrel  # noqa: F401
-from pvlib.iotools.ecmwf_macc import read_ecmwf_macc  # noqa: F401
-from pvlib.iotools.ecmwf_macc import get_ecmwf_macc  # noqa: F401
 from pvlib.iotools.crn import read_crn  # noqa: F401
 from pvlib.iotools.solrad import read_solrad  # noqa: F401
 from pvlib.iotools.psm3 import get_psm3  # noqa: F401
@@ -15,9 +14,15 @@ from pvlib.iotools.psm3 import parse_psm3  # noqa: F401
 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
 from pvlib.iotools.sodapro import get_cams  # noqa: F401
 from pvlib.iotools.sodapro import read_cams  # noqa: F401
 from pvlib.iotools.sodapro import parse_cams  # noqa: F401
+from pvlib.iotools.acis import get_acis_prism  # noqa: F401
+from pvlib.iotools.acis import get_acis_nrcc  # noqa: F401
+from pvlib.iotools.acis import get_acis_mpe  # noqa: F401
+from pvlib.iotools.acis import get_acis_station_data  # noqa: F401
+from pvlib.iotools.acis import get_acis_available_stations  # noqa: F401

pvlib/iotools/acis.py

@@ -0,0 +1,516 @@
+import requests
+import pandas as pd
+import numpy as np
+
+
+VARIABLE_MAP = {
+    # time series names
+    'pcpn': 'precipitation',
+    'maxt': 'temp_air_max',
+    'avgt': 'temp_air_average',
+    'obst': 'temp_air_observation',
+    'mint': 'temp_air_min',
+    'cdd': 'cooling_degree_days',
+    'hdd': 'heating_degree_days',
+    'gdd': 'growing_degree_days',
+    'snow': 'snowfall',
+    'snwd': 'snowdepth',
+
+    # metadata names
+    'lat': 'latitude',
+    'lon': 'longitude',
+    'elev': 'altitude',
+}
+
+
+def _get_acis(start, end, params, map_variables, url, **kwargs):
+    """
+    generic helper for the public get_acis_X functions
+    """
+    params = {
+        # use pd.to_datetime so that strings (e.g. '2021-01-01') are accepted
+        'sdate': pd.to_datetime(start).strftime('%Y-%m-%d'),
+        'edate': pd.to_datetime(end).strftime('%Y-%m-%d'),
+        'output': 'json',
+        **params,  # endpoint-specific parameters
+    }
+    response = requests.post(url,
+                             json=params,
+                             headers={"Content-Type": "application/json"},
+                             **kwargs)
+    response.raise_for_status()
+    payload = response.json()
+
+    # somewhat inconveniently, the ACIS API tends to return errors as "valid"
+    # responses instead of using proper HTTP error codes:
+    if "error" in payload:
+        raise requests.HTTPError(payload['error'], response=response)
+
+    columns = ['date'] + [e['name'] for e in params['elems']]
+    df = pd.DataFrame(payload['data'], columns=columns)
+    df = df.set_index('date')
+    df.index = pd.to_datetime(df.index)
+    df.index.name = None
+
+    metadata = payload['meta']
+
+    try:
+        # for StnData endpoint, unpack combination "ll" into lat, lon 
+        metadata['lon'], metadata['lat'] = metadata.pop('ll')
+    except KeyError:
+        pass
+
+    try:
+        metadata['elev'] = metadata['elev'] * 0.3048  # feet to meters
+    except KeyError:
+        # some queries don't return elevation
+        pass
+
+    if map_variables:
+        df = df.rename(columns=VARIABLE_MAP)
+
+        for key in list(metadata.keys()):
+            if key in VARIABLE_MAP:
+                metadata[VARIABLE_MAP[key]] = metadata.pop(key)
+
+    return df, metadata
+
+
+def get_acis_prism(latitude, longitude, start, end, map_variables=True,
+                   url="https://data.rcc-acis.org/GridData", **kwargs):
+    """
+    Retrieve estimated daily precipitation and temperature data from PRISM
+    via the Applied Climate Information System (ACIS).
+
+    ACIS [2]_, [3]_ aggregates and provides access to climate data
+    from many underlying sources.  This function retrieves daily data from
+    the Parameter-elevation Regressions on Independent Slopes Model
+    (PRISM) [1]_, a gridded precipitation and temperature model
+    from Oregon State University.
+
+    Geographical coverage: US, Central America, and part of South America.
+    Approximately 0° to 50° in latitude and -130° to -65° in longitude.
+
+    Parameters
+    ----------
+    latitude : float
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float
+        in decimal degrees, between -180 and 180, east is positive
+    start : datetime-like
+        First day of the requested period
+    end : datetime-like
+        Last day of the requested period
+    map_variables : bool, default True
+        When True, rename data columns and metadata keys to pvlib variable
+        names where applicable. See variable :const:`VARIABLE_MAP`.
+    url : str, default: 'https://data.rcc-acis.org/GridData'
+        API endpoint URL
+    kwargs:
+        Optional parameters passed to ``requests.post``.
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        Daily precipitation [mm], temperature [Celsius], and degree day
+        [Celsius-days] data
+    metadata : dict
+        Metadata of the selected grid cell
+
+    Raises
+    ------
+    requests.HTTPError
+        A message from the ACIS server if the request is rejected
+
+    Notes
+    -----
+    PRISM data is aggregated from 12:00 to 12:00 UTC, meaning data labeled
+    May 26 reflects to the 24 hours ending at 7:00am Eastern Standard Time
+    on May 26.
+
+    References
+    ----------
+    .. [1] `PRISM <https://prism.oregonstate.edu/>`_
+    .. [2] `ACIS Gridded Data <http://www.rcc-acis.org/docs_gridded.html>`_
+    .. [3] `ACIS Web Services <http://www.rcc-acis.org/docs_webservices.html>`_
+
+    Examples
+    --------
+    >>> from pvlib.iotools import get_acis_prism
+    >>> df, meta = get_acis_prism(40, 80, '2020-01-01', '2020-12-31')
+    """
+    elems = [
+        {"name": "pcpn", "interval": "dly", "units": "mm"},
+        {"name": "maxt", "interval": "dly", "units": "degreeC"},
+        {"name": "mint", "interval": "dly", "units": "degreeC"},
+        {"name": "avgt", "interval": "dly", "units": "degreeC"},
+        {"name": "cdd", "interval": "dly", "units": "degreeC"},
+        {"name": "hdd", "interval": "dly", "units": "degreeC"},
+        {"name": "gdd", "interval": "dly", "units": "degreeC"},
+    ]
+    params = {
+        'loc': f"{longitude},{latitude}",
+        'grid': "21",
+        'elems': elems,
+        'meta': ["ll", "elev"],
+    }
+    df, meta = _get_acis(start, end, params, map_variables, url, **kwargs)
+    df = df.replace(-999, np.nan)
+    return df, meta
+
+
+def get_acis_nrcc(latitude, longitude, start, end, grid, map_variables=True,
+                  url="https://data.rcc-acis.org/GridData", **kwargs):
+    """
+    Retrieve estimated daily precipitation and temperature data from the
+    Northeast Regional Climate Center via the Applied Climate
+    Information System (ACIS).
+
+    ACIS [2]_, [3]_ aggregates and provides access to climate data
+    from many underlying sources.  This function retrieves daily data from
+    Cornell's Northeast Regional Climate Center (NRCC) [1]_.
+
+    Geographical coverage: US, Central America, and part of South America.
+    Approximately 0° to 50° in latitude and -130° to -65° in longitude.
+
+    Parameters
+    ----------
+    latitude : float
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float
+        in decimal degrees, between -180 and 180, east is positive
+    start : datetime-like
+        First day of the requested period
+    end : datetime-like
+        Last day of the requested period
+    grid : int
+        Options are either 1 (for "NRCC Interpolated") or 3
+        (for "NRCC Hi-Resolution").  See [2]_ for details.
+    map_variables : bool, default True
+        When True, rename data columns and metadata keys to pvlib variable
+        names where applicable. See variable :const:`VARIABLE_MAP`.
+    url : str, default: 'https://data.rcc-acis.org/GridData'
+        API endpoint URL
+    kwargs:
+        Optional parameters passed to ``requests.post``.
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        Daily precipitation [mm], temperature [Celsius], and degree day
+        [Celsius-days] data
+    metadata : dict
+        Metadata of the selected grid cell
+
+    Raises
+    ------
+    requests.HTTPError
+        A message from the ACIS server if the request is rejected
+
+    Notes
+    -----
+    The returned values are 24-hour aggregates, but
+    the aggregation period may not be midnight to midnight in local time.
+    Check the ACIS and NRCC documentation for details.
+
+    References
+    ----------
+    .. [1] `NRCC <http://www.nrcc.cornell.edu/>`_
+    .. [2] `ACIS Gridded Data <http://www.rcc-acis.org/docs_gridded.html>`_
+    .. [3] `ACIS Web Services <http://www.rcc-acis.org/docs_webservices.html>`_
+
+    Examples
+    --------
+    >>> from pvlib.iotools import get_acis_nrcc
+    >>> df, meta = get_acis_nrcc(40, -80, '2020-01-01', '2020-12-31', grid=1)
+    """
+    elems = [
+        {"name": "pcpn", "interval": "dly", "units": "mm"},
+        {"name": "maxt", "interval": "dly", "units": "degreeC"},
+        {"name": "mint", "interval": "dly", "units": "degreeC"},
+        {"name": "avgt", "interval": "dly", "units": "degreeC"},
+        {"name": "cdd", "interval": "dly", "units": "degreeC"},
+        {"name": "hdd", "interval": "dly", "units": "degreeC"},
+        {"name": "gdd", "interval": "dly", "units": "degreeC"},
+    ]
+    params = {
+        'loc': f"{longitude},{latitude}",
+        'grid': grid,
+        'elems': elems,
+        'meta': ["ll", "elev"],
+    }
+    df, meta = _get_acis(start, end, params, map_variables, url, **kwargs)
+    df = df.replace(-999, np.nan)
+    return df, meta
+
+
+
+def get_acis_mpe(latitude, longitude, start, end, map_variables=True,
+                 url="https://data.rcc-acis.org/GridData", **kwargs):
+    """
+    Retrieve estimated daily Multi-sensor Precipitation Estimates
+    via the Applied Climate Information System (ACIS).
+
+    ACIS [2]_, [3]_ aggregates and provides access to climate data
+    from many underlying sources.  This function retrieves daily data from
+    the National Weather Service's Multi-sensor Precipitation Estimates
+    (MPE) [1]_, a gridded precipitation model.
+
+    This dataset covers the contiguous United States, Mexico, and parts of
+    Central America.
+
+    Parameters
+    ----------
+    latitude : float
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float
+        in decimal degrees, between -180 and 180, east is positive
+    start : datetime-like
+        First day of the requested period
+    end : datetime-like
+        Last day of the requested period
+    map_variables : bool, default True
+        When True, rename data columns and metadata keys to pvlib variable
+        names where applicable. See variable :const:`VARIABLE_MAP`.
+    url : str, default: 'https://data.rcc-acis.org/GridData'
+        API endpoint URL
+    kwargs:
+        Optional parameters passed to ``requests.post``.
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        Daily precipitation [mm] data
+    metadata : dict
+        Coordinates of the selected grid cell
+
+    Raises
+    ------
+    requests.HTTPError
+        A message from the ACIS server if the request is rejected
+
+    Notes
+    -----
+    The returned values are 24-hour aggregates, but
+    the aggregation period may not be midnight to midnight in local time.
+    Check the ACIS and MPE documentation for details.
+
+    References
+    ----------
+    .. [1] `Multisensor Precipitation Estimates
+           <https://www.weather.gov/marfc/Multisensor_Precipitation>`_
+    .. [2] `ACIS Gridded Data <http://www.rcc-acis.org/docs_gridded.html>`_
+    .. [3] `ACIS Web Services <http://www.rcc-acis.org/docs_webservices.html>`_
+
+    Examples
+    --------
+    >>> from pvlib.iotools import get_acis_mpe
+    >>> df, meta = get_acis_mpe(40, -80, '2020-01-01', '2020-12-31')
+    """
+    elems = [
+        # only precipitation is supported in this dataset
+        {"name": "pcpn", "interval": "dly", "units": "mm"},
+    ]
+    params = {
+        'loc': f"{longitude},{latitude}",
+        'grid': "2",
+        'elems': elems,
+        'meta': ["ll"],  # "elev" is not supported for this dataset
+    }
+    df, meta = _get_acis(start, end, params, map_variables, url, **kwargs)
+    df = df.replace(-999, np.nan)
+    return df, meta
+
+
+def get_acis_station_data(station, start, end, trace_val=0.001,
+                          map_variables=True,
+                          url="https://data.rcc-acis.org/StnData", **kwargs):
+    """
+    Retrieve weather station climate records via the Applied Climate
+    Information System (ACIS).
+
+    ACIS [1]_, [2]_ aggregates and provides access to climate data
+    from many underlying sources.  This function retrieves measurements
+    from ground stations belonging to various global networks.
+
+    This function can query data from stations all over the world.
+    The stations available in a given area can be listed using
+    :py:func:`get_acis_available_stations`.
+
+    Parameters
+    ----------
+    station : str
+        Identifier code for the station to query. Identifiers from many
+        station networks are accepted, including WBAN, COOP, FAA, WMO, GHCN,
+        and others.  See [1]_ and [2]_ for details.
+    start : datetime-like
+        First day of the requested period
+    end : datetime-like
+        Last day of the requested period
+    map_variables : bool, default True
+        When True, rename data columns and metadata keys to pvlib variable
+        names where applicable. See variable :const:`VARIABLE_MAP`.
+    trace_val : float, default 0.001
+        Value to replace "trace" values in the precipitation data
+    url : str, default: 'https://data.rcc-acis.org/GridData'
+        API endpoint URL
+    kwargs:
+        Optional parameters passed to ``requests.post``.
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        Daily precipitation [mm], temperature [Celsius], snow [mm], and
+        degree day [Celsius-days] data
+    metadata : dict
+        station metadata
+
+    Raises
+    ------
+    requests.HTTPError
+        A message from the ACIS server if the request is rejected
+
+    See Also
+    --------
+    get_acis_available_stations
+
+    References
+    ----------
+    .. [1] `ACIS Web Services <http://www.rcc-acis.org/docs_webservices.html>`_
+    .. [2] `ACIS Metadata <http://www.rcc-acis.org/docs_metadata.html>`_
+
+    Examples
+    --------
+    >>> # Using an FAA code (Chicago O'Hare airport)
+    >>> from pvlib.iotools import get_acis_station_data
+    >>> df, meta = get_acis_station_data('ORD', '2020-01-01', '2020-12-31')
+    >>>
+    >>> # Look up available stations in a lat/lon rectangle, with data
+    >>> # available in the specified date range:
+    >>> from pvlib.iotools import get_acis_available_stations
+    >>> stations = get_acis_available_stations([39.5, 40.5], [-80.5, -79.5],
+    ...                                        '2020-01-01', '2020-01-03')
+    >>> stations['sids'][0]
+    ['369367 2', 'USC00369367 6', 'WYNP1 7']
+    >>> df, meta = get_acis_station_data('369367', '2020-01-01', '2020-01-03')
+    """
+    elems = [
+        {"name": "maxt", "interval": "dly", "units": "degreeC"},
+        {"name": "mint", "interval": "dly", "units": "degreeC"},
+        {"name": "avgt", "interval": "dly", "units": "degreeC"},
+        {"name": "obst", "interval": "dly", "units": "degreeC"},
+        {"name": "pcpn", "interval": "dly", "units": "mm"},
+        {"name": "snow", "interval": "dly", "units": "cm"},
+        {"name": "snwd", "interval": "dly", "units": "cm"},
+        {"name": "cdd", "interval": "dly", "units": "degreeC"},
+        {"name": "hdd", "interval": "dly", "units": "degreeC"},
+        {"name": "gdd", "interval": "dly", "units": "degreeC"},
+    ]
+    params = {
+        'sid': str(station),
+        'elems': elems,
+        'meta': ('name,state,sids,sid_dates,ll,elev,uid,county,'
+                 'climdiv,valid_daterange,tzo,network')
+    }
+    df, metadata = _get_acis(start, end, params, map_variables, url, **kwargs)
+    df = df.replace("M", np.nan)
+    df = df.replace("T", trace_val)
+    df = df.astype(float)
+    return df, metadata
+
+
+def get_acis_available_stations(latitude_range, longitude_range,
+                                start=None, end=None,
+                                url="https://data.rcc-acis.org/StnMeta",
+                                **kwargs):
+    """
+    List weather stations in a given area available from the
+    Applied Climate Information System (ACIS).
+
+    The ``sids`` returned by this function can be used with
+    :py:func:`get_acis_station_data` to retrieve weather measurements
+    from the station.
+
+    Parameters
+    ----------
+    latitude_range : list
+        A 2-element list of [southern bound, northern bound]
+        in decimal degrees, between -90 and 90, north is positive
+    longitude_range : list
+        A 2-element list of [western bound, eastern bound]
+        in decimal degrees, between -180 and 180, east is positive
+    start : datetime-like, optional
+        If specified, return only stations that have data between ``start`` and
+        ``end``.  If not specified, all stations in the region are returned.
+    end : datetime-like, optional
+        See ``start``
+    url : str, default: 'https://data.rcc-acis.org/StnMeta'
+        API endpoint URL
+    kwargs:
+        Optional parameters passed to ``requests.post``.
+
+    Returns
+    -------
+    stations : pandas.DataFrame
+        A dataframe of station metadata, one row per station.
+        The ``sids`` column contains IDs that can be used with 
+        :py:func:`get_acis_station_data`.
+
+    Raises
+    ------
+    requests.HTTPError
+        A message from the ACIS server if the request is rejected
+
+    See Also
+    --------
+    get_acis_station_data
+
+    References
+    ----------
+    .. [1] `ACIS Web Services <http://www.rcc-acis.org/docs_webservices.html>`_
+    .. [2] `ACIS Metadata <http://www.rcc-acis.org/docs_metadata.html>`_
+
+    Examples
+    --------
+    >>> # Look up available stations in a lat/lon rectangle, with data
+    >>> # available in the specified date range:
+    >>> from pvlib.iotools import get_acis_available_stations
+    >>> stations = get_acis_available_stations([39.5, 40.5], [-80.5, -79.5],
+    ...                                        '2020-01-01', '2020-01-03')
+    >>> stations['sids'][0]
+    ['369367 2', 'USC00369367 6', 'WYNP1 7']
+    """
+    bbox = "{},{},{},{}".format(
+        longitude_range[0],
+        latitude_range[0],
+        longitude_range[1],
+        latitude_range[1],
+    )
+    params = {
+        "bbox": bbox,
+        "meta": ("name,state,sids,sid_dates,ll,elev,"
+                 "uid,county,climdiv,tzo,network"),    
+    }
+    if start is not None and end is not None:
+        params['elems'] = ['maxt', 'mint', 'avgt', 'obst',
+                           'pcpn', 'snow', 'snwd']
+        params['sdate'] = pd.to_datetime(start).strftime('%Y-%m-%d')
+        params['edate'] = pd.to_datetime(end).strftime('%Y-%m-%d')
+
+    response = requests.post(url,
+                             json=params,
+                             headers={"Content-Type": "application/json"},
+                             **kwargs)
+    response.raise_for_status()
+    payload = response.json()
+    if "error" in payload:
+        raise requests.HTTPError(payload['error'], response=response)
+
+    metadata = payload['meta']
+    for station_record in metadata:
+        station_record['altitude'] = station_record.pop('elev')
+        station_record['longitude'], station_record['latitude'] = \
+            station_record.pop('ll')
+
+    df = pd.DataFrame(metadata)
+    return df