pvlib.iotools.get_cams#

pvlib.iotools.get_cams(latitude, longitude, start, end, email, identifier='mcclear', altitude=None, time_step='1h', time_ref='UT', verbose=False, integrated=False, label=None, map_variables=True, url='api.soda-solardata.com', timeout=30)[source]#

Retrieve irradiance and clear-sky time series from CAMS.

Time-series of radiation and/or clear-sky global, beam, and diffuse radiation from CAMS (see [1]). Data is retrieved from SoDa [2].

Time coverage: 2004-01-01 to two days ago

Access: free, but requires registration, see [2]

Requests: max. 100 per day

Geographical coverage: worldwide for CAMS McClear and approximately -66° to 66° in latitude and -66° to 180° in longitude for CAMS Radiation. See [3] for a map of the geographical coverage.

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 (datetime-like) – First day of the requested period
end (datetime-like) – Last day of the requested period
email (str) – Email address linked to a SoDa account
identifier ({'mcclear', 'cams_radiation'}) – Specify whether to retrieve CAMS Radiation or McClear parameters
altitude (float, optional) – Altitude in meters. If not specified, then the altitude is determined from the NASA SRTM database
time_step (str, {'1min', '15min', '1h', '1d', '1M'}, default: '1h') – Time step of the time series, either 1 minute, 15 minute, hourly, daily, or monthly.
time_ref (str, {'UT', 'TST'}, default: 'UT') – ‘UT’ (universal time) or ‘TST’ (True Solar Time)
verbose (boolean, default: False) – Verbose mode outputs additional parameters (aerosols). Only available for 1 minute and universal time. See [1] for parameter description.
integrated (boolean, default False) – Whether to return radiation parameters as integrated values (Wh/m^2) or as average irradiance values (W/m^2) (pvlib preferred units)
label ({'right', 'left'}, optional) – Which bin edge label to label time-step with. The default is ‘left’ for all time steps except for ‘1M’ which has a default of ‘right’.
map_variables (bool, default: True) – When true, renames columns of the DataFrame to pvlib variable names where applicable. See variable VARIABLE_MAP.
url (str, default: pvlib.iotools.sodapro.URL) – Base url of the SoDa Pro CAMS Radiation API.
timeout (int, default: 30) – Time in seconds to wait for server response before timeout

Returns:

data (pandas.DataFrame) – Timeseries data, see Notes for columns
metadata (dict) – Metadata of the requested time-series

Notes

In order to use the CAMS services, users must register for a free SoDa account using an email address [2].

The returned data DataFrame includes the following fields:

Key, mapped key	Format	Description
Mapped field names are returned when the map_variables argument is True
Observation period	str	Beginning/end of time period
TOA, ghi_extra	float	Horizontal radiation at top of atmosphere
Clear sky GHI, ghi_clear	float	Clear sky global radiation on horizontal
Clear sky BHI, bhi_clear	float	Clear sky beam radiation on horizontal
Clear sky DHI, dhi_clear	float	Clear sky diffuse radiation on horizontal
Clear sky BNI, dni_clear	float	Clear sky beam radiation normal to sun
GHI, ghi†	float	Global horizontal radiation
BHI, bhi†	float	Beam (direct) radiation on horizontal
DHI, dhi†	float	Diffuse horizontal radiation
BNI, dni†	float	Beam (direct) radiation normal to the sun
Reliability†	float	Reliable data fraction in summarization

†Parameters only returned if identifier=’cams_radiation’. For description of additional output parameters in verbose mode, see [1].

Note that it is recommended to specify the latitude and longitude to at least the fourth decimal place.

Variables corresponding to standard pvlib variables are renamed, e.g. sza becomes solar_zenith. See variable VARIABLE_MAP for the complete mapping.

For large geospatial areas, CAMS offers a pre-calculated gridded dataset [4] over land and coastal areas. This dataset may not include the most recent data coverage and may not be based on the most recent CAMS version. This dataset is not available through pvlib.