CASSIOPE SPACECRAFT (Swarm-E)
PROCESSED DATA HANDBOOK
eDEx API Documentation
The eDEx Web API provides programmatic access to data products stored in the eDEx database. Built on simple REST principles, the API accepts JSON-formatted requests containing filters and constraints, and returns JSON responses with the requested data. Users can specify the desired data products, apply filters (e.g., date ranges, instrument types, or other criteria), and receive a list of matching filenames. Once confirmed, users can directly download the selected data products as a single file.
The base address for the eDEx Web API is:
https://api.edex.phys.ucalgary.ca
The API consists of a set of well-defined endpoints, each serving a specific purpose and accessible via its unique path. Below, you will find detailed documentation for each endpoint, including usage examples and expected responses.
Key Features of the eDEx Web API
- JSON-Based Communication: The API uses JSON for both input (filters and constraints) and output (responses), ensuring compatibility with modern applications and ease of use.
- Two-Step Workflow:
- File Listing: Users submit a request with desired products and filters to retrieve a list of available filenames.
- Direct Download: Users confirm the files and initiate a direct download of the selected data products.
- Progress Tracking: The API supports real-time progress tracking for downloads, allowing users to monitor the status of their requests using a unique
session_id. - Scalability: Designed to handle both small and large datasets efficiently, ensuring a smooth user experience.
How It Works
- Request a File List: Users submit a query with filters (e.g., product names, date ranges, instruments and/or measurement parameters) to the API and receive a list of matching filenames.
- Confirm and Download: Users confirm the files they wish to download and initiate a direct download request. The API streams the data products to the user in real-time, with progress updates available via a dedicated endpoint.
- Track Progress: Users can poll the progress endpoint to monitor the download status, including bytes transferred, total size, and completion percentage.
API Endpoints
| Endpoint | Description |
| /api_fetch_data | Accepts a JSON string of product names and constraints, and returns a list of filenames matching the filters. |
| /download | Accepts a list of filenames and streams the selected files as a direct download. Requires a session_id for progress tracking |
| /progress | Provides real-time updates on the download progress for a given session_id. |
Python implementation
An example Python program that should make things easy. It makes a call to /api_fetch_data to retrieve a list of filenames, confirms the files, initiates a direct download using the /download endpoint, and monitors its progress using the /progress endpoint
How to download data with eDEx Web API
- Fetch File List: Send a request to
/api_fetch_datawith the desired products and filters. The response will include a list of filenames. - Confirm Files: Review the list of filenames returned by
/api_fetch_data. If the files are correct, proceed to the next step. - Initiate Download: Send a request to
/downloadwith the list of filenames and a uniquesession_id. The API will stream the files directly to your client. - Track Progress: Use the
/progressendpoint to monitor the download status. Poll this endpoint periodically to get updates on bytes transferred, total size, and completion percentage.
API Products and Constraints
The JSON string is made up of the products desired and a number of constraints to filter those products. A product property, at least one constraint (e.g., date), and the query-logic property must be included when communicating with the /api_fetch_data endpoint.
Query Logic property
The query-logic property defines how the API processes the constraints. It is a string of logical operators (AND, OR) that combine the constraints. For example:
{"query-logic": "(1 AND 2) OR (3 AND 4)"}
Valid JSON Examples
Example 1: Fetch File List
{
"product": ["epop-quicklook", "mgf-quicklook"],
"date": [["2020-01-01", "2020-01-05"]],
"query-logic": "1 AND 2"
}
Example 2: Initiate Download
{
"selectedFiles": ["file1.zip", "file2.zip"],
"session_id": "your-session-id"
}
All Available Products and Constraints
Products
| “product”: [ | “cassiope-orbit-ephemeris-sp3”, |
| “cassiope-attitude-quaternions-and-ypr”, | |
| “cassiope-bus-telemetry”, | |
| “cassiope-legacy-ephemeris-and-attitude”, | |
| “epop-quicklook”, | |
| “epop-instrument-data-availability”, | |
| “cer-quicklook”, | |
| “cer-tec”, | |
| “cer-ground-receiver-data”, | |
| “fai-quicklook”, | |
| “fai-summary”, | |
| “fai-png-images”, | |
| “fai-lv1-hdf5-images”, | |
| “gap-quicklook”, | |
| “gap-lv1”, | |
| “gap-los-tec”, | |
| “gap-los-tec-ql”, | |
| “gap-vtec”, | |
| “gap-vtec-ql”, | |
| “gap-rinex-observation”, | |
| “irm-quicklook”, | |
| “irm-summary”, | |
| “irm-surface-sensor-current”, | |
| “irm-lv0b”, | |
| “mgf-quicklook”, | |
| “mgf-summary”, | |
| “mgf-residual”, | |
| “mgf-1-sps-lv1b-cdf”, | |
| “mgf-160-sps-lv1b-cdf”, | |
| “nms-lv0b”, | |
| “nms-quicklook”, | |
| “nms-quicklook-velocity”, | |
| “nms-quicklook-position”, | |
| “rri-quicklook”, | |
| “rri-lv1-hdf5”, | |
| “sei-quicklook”, | |
| “sei-summary”, | |
| “sei-lv0b”] |
Time Constraints
| “date”: [ | [“2013-09-30′, ‘2023-01-05”]] |
Geophysical Constraints
| ‘geophysical-parameters’: [ | [‘ae’, ‘0’, ‘2000’], |
| [‘ap’, ‘0’, ’35’], | |
| [‘dst’, ‘-600’, ‘100’], | |
| [‘f10.7’, ‘0’, ‘300’], | |
| [‘kp10’, ‘0’, ’90’]] | |
| ‘imf-parameters’: [ | [‘absolute-b’, ‘0’, ’50’], |
| [‘by-gsm’, ‘-50′, ’50’], | |
| [‘bz-gsm’, ‘-50′, ’50’], | |
| [‘flow-pressure’, ‘0’, ’20’], | |
| [‘flow-speed’, ‘0’, ‘900’], | |
| [‘proton-density’, ‘0’, ‘100’]] |
e-POP Constraints
| ‘e-pop-quicklook’: [ | ‘has-data’] |
| ‘cer’: [ | ‘has-data’, |
| [“receiver-site”, “arecibo”], | |
| [‘receiver-site’, ‘cuzco’], | |
| [‘receiver-site’, ‘eureka’], | |
| [‘receiver-site’, ‘jicamara’], | |
| [‘receiver-site’, ‘siefring’], | |
| [‘receiver-site’, ‘pmaldonad’], | |
| [‘receiver-site’, ‘delta-junct’], | |
| [‘receiver-site’, ‘gakon-ak’], | |
| [‘receiver-site’, ‘valdez-ak’]] | |
| ‘fai’: [ | ‘has-data’, |
| [‘camera-mode’, ‘high-res’], | |
| [‘camera-mode’, ‘med-res’], | |
| [‘camera-mode’, ‘low-res’], | |
| [‘camera-source’, ‘infrared’], | |
| [‘camera-source’, ‘visible’]] | |
| ‘gap’: [ | ‘has-data’, |
| [‘observation-rate’, ‘100hz’], | |
| [‘observation-rate’, ’50hz’], | |
| [‘observation-rate’, ’20hz’], | |
| [‘observation-rate’, ‘1hz’], | |
| [‘receiver-number’, ‘0’], | |
| [‘receiver-number’, ‘1’], | |
| [‘receiver-number’, ‘2’], | |
| [‘receiver-number’, ‘3’], | |
| [‘receiver-number’, ‘4’], | |
| [‘receiver-number’, ‘gap-a’], | |
| [‘receiver-number’, ‘gap-o’]] | |
| ‘irm’: [ | ‘has-data’] |
| ‘mgf’: [ | ‘has-data’] |
| ‘nms’: [ | ‘has-data’] |
| ‘rri’: [ | ‘has-data’, |
| [‘antenna’, ‘monopole’], | |
| [‘antenna’, ‘dipole’], | |
| [‘bandwidth’, ’30khz’], | |
| [‘bandwidth’, ‘5 KHz’], | |
| [‘dwell-a’, ‘0’, ’60’], | |
| [‘dwell-b’, ‘0’, ’60’], | |
| [“frequency”,”0″,”18.5″], | |
| [‘gain’, ‘high’], | |
| [‘gain’, ‘medium’], | |
| [‘gain’, ‘low’], | |
| [‘output-channels’, ‘i1-q1-i3-q3’], | |
| [‘output-channels’, ‘i1-i2-i3-i4’], | |
| [‘sweep’, ‘fixed’], | |
| [‘sweep’, ‘linear’], | |
| [‘sweep’, ‘logarithmic’]] | |
| ‘sei’: [ | ‘has-data’] |
| ‘spacecraft-position’: [ | [‘altitude’, ‘300’, ‘1500’], |
| [‘geographic-latitude’, ‘-81′,’81’], | |
| [‘geographic-longitude’, ‘-180’, ‘180’], | |
| [‘magnetic-local-time’, ‘0’, ’24’]] | |
| ‘spacecraft-attitude’: [ | [‘nadir-pointing’, ‘true’], |
| [‘nadir-pointing’, ‘false’], | |
| [‘pitch’, ‘-90′, ’90’], | |
| [‘roll’, ‘-180’, ‘-180’], | |
| [‘yaw’, ‘-180’, ‘-180’]] |
Planned Experiment Constraints
| ‘amateur-radio’: [ | ‘arrl-field-day’, |
| ‘ham-radio’] | |
| ‘auroral-region’: [ | ‘auroral-tilt’, |
| ‘auroral-zone’] | |
| ‘cusp-region’: [ | ‘cusp-region’] |
| ‘earth-limb-viewing’: [ | ‘earth-limb’] |
| ‘gap-orbit-determination’: [ | ‘gap-od’] |
| ‘miscellaneous’: [ | ‘rri-noise-survey’, |
| ‘rri-special-event’, | |
| ‘rri-vlf’, | |
| ‘churchill-vlf’, | |
| ‘lucky-lake-vlf’, | |
| ‘whistler-detection’, | |
| ‘flash’, | |
| ‘kilauea-eruption’, | |
| ‘lucky-lake-vlf-dmsp-satellite’, | |
| ‘rri-noise-survey-dmsp-satellite’, | |
| ‘he+-detection’, | |
| ‘lucky-lake-vlf-clyde-river-superdarn’, | |
| ‘gap-uncompressed’, | |
| ‘lucky-lake-vlf-dsx-conjunction’, | |
| ‘rri-nw-hemisphere’, | |
| ‘bbc-documentary’, | |
| ‘science-campaign’] | |
| ‘point-of-interest’: [ | ‘san-francisco’, |
| ‘revelstoke’, | |
| ‘portsmouth’, | |
| ‘hurricane-dorian’, | |
| ‘fort-mcmurray-fire’, | |
| ‘calgary’, | |
| ‘boston’, | |
| ‘hurricane-sandra’] | |
| ‘polar-cap-region’: [ | ‘polar-cap’] |
| ‘rocket-satellite-conjunctions’: [ | ‘dmsp-satellite’, |
| ‘cygnus-spacecraft’, | |
| ‘cluster-satellite’, | |
| ‘dsx-conjunction’, | |
| ‘ici-4-rocket’, | |
| ‘ici-5-rocket’, | |
| ‘renu2-rocket’, | |
| ‘techdemosat-satellite’, | |
| ‘zacube-1-satellite’] | |
| ‘saa-region’: [ | ‘saa-zone’, |
| ‘sei-saa’] | |
| ‘slew-targets’: [ | ‘poker-flat’, |
| ‘fort-smith’, | |
| ‘ice-bear-radar’] | |
| ‘solar-eclipse’: [ | ‘solar Eclipse’, |
| ‘solar-eclipse-buenos-aires’] | |
| ‘swarm’: [ | ‘swarm-a’, |
| ‘swarm-b’, | |
| ‘swarm-c’] | |
| ‘terrestrial-receiver’: [ | ‘autumn-x-receiver’, |
| ‘lsbb-receiver’, | |
| ‘carisma-receiver’, | |
| ‘above-receiver’] | |
| ‘terrestrial-transmitter’: [ | ‘tiger-superdarn’, |
| ‘rothr’, | |
| ‘wwv-radio-station’, | |
| ‘wake-island-transmitter’, | |
| ‘toolik-lake-transmitter’, | |
| ‘dho38-radio-station’, | |
| ‘bpm-time-signal-transmitter’, | |
| ‘kharkiv-isr’, | |
| ‘cyprus-transmitter’, | |
| ‘codar’, | |
| ‘clyde-river-superdarn’, | |
| ‘risr-transmitter’, | |
| ‘clyde-river-superdarn-saa-zone’, | |
| ‘chu-radio-station’, | |
| ‘cambridge-bay-cadi’, | |
| ‘arecibo-transmitter’, | |
| ‘surface-wave-radar’, | |
| ‘sura-heater’, | |
| ‘sondrestrom-radar’, | |
| ‘saskatoon-superdarn’, | |
| ‘isr-world-day’, | |
| ‘new-mexico-transmitter’, | |
| ‘nlk-radio-station’, | |
| ‘nwc-radio-station’, | |
| ‘ottawa-nrcan-transmitter’, | |
| ‘millstone-hill-transmitter’, | |
| ‘kodiak-superdarn’, | |
| ‘polardarn’, | |
| ‘prince-george-superdarn’, | |
| ‘rankin-inlet-superdarn’, | |
| ‘naa-transmitter’, | |
| ‘resolute-bay-transmitter’, | |
| ‘istok’, | |
| ‘hawaii-transmitter’, | |
| ‘hankasalmi-superdarn’, | |
| ‘haarp’, | |
| ‘eiscat-tromso’, | |
| ‘eiscat-svalbard’, | |
| ‘drdc’] |