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, server='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.

  • server (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.

Raises

requests.HTTPError – If the request is invalid, then an XML file is returned by the CAMS service and the error message will be raised as an exception.

References

1(1,2,3)

CAMS solar radiation documentation

2(1,2,3)

CAMS Radiation Automatic Access (SoDa)

3

A. R. Jensen et al., pvlib iotools — Open-source Python functions for seamless access to solar irradiance data. Solar Energy. 2023. Vol 266, pp. 112092. DOI: 10.1016/j.solener.2023.112092