pvlib.iotools.get_psm3#

pvlib.iotools.get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60, attributes=('air_temperature', 'dew_point', 'dhi', 'dni', 'ghi', 'surface_albedo', 'surface_pressure', 'wind_direction', 'wind_speed'), leap_day=None, full_name='pvlib python', affiliation='pvlib python', map_variables=None, url=None, timeout=30)[source]#

Retrieve NSRDB PSM3 timeseries weather data from the PSM3 API. The NSRDB is described in 1 and the PSM3 API is described in 2, 3, and 4.

Changed in version 0.9.0: The function now returns a tuple where the first element is a dataframe and the second element is a dictionary containing metadata. Previous versions of this function had the return values switched.

Changed in version 0.10.0: The default endpoint for hourly single-year datasets is now v3.2.2. The previous datasets can still be accessed (for now) by setting the url parameter to the original API endpoint ("https://developer.nrel.gov/api/nsrdb/v2/solar/psm3-download.csv").

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

  • names (str, default 'tmy') – PSM3 API parameter specifing year (e.g. 2020) or TMY variant to download (e.g. 'tmy' or 'tgy-2019'). The allowed values update periodically, so consult the NSRDB references below for the current set of options.

  • interval (int, {60, 5, 15, 30}) – interval size in minutes, must be 5, 15, 30 or 60. Must be 60 for typical year requests (i.e., tmy/tgy/tdy).

  • attributes (list of str, optional) – meteorological fields to fetch. If not specified, defaults to pvlib.iotools.psm3.ATTRIBUTES. See references 2, 3, and 4 for lists of available fields. Alternatively, pvlib names may also be used (e.g. ‘ghi’ rather than ‘GHI’); see REQUEST_VARIABLE_MAP. To retrieve all available fields, set attributes=[].

  • leap_day (boolean, default False) – include leap day in the results. Only used for single-year requests (i.e., it is ignored for tmy/tgy/tdy requests).

  • full_name (str, default 'pvlib python') – optional

  • affiliation (str, default 'pvlib python') – optional

  • map_variables (boolean, optional) – When true, renames columns of the Dataframe to pvlib variable names where applicable. See variable VARIABLE_MAP.

  • url (str, optional) – API endpoint URL. If not specified, the endpoint is determined from the names and interval parameters.

  • timeout (int, default 30) – time in seconds to wait for server response before timeout

Returns

  • data (pandas.DataFrame) – timeseries data from NREL PSM3

  • metadata (dict) – metadata from NREL PSM3 about the record, see pvlib.iotools.parse_psm3() 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.

Warning

The “DEMO_KEY” api_key is severely rate limited and may result in rejected requests.

Warning

PSM3 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).

References

1

NREL National Solar Radiation Database (NSRDB)

2(1,2)

Physical Solar Model (PSM) v3.2.2

3(1,2)

Physical Solar Model (PSM) v3 TMY

4(1,2,3)

Physical Solar Model (PSM) v3 - Five Minute Temporal Resolution