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.

  • 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


  • data (pandas.DataFrame) – Timeseries data, see Notes for columns

  • metadata (dict) – Metadata of the requested time-series


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



Mapped field names are returned when the map_variables argument is True

Observation period


Beginning/end of time period

TOA, ghi_extra


Horizontal radiation at top of atmosphere

Clear sky GHI, ghi_clear


Clear sky global radiation on horizontal

Clear sky BHI, bhi_clear


Clear sky beam radiation on horizontal

Clear sky DHI, dhi_clear


Clear sky diffuse radiation on horizontal

Clear sky BNI, dni_clear


Clear sky beam radiation normal to sun

GHI, ghi†


Global horizontal radiation

BHI, bhi†


Beam (direct) radiation on horizontal

DHI, dhi†


Diffuse horizontal radiation

BNI, dni†


Beam (direct) radiation normal to the sun



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.


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.



CAMS solar radiation documentation


CAMS Radiation Automatic Access (SoDa)


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