Application Program Interface (API)


PSG allows to perform operations remotely by employing a versatile online Application Program Interface (API). The API operates by sending a configuration file to the PSG servers, that can modified on the local machine as needed. Upon reception of the configuration file, PSG will compute the spectra and send back the planetary spectra. The great value of the API is that the user does not need to install / update the radiative transfer modules and databases on his/her computer, and by simply performing a 'curl' command, the user will run the simulations on high-performance NASA servers.
 
The configuration file is a relaxed form of XML (eXtensible Markup Language), the now preferred file type across applications. The spectra is provided in standard ASCII columns. The resulting units for the columns can be defined with the configuration XML file, while which type of data to provide (e.g., radiance, transmittance, noise) is provided by a POST command.
 
The communication with the server is performed via HTTPS, and this can be implemented via the 'curl' terminal command. A single line of 'curl', in which the user inputs are provided via a config.txt (example) will lead to spectra. The figure below better explains the inner workings of the PSG modules, and how the user can enable / disable the different modules, and request for different spectral outputs.
 
Application Program Interface (API)
Application Program Interface: PSG can be called from a local machine via the 'curl' command that employs the HTTP protocol for establishing the communication between the local machine and the PSG servers. The user sends a XML configuration file, and receives different type of spectral results (str, tel, srf, trn, atm, rad, noi), all standarized as text ASCII tables. The API will call the required modules (geometry, atmosphere, continuum, pumas/cem, generator) in a sequencial order, yet the user can also enable / disable modules as needed. Examples are presented in the next section.

Calling the API from the local machine


In order to compute spectra, one first needs to create / modify a PSG configuration file. The user can choose to edit this file with any text editor or scripting language.
 
1) Obtain a template configuration file (e.g., config.txt). The easiest way to obtain a configuration file is by parameterizing PSG via the web interface until a desired spectrum is obtained. On the main page of PSG, then click on "Download config-file", this will download the XML configuration file. A generic template can be also downloaded here.
 
2) Modify the config.txt configuration file using a text-editor, or using any scripting / programming language. In order to better understand what each parameter means, please refer to the PSG documentation.
 
3) Open a terminal window and type the following command:
 
curl --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
4) By default, the API will run all PSG modules employing this configuration file, and will return the total radiance spectra (rad file). As shown in the figure above, one can run only certain modules and request for a different type of spectral output. This is achieved by providing several POST keywords (see table below). For instance:
 
To return planetary transmittances without the header information:
curl -d type=trn -d whdr=n --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
To return only stellar transmittances (the API will only run the module 'continuum'):
curl -d type=str --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
5) With the API, the user can also compute ephmerides and/or atmospheric parameters. For instance:
 
a) Create a text file config.txt with this content:
<OBJECT-DATE>2017/01/15 14:30
<OBJECT>Mars
<GEOMETRY-REF>MRO

 
b) Call the API with this command:
curl -d type=cfg -d wephm=y -d watm=y --data-urlencode file@config.txt https://psg.gsfc.nasa.gov/api.php
 
 
IDL Matlab Python Matlab Fortran/td> Bash
IDL driver package
(telluric, planets, exoplanet transits)
MATLAB driver package
(under development)
Python driver package
(under development, DiGregorio)
C/C++ driver package
(under development)
Fortran driver package
(under development)
Bash driver package
(telluric, planets, exoplanet transits)

 

Types of planetary spectra and special keywords


Requested spectra (type keyword)
radIntegrated fluxes, incorporating all planetary and stellar transmittances, and considering the specific instrument / observatory parameters. This file is computed by the module generator. This is the default output setting.
noiSynthetic observational noise, including the noise introduced by the planet itself, its star (if present within the field), background sources (e.g., exozodii, local zodiacal dust, CMB), the terrestrial atmosphere (if observing from ground), and the instrument performance. This file is computed by the module generator.
trnIntegrated planetary transmittance spectra, including all geometry considerations and requested atmospheric parameters. This file is computed by the module PUMAS only.
atmIntegrated planetary fluxes as observed at the planet in units of [W m-2 sr-1 um-1]. This file is computed by the modules PUMAS and CEM.
strStellar transmittance spectrum. This file is computed by the module continuum.
telTerrestrial transmittance spectrum. This file is computed by the module continuum.
srfSurface reflectance and emissivity spectra. This file is computed by the module continuum.
cfgThe API will return the updated configuration file. This file is computed by the modules geometry and atmosphere.
allThis keyword will return all the resulting spectra, and the configuration file.

 
Special keywords
wgeoThe geometry module computes the observational angles (GEOMETRY-SOLAR-ANGLE, GEOMETRY-OBS-ANGLE) and the beam/planet ratio (GEOMETRY-PLANET-FRACTION) employing the geometry information provided by the user in the XML configuration file. For exoplanets, it also computes the planet transit factor (GEOMETRY-STAR-FRACTION), and the planet-star distance (GEOMETRY-STAR-DISTANCE). This information is then saved into the configuration file to be used by the other modules. The default is wgeo=y, yet one can disable this computation with wgeo=n.
wephmThis keyword enables the calculation of ephemeris parameters based on the object name and the provided date:
  • wephm=y computes ephemeris for the date provided.
  • wephm=N computes ephemeris for the current date/time.
  • wephm=T for exoplanets, it searches the next primary transit event, while for Solar System bodies it computes the ephemeris for [date - one day].
  • wephm=S for exoplanets, it searches the next secondary transit event, while for Solar System bodies it computes the ephemeris for [date + one day].
  • wephm=P for exoplanets, it searches the next periastron event.
  • wephm=n disables the ephemerides module (default).
watmThis keyword enables / disables the atmosphere module - Default watm=n.
whdrThis keyword allows to disable outputing the header information - Default whdr=y.

 

Full list of parameters accepted by PSG


Type Keyword Range Description
OBJECT S50 Object type (e.g., Exoplanet) or object name for the main bodies in the Solar System
OBJECT-NAME S50 Object name
OBJECT-DATE S20 Date of the observation (yyyy/mm/dd hh:mm) in Universal time [UT]
OBJECT-DIAMETER 1e-2 1e8 Diameter of the object [km]
OBJECT-GRAVITY 0 1e35 Gravity/density/mass of the object
OBJECT-GRAVITY-UNIT S10 Unit for the OBJECT-GRAVITY field, g:'Surface gravity [m/s2]', rho:'Mean density [g/cm3]', or kg:'Total mass [kg]'
OBJECT-STAR-DISTANCE 0 1e5 Distance of the planet to its parent star [AU]
OBJECT-STAR-VELOCITY -1e4 1e4 Velocity of the planet with respect to its parent star (in the observer-planet vector) [km/s]
OBJECT-SOLAR-LONGITUDE -360 360 Sub-solar east longitude [degrees] / For exoplanets, longitude of periapse [degrees]
OBJECT-SOLAR-LATITUDE -90 90 Sub-solar latitude [degrees] / For exoplanets, orbital eccentricity
OBJECT-SEASON 0 360 Angular parameter (season/phase) that defines the position of the planet moving along its Keplerian orbit, where 0:'Northern Hemisphere Spring Equinox', 90:'Northern Hemisphere Summer Solstice', 180:'Northern Hemisphere Autumn Equinox', 270:'Northern hemisphere Winter Solstice' [degrees]
OBJECT-STAR-TYPE S1 Stellar type of the parent star [O/B/A/F/G/K/M]
OBJECT-STAR-TEMPERATURE 1 1e5 Temperature of the parent star [K]
OBJECT-STAR-RADIUS 1e-3 1e8 Radius of the parent star [Rsun]
OBJECT-OBS-LONGITUDE -360 360 Sub-observer east longitude [degrees]
OBJECT-OBS-LATITUDE -90 90 Sub-observer latitude [degrees]
OBJECT-OBS-VELOCITY -1e4 1e4 Relative velocity between the observer and the object [km/s]
OBJECT-PERIOD 0 1e8 This field is computed by the geometry module - Orbital period [days]
GEOMETRY S20 Type of observing geometry, Telescope / Nadir / Limb / Solar / Stellar / Lookingup / LookingSolar
GEOMETRY-REF S50 Reference geometry (e.g., ExoMars, Maunakea), default is user defined or 'User'
GEOMETRY-OFFSET-NS -1e6 1e6 Right-ascension offset with respect to the sub-observer location
GEOMETRY-OFFSET-EW -1e6 1e6 Declination offset with respect to the sub-observer location
GEOMETRY-OFFSET-UNIT S10 Unit of the GEOMETRY-OFFSET field, arcsec / arcmin / degree / km / diameter
GEOMETRY-OBS-ALTITUDE 0 1e8 Distance between the observer and the surface of the planet
GEOMETRY-ALTITUDE-UNIT S10 Unit of the GEOMETRY-OBS-ALTITUDE field, AU / km / diameter and pc:'parsec'
GEOMETRY-USER-PARAM 0 1000 Parameter for the selected geometry, for Nadir / Lookingup this field indicates the zenith angle [degrees], for limb / occultations this field indicates the atmospheric height [km] being sampled
GEOMETRY-STELLAR-TYPE S1 For stellar occultations, this field indicates the type of the occultation star [O/B/A/F/G/K/M]
GEOMETRY-STELLAR-TEMPERATURE 1 1e5 For stellar occultations, this field indicates the temperature [K] of the occultation star
GEOMETRY-STELLAR-MAGNITUDE -30 30 For stellar occultations, this field indicates the brightness [magnitude] of the occultation star
GEOMETRY-OBS-ANGLE 0 360 This field is computed by the geometry module - It indicates the angle between the observer and the planetary surface
GEOMETRY-SOLAR-ANGLE 0 360 This field is computed by the geometry module - It indicates the angle between the Sun and the planetary surface
GEOMETRY-PHASE -360 360 This field is computed by the geometry module - It indicates the phase between the Sun and observer
GEOMETRY-PLANET-FRACTION 0 1 This field is computed by the geometry module - It indicates how much the beam fills the planetary area (1:maximum)
GEOMETRY-STAR-FRACTION 0 1 This field is computed by the geometry module - It indicates how much the beam fills the parent star (1:maximum)
GEOMETRY-STAR-DISTANCE -1 1e8 This field is computed by the geometry module - It indicates the projected distance between the beam and the parent star
ATMOSPHERE-STRUCTURE S100 The structure of the atmosphere, None / Equilibrium:'Hydrostatic equilibrium' / Coma:'Cometary expanding coma'
ATMOSPHERE-PRESSURE 0 1e35 For equilibrium atmospheres, this field defines the surface pressure; while for cometary coma, this field indicates the gas production rate
ATMOSPHERE-PUNIT S20 The unit of the ATMOSPHERE-PRESSURE field, Pa:Pascal / bar / kbar / mbar / ubar / at / atm / torr / psi / gas:'molecules / second' / gasau:'molecules / second at rh=1AU'
ATMOSPHERE-TEMPERATURE 1 1e4 For atmospheres without a defined P/T profile, this field indicates the temperature across all altitudes
ATMOSPHERE-WEIGHT 1 1e3 Molecular weight of the atmosphere [g/mol]
ATMOSPHERE-NGAS 0 20 Number of gases to include in the simulation
ATMOSPHERE-GAS S300 Name of the gases to include in the simulation, e.g 'H2O,CO2'
ATMOSPHERE-TYPE S300 Sub-type of the gases, e.g. 'HIT[1],HIT[2]'
ATMOSPHERE-ABUN S300 Abundance of gases. The values can be assumed to be same across all altitudes/layers [%,ppmv,ppbv,pptv,m-2], or as a multiplier [scaler] to the provided vertical profile (see ATMOSPHERE-LAYERS-MOLECULES)
ATMOSPHERE-UNIT S300 Unit of the ATMOSPHERE-ABUN field, % / ppmv / ppbv / pptv / m2:'molecules/m2' / scl:'scaler of profile'
ATMOSPHERE-TAU S300 For expanding cometary coma, this field indicates the photodissociation lifetime of the molecules [s]
ATMOSPHERE-NAERO 0 20 Number of aerosols to include in the simulation
ATMOSPHERE-AEROS S300 Name of the aerosols to include in the simulation
ATMOSPHERE-ATYPE S300 Sub-type of the aerosols
ATMOSPHERE-AABUN S300 Abundance of aerosols. The values can be assumed to be same across all altitudes/layers [%,ppm,ppb,ppt,Kg/m2], or as a multiplier [scaler] to the provided vertical profile (see ATMOSPHERE-LAYERS-MOLECULES)
ATMOSPHERE-AUNIT S300 Unit of the ATMOSPHERE-AABUN field, % / ppmv / ppbv / pptv / m2:'molecules/m2' / scl:'scaler of profile'
ATMOSPHERE-ASIZE S300 Effective radius of the aerosol particles [um]
ATMOSPHERE-NMAX 0 100 When performing scattering aerosols calculations, this parameter indicates the number of n-stream pairs - Use 0 for extinction calculations
ATMOSPHERE-LMAX 0 100 When performing scattering aerosols calculations, this parameter indicates the number of scattering Legendre polynomials used for describing the phase function - Use 0 for extinction calculations
ATMOSPHERE-DESCRIPTION S200 Description establishing the source/reference for the vertical profile
ATMOSPHERE-LAYERS 0 999 Number of layers of the atmospheric vertical profile
ATMOSPHERE-LAYERS-MOLECULES S500 Molecules quantified by the vertical profile
ATMOSPHERE-LAYER S500 Values for that specific layer, Pressure[bar] / Temperature[K] / gases[mol/mol] / aerosols [kg/kg]
SURFACE-TEMPERATURE 0 1e5 Temperature of the surface [K]
SURFACE-ALBEDO 0 1.0 Albedo the surface [0:non-reflectance, 1:fully-reflective]
SURFACE-EMISSIVITY 0 1.0 Emissivity of the surface [0:non-emitting, 1:perfect-emitter]
SURFACE-PHASEG -1.0 1.0 One-term Henyey-Greenstein g-factor [0:isotropic, -1:backward scatterer, +1:forward scatterer]
SURFACE-GAS-RATIO 0 1e3 For expanding cometary coma, this value indicates an scaling value for the dust in the coma [1:typical dust/gas ratio]
SURFACE-NSURF 0 20 Number of components describing the surface properties [areal mixing]
SURFACE-SURF S300 Name of surface components to be included in the simulation
SURFACE-TYPE S300 Sub-type of the surface components
SURFACE-ABUN S300 Relative abundance of the surface components
SURFACE-UNIT S300 Unit of the SURFACE-ABUN field, % / ppm / ppv
SURFACE-THICK S300 Thickness for each surface component [um]
GENERATOR-RANGE1 1e-5 1e7 Lower spectral range for the simulation
GENERATOR-RANGE2 1e-5 1e7 Upper spectral range for the simulation
GENERATOR-RANGEUNIT S10 Unit of the GENERATOR-RANGE fields, um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
GENERATOR-RESOLUTION 1e-6 1e8 Spectral resolution for the simulation. PSG assumes that the sampling resolution is equal is to the instrumental resolution, yet radiative transfer resolutions are always performed at the necessary/higher resolutions in order to accurately describe the lineshapes
GENERATOR-RESOLUTIONUNIT S10 Unit of the GENERATOR-RESOLUTION field, RP:'Resolving power' / um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
GENERATOR-GAS-MODEL S1 Flag indicating whether to include molecular signatures as generated with PUMAS or CEM [Y/N]
GENERATOR-CONT-MODEL S1 Flag indicating whether to include continuum signatures as generated by the surface, the star (when in the field) and dust/nucleus (when synthesizing comets) [Y/N]
GENERATOR-CONT-STELLAR S1 Flag indicating whether to include stellar absorption signatures in the reflected sunlight / stellar spectra [Y/N]
GENERATOR-TRANS-SHOW S1 Flag indicating whether we are synthesizing planetary spectra (not of Earth) as observed with a ground-based telescope. This flag will ensure that the noise module properly includes telluric signatures.
GENERATOR-TRANS-APPLY S1 Flag indicating whether to show the spectra divided by the telluric transmittance [N], or as observed and affected by transmittance [Y]
GENERATOR-TRANS S20 Keyword [SS-WW] indicating the site [SS] and water abundance [WW]. Values of SS are 00:'0m (sea level)', 01:'2,600m (8,500 feet)', 02:'4,200m (14,000 feet)', 03:'14,000m (46,000 feet)', 04:'35,000m (120,000 feet)'. Values of WW are 00:'10% tropical', 01:'30% tropical', 02:'70% tropical', 03:'100% tropical'
GENERATOR-RADUNITS S20 Radiation unit for the generated spectra, see full list of permitted keywords in the 'Modeling > Radiation Units' section
GENERATOR-LOGRAD S1 Flag indicating whether to show the spectra employing a logarithmic scale
GENERATOR-TELESCOPE S10 Type of telescope, SINGLE:'single dish telescope / instrument' / ARRAY:'Interferometric array' / CORONA:'Coronagraph'
GENERATOR-BEAM 1e-3 1e6 Full width half-maximum (FWHM) of the instrument's beam
GENERATOR-BEAM-UNIT S20 Unit of the GENERATOR-BEAM field, arcsec / arcmin / degree / km / diameter:'beamsize in terms of the planet's diameter' / diffrac:'defined by the telescope diameter and center wavelength'
GENERATOR-DIAMTELE 1e-5 1e5 Diameter of the main reflecting surface of the telescope / instrument [m]
GENERATOR-TELESCOPE1 1e-20 1000 For interferometers, the number of telescopes; for coronagraphs, the instrument's constrast
GENERATOR-TELESCOPE2 0.0 1e20 For coronagraphic observations, the exozodi level
GENERATOR-TELESCOPE3 0.1 100 For coronagraphic observations, the inner working angle (IWA) in units of [L/D]
GENERATOR-NOISE S20 Keyword identifying the noise model to consider, NO:'None' / TRX:'Receiver temperature / radio' / RMS:'Constant noise in radiation units' / BKG:'Constant noise with added background' / NEP:'Power equivalent noise detector model' / D*:'Detectability noise detector model' / CCD:'Image sensor'
GENERATOR-NOISETIME 0.0 1e7 Exposure time per frame [sec]
GENERATOR-NOISEFRAMES 1 1e5 Number of exposures
GENERATOR-NOISEPIXELS 1 1e9 Total number of pixels that encompass the beam (GENERATOR-BEAM) and the spectral unit (GENERATOR-RESOLUTION)
GENERATOR-NOISE1 0.0 1e20 First noise model parameter - For RMS, 1-sigma noise; for TRX, the receiver temperature; for BKG, the 1-sigma noise; for NEP, the sensitivity in W/sqrt(Hz); for DET, the sensitivity in cm.sqrt(Hz)/W; for CCD, the read noise [e-]
GENERATOR-NOISE2 0.0 1e20 Second noise model parameter - For RMS, not used; for TRX, the sideband g-factor; for BKG, the not used; for NEP, not used; for DET, the pixel size [um]; for CCD, the dark rate [e-/s]
GENERATOR-NOISEOEFF 0.0 1.0 Total throughput of the telescope+instrument, from photons arriving to the main mirror to photons being quantified by the detector [0:none to 1:perfect]. The user can provide wavelength dependent values as neff@wavelength[um] (e.g., '0.087@2.28,0.089@2.30,0.092@2.31,0.094@2.32,...')
GENERATOR-NOISEOEMIS 0.0 1.0 Emissivity of the telescope+instrument optics [0 to 1]
GENERATOR-NOISEOTEMP 0.0 1e4 Temperature of the telescope+instrument optics [K]
GENERATOR-INSTRUMENT S500 Text describing if an instrument template was used to define the GENERATOR parameters
RETRIEVAL-RANGEUNIT S10 Spectral unit of the user-provided data for the retrieval, um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
RETRIEVAL-RESOLUTION 1e-6 1e8 Instrument's spectral resolution [FWHM] of the user-provided data. This value is independent of the sampling rate of the data, and refers to the actual spectral resolution of the instrument.
RETRIEVAL-RESOLUTIONUNIT S10 Unit of the RETRIEVAL-RESOLUTION field, RP:'Resolving power' / um / nm / mm / An:'Angstrom' / cm:'Wavenumber [cm-1]' / MHz / GHz / kHz
RETRIEVAL-FLUXSCALER 0 1E30 Scaling value to be applied to all fluxes of the user-provided data file.
RETRIEVAL-FREQSHIFT -1e5 1e5 Frequency/wavelength shift to be applied to the data.
RETRIEVAL-FLUXLABELS S100 Labels for the columns of the data file.
RETRIEVAL-FITGAIN -1 2 Polynomical degree of the instrument's gain function, -1:None, 0:Constant, 1:Sloped, 2:Quadratic, etc.
RETRIEVAL-REMOVEOFFSET -1 2 Polynomical degree of the residual offset, -1:None, 0:Constant, 1:Sloped, 2:Quadratic, etc.
RETRIEVAL-REMOVEFRINGE 0 9 Maximum number of spectral fringes to be removed from the data.
RETRIEVAL-FITSTELLAR S1 Flag indicating whether to fit the intensity of the solar/stellar features [Y/N]
RETRIEVAL-FITFREQ S1 Flag indicating whether to refine the spectral calibration [Y/N]
RETRIEVAL-FITRESOLUTION S1 Flag indicating whether to fit the spectral resolution [Y/N]
RETRIEVAL-FITTELLURIC S1 Flag indicating whether to refine the telluric features [Y/N]. This is done by perturbing the selected telluric column/water abundances.
RETRIEVAL-NVARS 0 9 Number of model variables to be retrieved.
RETRIEVAL-VARIABLES S300 Name of the variables of the retrieval (comma separated).
RETRIEVAL-VALUES S300 A-priori values of the retrieval parameters (comma separated).
RETRIEVAL-MIN S300 Lower boundary permitted for each parameter (comma separated).
RETRIEVAL-MAX S300 Upper boundary permitted for each parameter (comma separated).
RETRIEVAL-UNITS S300 Magnitude unit of the a-priori and boundary entries (comma separated).
RETRIEVAL-STATUS S30 Flag indicating the status of the retrieval suite (e.g., RUNNING, OK)