pvlib 0.12.0__py3-none-any.whl → 0.12.1a1__py3-none-any.whl

pvlib/iotools/psm4.py

@@ -0,0 +1,819 @@
+"""
+Functions for reading and retrieving data from NSRDB PSM4. See:
+https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-aggregated-v4-0-0-download/
+https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-tmy-v4-0-0-download/
+https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-conus-v4-0-0-download/
+https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-full-disc-v4-0-0-download/
+"""
+
+import io
+from urllib.parse import urljoin
+import requests
+import pandas as pd
+from json import JSONDecodeError
+
+NSRDB_API_BASE = "https://developer.nrel.gov/api/nsrdb/v2/solar/"
+PSM4_AGG_ENDPOINT = "nsrdb-GOES-aggregated-v4-0-0-download.csv"
+PSM4_TMY_ENDPOINT = "nsrdb-GOES-tmy-v4-0-0-download.csv"
+PSM4_CON_ENDPOINT = "nsrdb-GOES-conus-v4-0-0-download.csv"
+PSM4_FUL_ENDPOINT = "nsrdb-GOES-full-disc-v4-0-0-download.csv"
+PSM4_AGG_URL = urljoin(NSRDB_API_BASE, PSM4_AGG_ENDPOINT)
+PSM4_TMY_URL = urljoin(NSRDB_API_BASE, PSM4_TMY_ENDPOINT)
+PSM4_CON_URL = urljoin(NSRDB_API_BASE, PSM4_CON_ENDPOINT)
+PSM4_FUL_URL = urljoin(NSRDB_API_BASE, PSM4_FUL_ENDPOINT)
+
+PARAMETERS = (
+    'air_temperature', 'dew_point', 'dhi', 'dni', 'ghi', 'surface_albedo',
+    'surface_pressure', 'wind_direction', 'wind_speed')
+PVLIB_PYTHON = 'pvlib python'
+
+# Dictionary mapping PSM4 response names to pvlib names
+VARIABLE_MAP = {
+    'GHI': 'ghi',
+    'DHI': 'dhi',
+    'DNI': 'dni',
+    'Clearsky GHI': 'ghi_clear',
+    'Clearsky DHI': 'dhi_clear',
+    'Clearsky DNI': 'dni_clear',
+    'Solar Zenith Angle': 'solar_zenith',
+    'Temperature': 'temp_air',
+    'Dew Point': 'temp_dew',
+    'Relative Humidity': 'relative_humidity',
+    'Pressure': 'pressure',
+    'Wind Speed': 'wind_speed',
+    'Wind Direction': 'wind_direction',
+    'Surface Albedo': 'albedo',
+    'Precipitable Water': 'precipitable_water',
+    'AOD': 'aod',
+}
+
+# Dictionary mapping pvlib names to PSM4 request names
+# Note, PSM4 uses different names for the same variables in the
+# response and the request
+REQUEST_VARIABLE_MAP = {
+    'ghi': 'ghi',
+    'dhi': 'dhi',
+    'dni': 'dni',
+    'ghi_clear': 'clearsky_ghi',
+    'dhi_clear': 'clearsky_dhi',
+    'dni_clear': 'clearsky_dni',
+    'solar_zenith': 'solar_zenith_angle',
+    'temp_air': 'air_temperature',
+    'temp_dew': 'dew_point',
+    'relative_humidity': 'relative_humidity',
+    'pressure': 'surface_pressure',
+    'wind_speed': 'wind_speed',
+    'wind_direction': 'wind_direction',
+    'albedo': 'surface_albedo',
+    'precipitable_water': 'total_precipitable_water',
+    'aod': 'aod',
+}
+
+
+def get_nsrdb_psm4_aggregated(latitude, longitude, api_key, email,
+                              year='2023', time_step=60,
+                              parameters=PARAMETERS, leap_day=True,
+                              full_name=PVLIB_PYTHON,
+                              affiliation=PVLIB_PYTHON,
+                              utc=False, map_variables=True, url=None,
+                              timeout=30):
+    """
+    Retrieve NSRDB PSM4 timeseries weather data from the PSM4 NSRDB GOES
+    Aggregated v4 API.
+
+    The NSRDB is described in [1]_ and the PSM4 NSRDB GOES Aggregated v4 API is
+    described in [2]_,.
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    api_key : str
+        NREL Developer Network API key
+    email : str
+        NREL API uses this to automatically communicate messages back
+        to the user only if necessary
+    year : str, default '2023'
+        PSM4 API parameter specifing year (e.g. ``2023``) to download. The
+        allowed values update periodically, so consult the NSRDB reference
+        below for the current set of options. Called ``names`` in NSRDB API.
+    time_step : int, {60, 30}
+        time step in minutes, must be 60 or 30 for PSM4 Aggregated. Called
+        ``interval`` in NSRDB API.
+    parameters : list of str, optional
+        meteorological fields to fetch. If not specified, defaults to
+        ``pvlib.iotools.psm4.PARAMETERS``. See reference [2]_ for a list of
+        available fields. Alternatively, pvlib names may also be used (e.g.
+        'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`. To
+        retrieve all available fields, set ``parameters=[]``.
+    leap_day : bool, default : True
+        include leap day in the results
+    full_name : str, default 'pvlib python'
+        optional
+    affiliation : str, default 'pvlib python'
+        optional
+    utc: bool, default : False
+        retrieve data with timestamps converted to UTC. False returns
+        timestamps in local standard time of the selected location
+    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, optional
+        Full API endpoint URL. If not specified, the PSM4 GOES Aggregated v4
+        URL is used.
+    timeout : int, default 30
+        time in seconds to wait for server response before timeout
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see
+        :func:`pvlib.iotools.parse_nsrdb_psm4` for fields
+
+    Raises
+    ------
+    requests.HTTPError
+        if the request response status is not ok, then the ``'errors'`` field
+        from the JSON response or any error message in the content will be
+        raised as an exception, for example if the `api_key` was rejected or if
+        the coordinates were not found in the NSRDB
+
+    Notes
+    -----
+    The required NREL developer key, `api_key`, is available for free by
+    registering at the `NREL Developer Network <https://developer.nrel.gov/>`_.
+
+    .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
+        result in rejected requests.
+
+    .. warning:: PSM4 is limited to data found in the NSRDB, please consult
+        the references below for locations with available data. Additionally,
+        querying data with < 30-minute resolution uses a different API endpoint
+        with fewer available fields (see [4]_).
+
+    See Also
+    --------
+    pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_conus,
+    pvlib.iotools.get_nsrdb_psm4_full_disc, pvlib.iotools.read_nsrdb_psm4,
+    pvlib.iotools.parse_nsrdb_psm4
+
+    References
+    ----------
+
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `NSRDB GOES Aggregated V4.0.0
+       <https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-aggregated-v4-0-0-download/>`_
+    """
+    # The well know text (WKT) representation of geometry notation is strict.
+    # A POINT object is a string with longitude first, then the latitude, with
+    # four decimals each, and exactly one space between them.
+    longitude = ('%9.4f' % longitude).strip()
+    latitude = ('%8.4f' % latitude).strip()
+    # TODO: make format_WKT(object_type, *args) in tools.py
+
+    # convert to string to accomodate integer years being passed in
+    year = str(year)
+
+    # convert pvlib names in parameters to PSM4 convention
+    parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
+
+    # required query-string parameters for request to PSM4 API
+    params = {
+        'api_key': api_key,
+        'full_name': full_name,
+        'email': email,
+        'affiliation': affiliation,
+        'reason': PVLIB_PYTHON,
+        'mailing_list': 'false',
+        'wkt': 'POINT(%s %s)' % (longitude, latitude),
+        'names': year,
+        'attributes':  ','.join(parameters),
+        'leap_day': str(leap_day).lower(),
+        'utc': str(utc).lower(),
+        'interval': time_step
+    }
+    # request CSV download from NREL PSM4
+    if url is None:
+        url = PSM4_AGG_URL
+
+    response = requests.get(url, params=params, timeout=timeout)
+    if not response.ok:
+        # if the API key is rejected, then the response status will be 403
+        # Forbidden, and then the error is in the content and there is no JSON
+        try:
+            errors = response.json()['errors']
+        except JSONDecodeError:
+            errors = response.content.decode('utf-8')
+        raise requests.HTTPError(errors, response=response)
+    # the CSV is in the response content as a UTF-8 bytestring
+    # to use pandas we need to create a file buffer from the response
+    fbuf = io.StringIO(response.content.decode('utf-8'))
+    return parse_nsrdb_psm4(fbuf, map_variables)
+
+
+def get_nsrdb_psm4_tmy(latitude, longitude, api_key, email, year='tmy',
+                       time_step=60, parameters=PARAMETERS, leap_day=False,
+                       full_name=PVLIB_PYTHON, affiliation=PVLIB_PYTHON,
+                       utc=False, map_variables=True, url=None, timeout=30):
+    """
+    Retrieve NSRDB PSM4 timeseries weather data from the PSM4 NSRDB GOES
+    TMY v4 API.
+
+    The NSRDB is described in [1]_ and the PSM4 NSRDB GOES TMY v4 API is
+    described in [2]_,.
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    api_key : str
+        NREL Developer Network API key
+    email : str
+        NREL API uses this to automatically communicate messages back
+        to the user only if necessary
+    year : str, default 'tmy'
+        PSM4 API parameter specifing TMY variant to download (e.g. ``'tmy'``
+        or ``'tgy-2022'``).  The allowed values update periodically, so
+        consult the NSRDB references below for the current set of options.
+        Called ``names`` in NSRDB API.
+    time_step : int, {60}
+        time step in minutes. Must be 60 for typical year requests. Called
+        ``interval`` in NSRDB API.
+    parameters : list of str, optional
+        meteorological fields to fetch. If not specified, defaults to
+        ``pvlib.iotools.psm4.PARAMETERS``. See reference [2]_ for a list of
+        available fields. Alternatively, pvlib names may also be used (e.g.
+        'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`. To
+        retrieve all available fields, set ``parameters=[]``.
+    leap_day : bool, default : False
+        Include leap day in the results. Ignored for tmy/tgy/tdy requests.
+    full_name : str, default 'pvlib python'
+        optional
+    affiliation : str, default 'pvlib python'
+        optional
+    utc: bool, default : False
+        retrieve data with timestamps converted to UTC. False returns
+        timestamps in local standard time of the selected location
+    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, optional
+        Full API endpoint URL. If not specified, the PSM4 GOES TMY v4 URL is
+        used.
+    timeout : int, default 30
+        time in seconds to wait for server response before timeout
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see
+        :func:`pvlib.iotools.parse_nsrdb_psm4` for fields
+
+    Raises
+    ------
+    requests.HTTPError
+        if the request response status is not ok, then the ``'errors'`` field
+        from the JSON response or any error message in the content will be
+        raised as an exception, for example if the `api_key` was rejected or if
+        the coordinates were not found in the NSRDB
+
+    Notes
+    -----
+    The required NREL developer key, `api_key`, is available for free by
+    registering at the `NREL Developer Network <https://developer.nrel.gov/>`_.
+
+    .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
+        result in rejected requests.
+
+    .. warning:: PSM4 is limited to data found in the NSRDB, please consult
+        the references below for locations with available data. Additionally,
+        querying data with < 30-minute resolution uses a different API endpoint
+        with fewer available fields (see [4]_).
+
+    See Also
+    --------
+    pvlib.iotools.get_nsrdb_psm4_aggregated,
+    pvlib.iotools.get_nsrdb_psm4_conus, pvlib.iotools.get_nsrdb_psm4_full_disc,
+    pvlib.iotools.read_nsrdb_psm4,pvlib.iotools.parse_nsrdb_psm4
+
+    References
+    ----------
+
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `NSRDB GOES Tmy V4.0.0
+       <https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-tmy-v4-0-0-download/>`_
+    """
+    # The well know text (WKT) representation of geometry notation is strict.
+    # A POINT object is a string with longitude first, then the latitude, with
+    # four decimals each, and exactly one space between them.
+    longitude = ('%9.4f' % longitude).strip()
+    latitude = ('%8.4f' % latitude).strip()
+    # TODO: make format_WKT(object_type, *args) in tools.py
+
+    # convert to string to accomodate integer years being passed in
+    year = str(year)
+
+    # convert pvlib names in parameters to PSM4 convention
+    parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
+
+    # required query-string parameters for request to PSM4 API
+    params = {
+        'api_key': api_key,
+        'full_name': full_name,
+        'email': email,
+        'affiliation': affiliation,
+        'reason': PVLIB_PYTHON,
+        'mailing_list': 'false',
+        'wkt': 'POINT(%s %s)' % (longitude, latitude),
+        'names': year,
+        'attributes':  ','.join(parameters),
+        'leap_day': str(leap_day).lower(),
+        'utc': str(utc).lower(),
+        'interval': time_step
+    }
+    # request CSV download from NREL PSM4
+    if url is None:
+        url = PSM4_TMY_URL
+
+    response = requests.get(url, params=params, timeout=timeout)
+    if not response.ok:
+        # if the API key is rejected, then the response status will be 403
+        # Forbidden, and then the error is in the content and there is no JSON
+        try:
+            errors = response.json()['errors']
+        except JSONDecodeError:
+            errors = response.content.decode('utf-8')
+        raise requests.HTTPError(errors, response=response)
+    # the CSV is in the response content as a UTF-8 bytestring
+    # to use pandas we need to create a file buffer from the response
+    fbuf = io.StringIO(response.content.decode('utf-8'))
+    return parse_nsrdb_psm4(fbuf, map_variables)
+
+
+def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year='2023',
+                         time_step=60, parameters=PARAMETERS, leap_day=True,
+                         full_name=PVLIB_PYTHON, affiliation=PVLIB_PYTHON,
+                         utc=False, map_variables=True, url=None, timeout=30):
+    """
+    Retrieve NSRDB PSM4 timeseries weather data from the PSM4 NSRDB GOES CONUS
+    v4 API.
+
+    The NSRDB is described in [1]_ and the PSM4 NSRDB GOES CONUS v4 API is
+    described in [2]_,.
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    api_key : str
+        NREL Developer Network API key
+    email : str
+        NREL API uses this to automatically communicate messages back
+        to the user only if necessary
+    year : str, default '2023'
+        PSM4 API parameter specifing year (e.g. ``2023``) to download. The
+        allowed values update periodically, so consult the NSRDB reference
+        below for the current set of options. Called ``names`` in NSRDB API.
+    time_step : int, {60, 5, 15, 30}
+        time step in minutes. Called ``interval`` in NSRDB API.
+    parameters : list of str, optional
+        meteorological fields to fetch. If not specified, defaults to
+        ``pvlib.iotools.psm4.PARAMETERS``. See reference [2]_ for a list of
+        available fields. Alternatively, pvlib names may also be used (e.g.
+        'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`. To
+        retrieve all available fields, set ``parameters=[]``.
+    leap_day : bool, default : True
+        include leap day in the results
+    full_name : str, default 'pvlib python'
+        optional
+    affiliation : str, default 'pvlib python'
+        optional
+    utc: bool, default : False
+        retrieve data with timestamps converted to UTC. False returns
+        timestamps in local standard time of the selected location
+    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, optional
+        Full API endpoint URL. If not specified, the PSM4 GOES CONUS v4 URL is
+        used.
+    timeout : int, default 30
+        time in seconds to wait for server response before timeout
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see
+        :func:`pvlib.iotools.parse_nsrdb_psm4` for fields
+
+    Raises
+    ------
+    requests.HTTPError
+        if the request response status is not ok, then the ``'errors'`` field
+        from the JSON response or any error message in the content will be
+        raised as an exception, for example if the `api_key` was rejected or if
+        the coordinates were not found in the NSRDB
+
+    Notes
+    -----
+    The required NREL developer key, `api_key`, is available for free by
+    registering at the `NREL Developer Network <https://developer.nrel.gov/>`_.
+
+    .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
+        result in rejected requests.
+
+    .. warning:: PSM4 is limited to data found in the NSRDB, please consult
+        the references below for locations with available data. Additionally,
+        querying data with < 30-minute resolution uses a different API endpoint
+        with fewer available fields (see [4]_).
+
+    See Also
+    --------
+    pvlib.iotools.get_nsrdb_psm4_aggregated,
+    pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_full_disc,
+    pvlib.iotools.read_nsrdb_psm4, pvlib.iotools.parse_nsrdb_psm4
+
+    References
+    ----------
+
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `NSRDB GOES Conus V4.0.0
+       <https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-conus-v4-0-0-download/>`_
+    """
+    # The well know text (WKT) representation of geometry notation is strict.
+    # A POINT object is a string with longitude first, then the latitude, with
+    # four decimals each, and exactly one space between them.
+    longitude = ('%9.4f' % longitude).strip()
+    latitude = ('%8.4f' % latitude).strip()
+    # TODO: make format_WKT(object_type, *args) in tools.py
+
+    # convert to string to accomodate integer years being passed in
+    year = str(year)
+
+    # convert pvlib names in parameters to PSM4 convention
+    parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
+
+    # required query-string parameters for request to PSM4 API
+    params = {
+        'api_key': api_key,
+        'full_name': full_name,
+        'email': email,
+        'affiliation': affiliation,
+        'reason': PVLIB_PYTHON,
+        'mailing_list': 'false',
+        'wkt': 'POINT(%s %s)' % (longitude, latitude),
+        'names': year,
+        'attributes':  ','.join(parameters),
+        'leap_day': str(leap_day).lower(),
+        'utc': str(utc).lower(),
+        'interval': time_step
+    }
+    # request CSV download from NREL PSM4
+    if url is None:
+        url = PSM4_CON_URL
+
+    response = requests.get(url, params=params, timeout=timeout)
+    if not response.ok:
+        # if the API key is rejected, then the response status will be 403
+        # Forbidden, and then the error is in the content and there is no JSON
+        try:
+            errors = response.json()['errors']
+        except JSONDecodeError:
+            errors = response.content.decode('utf-8')
+        raise requests.HTTPError(errors, response=response)
+    # the CSV is in the response content as a UTF-8 bytestring
+    # to use pandas we need to create a file buffer from the response
+    fbuf = io.StringIO(response.content.decode('utf-8'))
+    return parse_nsrdb_psm4(fbuf, map_variables)
+
+
+def get_nsrdb_psm4_full_disc(latitude, longitude, api_key, email,
+                             year='2023', time_step=60,
+                             parameters=PARAMETERS, leap_day=True,
+                             full_name=PVLIB_PYTHON,
+                             affiliation=PVLIB_PYTHON, utc=False,
+                             map_variables=True, url=None, timeout=30):
+    """
+    Retrieve NSRDB PSM4 timeseries weather data from the PSM4 NSRDB GOES Full
+    Disc v4 API.
+
+    The NSRDB is described in [1]_ and the PSM4 NSRDB GOES Full Disc v4 API is
+    described in [2]_,.
+
+    Parameters
+    ----------
+    latitude : float or int
+        in decimal degrees, between -90 and 90, north is positive
+    longitude : float or int
+        in decimal degrees, between -180 and 180, east is positive
+    api_key : str
+        NREL Developer Network API key
+    email : str
+        NREL API uses this to automatically communicate messages back
+        to the user only if necessary
+    year : str, default '2023'
+        PSM4 API parameter specifing year (e.g. ``2023``) to download. The
+        allowed values update periodically, so consult the NSRDB reference
+        below for the current set of options. Called ``names`` in NSRDB API.
+    time_step : int, {60, 10, 30}
+        time step in minutes, must be 10, 30 or 60. Called ``interval`` in
+        NSRDB API.
+    parameters : list of str, optional
+        meteorological fields to fetch. If not specified, defaults to
+        ``pvlib.iotools.psm4.PARAMETERS``. See reference [2]_ for a list of
+        available fields. Alternatively, pvlib names may also be used (e.g.
+        'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`. To
+        retrieve all available fields, set ``parameters=[]``.
+    leap_day : bool, default : True
+        include leap day in the results
+    full_name : str, default 'pvlib python'
+        optional
+    affiliation : str, default 'pvlib python'
+        optional
+    utc: bool, default : False
+        retrieve data with timestamps converted to UTC. False returns
+        timestamps in local standard time of the selected location
+    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, optional
+        Full API endpoint URL. If not specified, the PSM4 GOES Full Disc v4
+        URL is used.
+    timeout : int, default 30
+        time in seconds to wait for server response before timeout
+
+    Returns
+    -------
+    data : pandas.DataFrame
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see
+        :func:`pvlib.iotools.parse_nsrdb_psm4` for fields
+
+    Raises
+    ------
+    requests.HTTPError
+        if the request response status is not ok, then the ``'errors'`` field
+        from the JSON response or any error message in the content will be
+        raised as an exception, for example if the `api_key` was rejected or if
+        the coordinates were not found in the NSRDB
+
+    Notes
+    -----
+    The required NREL developer key, `api_key`, is available for free by
+    registering at the `NREL Developer Network <https://developer.nrel.gov/>`_.
+
+    .. warning:: The "DEMO_KEY" `api_key` is severely rate limited and may
+        result in rejected requests.
+
+    .. warning:: PSM4 is limited to data found in the NSRDB, please consult
+        the references below for locations with available data. Additionally,
+        querying data with < 30-minute resolution uses a different API endpoint
+        with fewer available fields (see [4]_).
+
+    See Also
+    --------
+    pvlib.iotools.get_nsrdb_psm4_aggregated,
+    pvlib.iotools.get_nsrdb_psm4_tmy, pvlib.iotools.get_nsrdb_psm4_conus,
+    pvlib.iotools.read_nsrdb_psm4, pvlib.iotools.parse_nsrdb_psm4
+
+    References
+    ----------
+
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `NSRDB GOES Full Disc V4.0.0
+       <https://developer.nrel.gov/docs/solar/nsrdb/nsrdb-GOES-full-disc-v4-0-0-download/>`_
+    """
+    # The well know text (WKT) representation of geometry notation is strict.
+    # A POINT object is a string with longitude first, then the latitude, with
+    # four decimals each, and exactly one space between them.
+    longitude = ('%9.4f' % longitude).strip()
+    latitude = ('%8.4f' % latitude).strip()
+    # TODO: make format_WKT(object_type, *args) in tools.py
+
+    # convert to string to accomodate integer years being passed in
+    year = str(year)
+
+    # convert pvlib names in parameters to PSM4 convention
+    parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
+
+    # required query-string parameters for request to PSM4 API
+    params = {
+        'api_key': api_key,
+        'full_name': full_name,
+        'email': email,
+        'affiliation': affiliation,
+        'reason': PVLIB_PYTHON,
+        'mailing_list': 'false',
+        'wkt': 'POINT(%s %s)' % (longitude, latitude),
+        'names': year,
+        'attributes':  ','.join(parameters),
+        'leap_day': str(leap_day).lower(),
+        'utc': str(utc).lower(),
+        'interval': time_step
+    }
+    # request CSV download from NREL PSM4
+    if url is None:
+        url = PSM4_FUL_URL
+
+    response = requests.get(url, params=params, timeout=timeout)
+    if not response.ok:
+        # if the API key is rejected, then the response status will be 403
+        # Forbidden, and then the error is in the content and there is no JSON
+        try:
+            errors = response.json()['errors']
+        except JSONDecodeError:
+            errors = response.content.decode('utf-8')
+        raise requests.HTTPError(errors, response=response)
+    # the CSV is in the response content as a UTF-8 bytestring
+    # to use pandas we need to create a file buffer from the response
+    fbuf = io.StringIO(response.content.decode('utf-8'))
+    return parse_nsrdb_psm4(fbuf, map_variables)
+
+
+def parse_nsrdb_psm4(fbuf, map_variables=True):
+    """
+    Parse an NSRDB PSM4 weather file (formatted as SAM CSV).
+
+    The NSRDB is described in [1]_ and the SAM CSV format is described in [2]_.
+
+    Parameters
+    ----------
+    fbuf: file-like object
+        File-like object containing data to read.
+    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
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see notes for fields
+
+    Notes
+    -----
+    The return is a tuple with two items. The first item is a dataframe with
+    the PSM4 timeseries data.
+
+    The second item is a dictionary with metadata from NREL PSM4 about the
+    record containing the following fields:
+
+    * Source
+    * Location ID
+    * City
+    * State
+    * Country
+    * Latitude
+    * Longitude
+    * Time Zone
+    * Elevation
+    * Local Time Zone
+    * Clearsky DHI Units
+    * Clearsky DNI Units
+    * Clearsky GHI Units
+    * Dew Point Units
+    * DHI Units
+    * DNI Units
+    * GHI Units
+    * Solar Zenith Angle Units
+    * Temperature Units
+    * Pressure Units
+    * Relative Humidity Units
+    * Precipitable Water Units
+    * Wind Direction Units
+    * Wind Speed Units
+    * Cloud Type -15
+    * Cloud Type 0
+    * Cloud Type 1
+    * Cloud Type 2
+    * Cloud Type 3
+    * Cloud Type 4
+    * Cloud Type 5
+    * Cloud Type 6
+    * Cloud Type 7
+    * Cloud Type 8
+    * Cloud Type 9
+    * Cloud Type 10
+    * Cloud Type 11
+    * Cloud Type 12
+    * Fill Flag 0
+    * Fill Flag 1
+    * Fill Flag 2
+    * Fill Flag 3
+    * Fill Flag 4
+    * Fill Flag 5
+    * Surface Albedo Units
+    * Version
+
+    Examples
+    --------
+    >>> # Read a local PSM4 file:
+    >>> with open(filename, 'r') as f:  # doctest: +SKIP
+    ...     df, metadata = iotools.parse_nsrdb_psm4(f)  # doctest: +SKIP
+
+    See Also
+    --------
+    pvlib.iotools.read_nsrdb_psm4, pvlib.iotools.get_psm4
+
+    References
+    ----------
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `Standard Time Series Data File Format
+       <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
+    """
+    # The first 2 lines of the response are headers with metadata
+    metadata_fields = fbuf.readline().split(',')
+    metadata_fields[-1] = metadata_fields[-1].strip()  # strip trailing newline
+    metadata_values = fbuf.readline().split(',')
+    metadata_values[-1] = metadata_values[-1].strip()  # strip trailing newline
+    metadata = dict(zip(metadata_fields, metadata_values))
+    # the response is all strings, so set some metadata types to numbers
+    metadata['Local Time Zone'] = int(metadata['Local Time Zone'])
+    metadata['Time Zone'] = int(metadata['Time Zone'])
+    metadata['Latitude'] = float(metadata['Latitude'])
+    metadata['Longitude'] = float(metadata['Longitude'])
+    metadata['Elevation'] = int(metadata['Elevation'])
+    # get the column names so we can set the dtypes
+    columns = fbuf.readline().split(',')
+    columns[-1] = columns[-1].strip()  # strip trailing newline
+    # Since the header has so many columns, excel saves blank cols in the
+    # data below the header lines.
+    columns = [col for col in columns if col != '']
+    dtypes = dict.fromkeys(columns, float)  # all floats except datevec
+    dtypes.update(Year=int, Month=int, Day=int, Hour=int, Minute=int)
+    dtypes['Cloud Type'] = int
+    dtypes['Fill Flag'] = int
+    data = pd.read_csv(
+        fbuf, header=None, names=columns, usecols=columns, dtype=dtypes,
+        delimiter=',', lineterminator='\n')  # skip carriage returns \r
+    # the response 1st 5 columns are a date vector, convert to datetime
+    dtidx = pd.to_datetime(
+        data[['Year', 'Month', 'Day', 'Hour', 'Minute']])
+    # in USA all timezones are integers
+    tz = 'Etc/GMT%+d' % -metadata['Time Zone']
+    data.index = pd.DatetimeIndex(dtidx).tz_localize(tz)
+
+    if map_variables:
+        data = data.rename(columns=VARIABLE_MAP)
+        metadata['latitude'] = metadata.pop('Latitude')
+        metadata['longitude'] = metadata.pop('Longitude')
+        metadata['altitude'] = metadata.pop('Elevation')
+
+    return data, metadata
+
+
+def read_nsrdb_psm4(filename, map_variables=True):
+    """
+    Read an NSRDB PSM4 weather file (formatted as SAM CSV).
+
+    The NSRDB is described in [1]_ and the SAM CSV format is described in [2]_.
+
+    Parameters
+    ----------
+    filename: str or path-like
+        Filename of a file containing data to read.
+    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
+        timeseries data from NREL PSM4
+    metadata : dict
+        metadata from NREL PSM4 about the record, see
+        :func:`pvlib.iotools.parse_nsrdb_psm4` for fields
+
+    See Also
+    --------
+    pvlib.iotools.parse_nsrdb_psm4, pvlib.iotools.get_psm4
+
+    References
+    ----------
+    .. [1] `NREL National Solar Radiation Database (NSRDB)
+       <https://nsrdb.nrel.gov/>`_
+    .. [2] `Standard Time Series Data File Format
+       <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
+    """
+    with open(str(filename), 'r') as fbuf:
+        content = parse_nsrdb_psm4(fbuf, map_variables)
+    return content