October 21, 2022

eDEx API Documentation


CASSIOPE SPACECRAFT (Swarm-E)
PROCESSED DATA HANDBOOK

eDEx API Documentation *BETA*


*Beta development is currently ongoing to improve the user experience*

Based on simple REST principles, the eDEx Web API endpoints return JSON filename data based on the given filters and constraints from the eDEx database, which can then be used to request the pre-packaged products to be sent to you via email. We recognize that not on data product requests are large enough that they warrant this pre-packaging and email process, therefore we will be making direct download available in the future.

The base address of the eDEx Web API is https://edex.phys.ucalgary.ca/api. The API provides a set of endpoints, each with it’s own unique path.

Requests

The eDEx Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. eDEx Web API uses the appropriate HTTP verbs for each action:

METHODACTION
GETRetrieves resources
POSTCreates resources

Responses

eDEx Web API responses normally include a JSON object. See the reference documentation below to find descriptions of common responses from each endpoint.

End Points

EndpointDescription
/apiReturns a list of product filenames based on the filters and constraints given
/prepareReportTakes a list of product filenames in JSON format and sends them via a download link to the requested email.
/get_instrument_productsReturns a JSON list of all e-POP data products
/get_experiment_tagsReturns a JSON list of all e-POP experiments
/get_spacecraft_constraint_fieldsReturns a JSON list of all e-POP constraints
/get_geophysical_constraint_fieldsReturns a JSON list of all geophysical constraints

Request Schema

The common eDEx Web API process:

  1. Get-request data product file names using the ‘/api’ endpoint
  2. Confirm the data product file names returned are the files you wish to download
  3. Post-request that the data product files be emailed to you by using the filenames returned to you by ‘/api’

1: GET request data product filenames

A simple curl request:

curl https://edex.phys.ucalgary.ca/api -X GET -d '{"product": ["cassiope.Orbit Geometry"],"date": ["2020-06-01 and 2020-08-01"]}' --header "Content-Type:application/json"

Parameters:

  • Curl – Command line tool for transferring data using various network protocols
  • URL – edex url with API endpoint
  • -X – Specifies a custom request method when communicating with the HTTP server
  • -d – Sends the specified data in the request to the HTTP server
  • –header – Specifies the HTTP header to be sent along with the request. Here we specify the data we’re sending as JSON data.

JSON Object:

All parameters available are listed below in the “/api options” section

2. Confirm data product file names

The GET request will return a list of product names. Confirm this list is what you are looking for as the list may be large. This list can be passed to the next POST request.

3. Post request to have the data files emailed to you

A simple curl request:

curl https://edex.phys.ucalgary.ca/prepareReport -X POST -d '{"result_filenames":["CAS_Orbit_GEO_20170202T000000_20170202T235959_1.1.0.sp3.zip","CAS_Orbit_GEO_20170203T000000_20170203T235959_1.1.0.sp3.zip","CAS_Orbit_GEO_20170204T000000_20170204T235959_1.1.0.sp3.zip"],"email":"esoc@phys.ucalgary.ca","searchString":"( cassiope.Orbit Geometry, cassiope.Attitude Quaternions ) WHEN ( '\''Date'\'' :: Between ( '\''2017-02-02 and 2017-02-04'\'' ) ) USING QUERY ( 1 )"}' --header "Content-Type:application/json"

Parameters:

  • Curl – Command line tool for transferring data using various network protocols
  • URL – edex url with API endpoint
  • -X – Specifies a custom request method when communicating with the HTTP server
  • -d – Sends the specified data in the request to the HTTP server
  • –header – Specifies the HTTP hea der to be sent along with the request. Here we specify the data we’re sending as JSON data.

JSON Object:

All parameters available that may be used in the JSON object to be sent in the data field of the request are available below in the “/prepareReport options” section

/prepareReport JSON Data query options

The “/prepareReport” JSON object consists of 3 keys. “result_filenames”, “email”, and “searchString”. The value of “result_filenames” is the list of data product filenames you are requesting. The value of “email” is the email where the download link will be sent. The “searchString” value is a pseudo SQL string of the format:

"( <comma separated list of products> ) WHEN ( <comma separated list of constraint parameters> ) USING QUERY ( <logical string> ) "

White space matters. A fully comprehensive list of all products and constraint parameters can be found in the tables below.

The bracketed section of the logical string acts on the parameter constraints, therefore the order of the parameter constraints matters. The logical string is a series of “AND”s and “OR”s which can be used to union or intersect the given parameter constraints. e.g. ( 1 AND ( 2 OR 3 ) )

Example:

"( cassiope.Orbit Geometry, cassiope.Attitude Quaternions, mgf.High Resolution CDF, gap.Observation ) WHEN ( 'Date' :: Between ( '2020-06-01 and 2020-08-01' ), 'Date' :: Between ( '2020-11-01 and 2021-01-01' ), 'SWARM'.'SWARM A' :: True, 'SWARM'.'SWARM B' :: True, 'SWARM'.'SWARM C' :: True ) USING QUERY ( ( 1 OR 2 ) AND ( 3 OR 4 OR 5 ) )"

Available Products:

cassiope.Orbit Geometry
cassiope.Attitude Quaternions
cassiope.Bus Telemetry
epop.Quicklook
epop.Ephemeris
cer.Quicklook
cer.TEC
fai.Quicklook
cer.Zip
fai.Summary
fai.PNG
fai.HDF5
gap.Quicklook
gap.Lv1
gap.Observation
irm.Quicklook
irm.Summary
irm.Lv1 Skin Current
irm.Surface Sensor Current
irm.Lv0b
mgf.Quicklook
mgf.Summary
mgf.Residual
mgf.Low Resolution CDF
mgf.High Resolution CDF
nms.Lv0b
nms.Quicklook
nms.Quicklook Velocity
nms.Quicklook Position
rri.HDF5
rri.Quicklook
sei.Quicklook
sei.Summary
sei.Lv0b

Geophysical Constraints:

‘Date’ :: Between ( ‘2020-11-02 and 2020-11-05’ )
‘Geophysical Parameters’.’AE’ :: Between ( ‘0 and 2000’ )
‘Geophysical Parameters’.’Ap’ :: Between ( ‘0 and 35’ )
‘Geophysical Parameters’.’DST’ :: Between ( ‘-600 and 100’ )
‘Geophysical Parameters’.’F 10.7′ :: Between ( ‘0 and 300’ )
‘Geophysical Parameters’.’Kp*10′ :: Between ( ‘0 and 90’ )
‘IMF Parameters’.’Absolute B (nT)’ :: Between ( ‘0 and 50’ )
‘IMF Parameters’.’By GSM (nT)’ :: Between ( ‘-50 and 50’ )
‘IMF Parameters’.’Bz GSM (nT)’ :: Between ( ‘-50 and 50’ )
‘IMF Parameters’.’Flow Pressure (nP)’ :: Between ( ‘0 and 20’ )
‘IMF Parameters’.’Flow Speed (km/s)’ :: Between ( ‘0 and 900’ )
‘IMF Parameters’.’Proton Density’ :: Between ( ‘0 and 100’ )
‘IMF Parameters’.’Proton Temperature (K)’ :: Between ( ‘0 and 1500000’)

e-POP Constraints:

‘e-POP Quicklook’.’Has Data’ :: True
‘CER’.’Has Data’ :: True
‘CER’.’Receiver Site’ :: Arecibo
‘CER’.’Receiver Site’ :: Cuzco
‘CER’.’Receiver Site’ :: Eureka
‘CER’.’Receiver Site’ :: Jicamara
‘CER’.’Receiver Site’ :: Siefring
‘CER’.’Receiver Site’ :: PMaldonad
‘CER’.’Receiver Site’ :: Delta Junct
‘CER’.’Receiver Site’ :: Gakona AK
‘CER’.’Receiver Site’ :: Valdez AK
‘FAI’.’Camera Mode’ :: high-res
‘FAI’.’Camera Mode’ :: med-res
‘FAI’.’Camera Mode’ :: low-res
‘FAI’.’Camera Source’ :: infrared
‘FAI’.’Camera Source’ :: visible
‘FAI’.’Has Data’ :: True
‘GAP’.’Has Data’ :: True
‘GAP’.’Observation Rate’ :: 100 Hz
‘GAP’.’Observation Rate’ :: 50 Hz
‘GAP’.’Observation Rate’ :: 20 Hz
‘GAP’.’Observation Rate’ :: 1 Hz
‘GAP’.’Receiver Number’ :: 0
‘GAP’.’Receiver Number’ :: 1
‘GAP’.’Receiver Number’ :: 2
‘GAP’.’Receiver Number’ :: 3
‘GAP’.’Receiver Number’ :: 4
‘GAP’.’Receiver Number’ :: GAP-A
‘GAP’.’Receiver Number’ :: GAP-O
‘IRM’.’Has Data’ :: True
‘MGF’.’Has Data’ :: True
‘NMS’.’Has Data’ :: True
‘RRI’.’Antenna’ :: monopole
‘RRI’.’Antenna’ :: dipole
‘RRI’.’Bandwidth’ :: 30 KHz
‘RRI’.’Bandwidth’ :: 5 KHz
‘RRI’.’Dwell A (s)’ :: Between ( ‘0 and null’ )
‘RRI’.’Dwell B (s)’ :: Between ( ‘0 and null’ )
‘RRI’.’Frequency (MHz)’ :: Between ( ‘0 and 18.5’ )
‘RRI’.’Gain’ :: high
‘RRI’.’Gain’ :: medium
‘RRI’.’Gain’ :: low
‘RRI’.’Has Data’ :: True
‘RRI’.’Output Channels’ :: I1,Q1,I3,Q3
‘RRI’.’Output Channels’ :: I1,I2,I3,I4
‘RRI’.’Sweep’ :: fixed
‘RRI’.’Sweep’ :: linear
‘RRI’.’Sweep’ :: logarithmic
‘SEI’.’Has Data’ :: True
‘Spacecraft Position’.’Altitude (km)’ :: Between ( ‘300 and 1500’ )
‘Spacecraft Position’.’Geographic Latitude (deg)’ :: Between ( ‘-81 and 81’ )
‘Spacecraft Position’.’Geographic Longitude (deg)’ :: Between ( ‘-180 and 180’ )
‘Spacecraft Position’.’Magnetic Local Time (h)’ :: Between ( ‘0 and 24’ )
‘Spacecraft Attitude’.’Nadir Pointing’ :: True
‘Spacecraft Attitude’.’Nadir Pointing’ :: False
‘Spacecraft Attitude’.’Pitch (deg)’ :: Between ( ‘-90 and 90’ )
‘Spacecraft Attitude’.’Roll (deg)’ :: Between ( ‘-180 and 180’ )
‘Spacecraft Attitude’.’Yaw (deg)’ :: Between ( ‘-180 and 180’ )

Planned Experiment Constraints:

‘Amateur Radio’.’ARRL Field Day’ :: True
‘Amateur Radio’.’HAM Radio’ :: True
‘Auroral Region’.’Auroral Tilt’ :: True
‘Auroral Region’.’Auroral Zone’ :: True
‘Cusp Region’.’Cusp Region’ :: True
‘Earth Limb Viewing’.’Earth Limb’ :: True
‘GAP Orbit Determination’.’GAP-OD’ :: True
‘Miscellaneous’.’RRI Noise Survey’ :: True
‘Miscellaneous’.’RRI Special Event’ :: True
‘Miscellaneous’.’RRI VLF’ :: True
‘Miscellaneous’.’Churchill VLF’ :: True
‘Miscellaneous’.’Lucky Lake VLF’ :: True
‘Miscellaneous’.’Whistler Detection’ :: True
‘Miscellaneous’.’FLASH’ :: True
‘Miscellaneous’.’Kilauea Eruption’ :: True
‘Miscellaneous’.’Lucky Lake VLF, DMSP Satellite’ :: True
‘Miscellaneous’.’RRI Noise Survey, DMSP Satellite’ :: True
‘Miscellaneous’.’He+ Detection’ :: True
‘Miscellaneous’.’Lucky Lake VLF, Clyde River SUPERDARN’ :: True
‘Miscellaneous’.’GAP Uncompressed’ :: True
‘Miscellaneous’.’Lucky Lake VLF, DSX Conjunction’ :: True
‘Miscellaneous’.’RRI NW Hemisphere’ :: True
‘Miscellaneous’.’BBC Documentary’ :: True
‘Miscellaneous’.’Science Campaign’ :: True
‘Point of Interest’.’San Francisco’ :: True
‘Point of Interest’.’Revelstoke’ :: True
‘Point of Interest’.’Portsmouth’ :: True
‘Point of Interest’.’Hurricane Dorian’ :: True
‘Point of Interest’.’Fort McMurray Fire’ :: True
‘Point of Interest’.’Calgary’ :: True
‘Point of Interest’.’Boston’ :: True
‘Point of Interest’.’Hurricane Sandra’ :: True
‘Polar Cap Region’.’Polar Cap’ :: True
‘Rocket + Satellite Conjunctions’.’DMSP Satellite’ :: True
‘Rocket + Satellite Conjunctions’.’Cygnus Spacecraft’ :: True
‘Rocket + Satellite Conjunctions’.’CLUSTER Satellite’ :: True
‘Rocket + Satellite Conjunctions’.’DSX Conjunction’ :: True
‘Rocket + Satellite Conjunctions’.’ICI-4 Rocket’ :: True
‘Rocket + Satellite Conjunctions’.’ICI-5 Rocket’ :: True
‘Rocket + Satellite Conjunctions’.’RENU2 Rocket’ :: True
‘Rocket + Satellite Conjunctions’.’TechDemoSat Satellite’ :: True
‘Rocket + Satellite Conjunctions’.’ZACUBE-1 Satellite’ :: True
‘SAA Region’.’SAA Zone’ :: True
‘SAA Region’.’SEI SAA’ :: True
‘Slew Targets’.’Poker Flat’ :: True
‘Slew Targets’.’Fort Smith’ :: True
‘Slew Targets’.’ICE BEAR Radar’ :: True
‘Solar Eclipse’.’Solar Eclipse’ :: True
‘Solar Eclipse’.’Solar Eclipse Buenos Aires’ :: True
‘SWARM’.’SWARM A’ :: True
‘SWARM’.’SWARM C’ :: True
‘SWARM’.’SWARM B’ :: True
‘Terrestrial Receiver’.’AUTUMNX Receiver’ :: True
‘Terrestrial Receiver’.’LSBB Receiver’ :: True
‘Terrestrial Receiver’.’CARISMA Receiver’ :: True
‘Terrestrial Receiver’.’ABOVE Receiver’ :: True
‘Terrestrial Transmitter’.’Tiger SUPERDARN’ :: True
‘Terrestrial Transmitter’.’ROTHR’ :: True
‘Terrestrial Transmitter’.’WWV Radio Station’ :: True
‘Terrestrial Transmitter’.’Wake Island Transmitter’ :: True
‘Terrestrial Transmitter’.’Toolik Lake Transmitter’ :: True
‘Terrestrial Transmitter’.’DHO38 Radio Station’ :: True
‘Terrestrial Transmitter’.’BPM Time Signal Transmitter’ :: True
‘Terrestrial Transmitter’.’Kharkiv ISR’ :: True
‘Terrestrial Transmitter’.’Cyprus Transmitter’ :: True
‘Terrestrial Transmitter’.’CODAR’ :: True
‘Terrestrial Transmitter’.’Clyde River SUPERDARN’ :: True
‘Terrestrial Transmitter’.’RISR Transmitter’ :: True
‘Terrestrial Transmitter’.’Clyde River SUPERDARN, SAA Zone’ :: True
‘Terrestrial Transmitter’.’CHU Radio Station’ :: True
‘Terrestrial Transmitter’.’Cambridge Bay CADI’ :: True
‘Terrestrial Transmitter’.’Arecibo Transmitter’ :: True
‘Terrestrial Transmitter’.’Surface Wave Radar’ :: True
‘Terrestrial Transmitter’.’Sura Heater’ :: True
‘Terrestrial Transmitter’.’Sondrestrom Radar’ :: True
‘Terrestrial Transmitter’.’Saskatoon SUPERDARN’ :: True
‘Terrestrial Transmitter’.’ISR World Day’ :: True
‘Terrestrial Transmitter’.’New Mexico Transmitter’ :: True
‘Terrestrial Transmitter’.’NLK Radio Station’ :: True
‘Terrestrial Transmitter’.’NWC Radio Station’ :: True
‘Terrestrial Transmitter’.’Ottawa NRCAN Transmitter’ :: True
‘Terrestrial Transmitter’.’Millstone Hill Transmitter’ :: True
‘Terrestrial Transmitter’.’Kodiak SuperDARN’ :: True
‘Terrestrial Transmitter’.’POLARDARN’ :: True
‘Terrestrial Transmitter’.’Prince George SuperDARN’ :: True
‘Terrestrial Transmitter’.’Rankin Inlet SUPERDARN’ :: True
‘Terrestrial Transmitter’.’NAA Transmitter’ :: True
‘Terrestrial Transmitter’.’Resolute Bay Transmitter’ :: True
‘Terrestrial Transmitter’.’Istok’ :: True
‘Terrestrial Transmitter’.’Hawaii Transmitter’ :: True
‘Terrestrial Transmitter’.’Hankasalmi SUPERDARN’ :: True
‘Terrestrial Transmitter’.’HAARP’ :: True
‘Terrestrial Transmitter’.’EISCAT Tromso’ :: True
‘Terrestrial Transmitter’.’EISCAT Svalbard’ :: True
‘Terrestrial Transmitter’.’DRDC’ :: True