RESTful API from the University of Calgary Space Remote Sensing group for accessing space physics and remote-sensing data (all-sky imagers, riometers, and related instruments). Usable directly over HTTP or via the pyucalgarysrs / pyucrio Python and IDL client libraries. Interactive Swagger documentation is served at the API root.
openapi: 3.0.3
info:
title: UCalgary Space Remote Sensing API
description: API providing data and tools for UCalgary Space Remote Sensing
version: 1.56.0
paths:
/api/v1/data_distribution/datasets:
get:
tags:
- Data Distribution
summary: Retrieve available datasets
description: "Retrieve information about available datasets. Filter based on parameters supplied.\n\
\nNotes:\n - filtering is case insensitive\n - data level description: https://www.earthdata.nasa.gov/engage/open-data-services-and-software/data-information-policy/data-levels"
operationId: retrieve_datasets_api_v1_data_distribution_datasets_get
parameters:
- name: name
in: query
required: false
schema:
nullable: true
type: string
title: Name
- name: level
in: query
required: false
schema:
type: string
enum:
- L0
- L1
- L1A
- L2
- L3
title: Level
responses:
'200':
description: Dataset information
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: '#/components/schemas/Dataset'
- $ref: '#/components/schemas/DatasetLegacy1'
- $ref: '#/components/schemas/DatasetLegacy2'
title: Response Retrieve Datasets Api V1 Data Distribution Datasets Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/data_distribution/urls:
get:
tags:
- Data Distribution
summary: Retrieve list of URLs for a given dataset
description: "Retrieve list of URLs for a given dataset and timeframe.\n\nNotes:\n - start and\
\ end times are inclusive\n - start and end time format is YYYY-mm-ddTHH:MM:SS. Excluding values\
\ from the right to \n the left result in default values being used (eg. YYYY-mm-ddTHH results\
\ in YYYY-mm-ddTHH:00:00)\n - dataset matching is case insensitive\n - site_uid is expected\
\ to be the 4-letter site code, and is case insensitive\n - device_uid is expected to be the\
\ instrument identifier such as \"themis02\", \"rego-657\", or \"rgb-07\",\n and is case insensitive"
operationId: retrieve_urls_api_v1_data_distribution_urls_get
parameters:
- name: name
in: query
required: true
schema:
type: string
title: Name
- name: start
in: query
required: true
schema:
type: string
format: date-time
title: Start
- name: end
in: query
required: true
schema:
type: string
format: date-time
title: End
- name: site_uid
in: query
required: false
schema:
nullable: true
type: string
title: Site Uid
- name: device_uid
in: query
required: false
schema:
nullable: true
type: string
title: Device Uid
- name: include_total_bytes
in: query
required: false
schema:
type: boolean
default: false
title: Include Total Bytes
responses:
'200':
description: URLs
content:
application/json:
schema:
$ref: '#/components/schemas/FileListingResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Dataset not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: Data retrieval error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/data_distribution/observatories:
get:
tags:
- Data Distribution
summary: Retrieve information about observatories
description: "Retrieve information about observatories. Filter based on parameters supplied.\n\n\
Notes:\n - filtering for \"uid\" is case insensitive"
operationId: retrieve_observatories_api_v1_data_distribution_observatories_get
parameters:
- name: instrument_array
in: query
required: true
schema:
type: string
enum:
- norstar_riometer
- rego
- smile_asi
- swan_hsr
- themis_asi
- trex_blue
- trex_nir
- trex_rgb
- trex_spectrograph
title: Instrument Array
- name: uid
in: query
required: false
schema:
nullable: true
type: string
title: Uid
responses:
'200':
description: Observatory information
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Observatory'
title: Response Retrieve Observatories Api V1 Data Distribution Observatories Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/data_distribution/imaging_timeframes:
post:
tags:
- Data Distribution
summary: Retrieve imaging start and end times for a set of locations
description: "Retrieve imaging start and end times for a set of locations. This is specific to the\
\ optical \ninstrumentation we provide data for.\n\nThe timestamp is expected to be UTC time.\n\
\nEach location in the 'locations' array can be specified either by a 4-letter site UID, or by\n\
providing geodetic latitude and longitude. If the site_uid is provided, it is resolved to\ncoordinates\
\ using the known observatory list.\n\nNotes:\n - The threshold parameter is the solar zenith\
\ angle (in degrees) above which imaging occurs. \n The default value of 102.0 corresponds\
\ to nautical twilight, and what all UCalgary optical\n instruments use.\n - The `site_uid`\
\ parameter matching is case insensitive"
operationId: retrieve_imaging_timeframes_api_v1_data_distribution_imaging_timeframes_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImagingTimeframesRequest'
required: true
responses:
'200':
description: Imaging times
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ImagingTimeframeResponse'
type: array
title: Response Retrieve Imaging Timeframes Api V1 Data Distribution Imaging Timeframes
Post
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Site not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/atm/forward:
post:
tags:
- Auroral Transport Model (ATM)
summary: Perform forward ATM calculation
description: "Perform a forward calculation using **VERSION 1** of the TREx Auroral Transport Model\
\ and the supplied \ninput parameters.\n\nInput notes:\n - timestamp\n - timestamp is expected\
\ to be in UTC, and is valid for any value up to the end of the previous day\n - the 'Z' character\
\ at the end of the timestamp is optional, and will be ignored if it is supplied\n - latitude\
\ and longitude are to be in geodetic coordinates (-90 to 90 lat, -180 to 180 lon)\n - maxwellian_characteristic_energy\
\ must be specified if the maxwellian_energy_flux is not 0\n - gaussian_peak_energy must be specified\
\ if the gaussian_energy_flux is not 0\n - gaussian_spectral_width must be specified if the gaussian_energy_flux\
\ is not 0\n - valid values for nrlmsis_model_version are '00' and '2.0'\n - The ATM model is\
\ 1D and time-independent. However, the optional parameters timescale_auroral and \n timescale_transport\
\ provide limited support for time-dependent and transport process.\n - timescale_auroral\
\ (T0) is the duration of the precipitation; default value is 600 sec\n - timescale_transport\
\ is defined by L/v0, in which L is the dimension of the auroral structure, \n and v0 is\
\ the cross-structure drift speed. Default value is 600 sec.\n - the model quasi-analytically\
\ solves the continuity equation under a square input (with time \n duration T0 and spatial\
\ width L) input of precipitation. The initial/boundary conditions are \n given by IRI.\
\ The output yields the mean density/VER over [0-L] at time T0.\n - units\n - timescale parameters:\
\ seconds\n - maxwellian energy flux: erg/cm2/s\n - maxwellian characteristic energy: eV\n\
\ - gaussian energy flux: erg/cm2/s\n - gaussian peak energy: eV\n - gaussian spectral\
\ width: eV\n - custom spectrum\n - energy in eV, flux in 1/cm2/s/eV\n - energy and flux\
\ arrays must be the same length\n - by default requests are cached; use the 'no_cache' parameter\
\ to disable this functionality\n\nOutput notes:\n - output parameter of the request are toggles\
\ the enable/disable each field's inclusion in the response\n - all output parameters are false\
\ by default\n - altitude is in kilometers\n - emission data: 1-D array -- volume emission rate\
\ (1/cm^3/s)\n - plasma electron density: 1-D array -- density (cm^-3)\n - plasma O2+ density:\
\ 1-D array -- density (cm^-3)\n - plasma NO+ density: 1-D array -- density (cm^-3)\n - plasma\
\ O+ density: 1-D array -- density (cm^-3)\n - plasma ionisation rate: 1-D array -- ionisation\
\ rate (1/cm^3/s)\n - plasma electron temperature: 1-D array -- temperature (K)\n - plasma ion\
\ temperature: 1-D array -- temperature (K)\n - plasma peterson conductivity: 1-D array -- conductivity\
\ (S/m)\n - plasma hall conductivity: 1-D array -- conductivity (S/m)\n - neutral O2 density:\
\ 1-D array -- density (cm^-3)\n - neutral O density: 1-D array -- density (cm^-3)\n - neutral\
\ N2 density: 1-D array -- density (cm^-3)\n - neutral N density: 1-D array -- density (cm^-3)\n\
\ - neutral temperature: 1-D array -- temperature (K)"
operationId: atm_forward_api_v1_atm_forward_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/src__atm__v1__schemas_forward__ATMForwardRequest'
examples:
base:
summary: Default request object
description: Default field values, adjust accordingly
value:
atm_model_version: '1.0'
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 0
geodetic_longitude: 0
maxwellian_energy_flux: 10
gaussian_energy_flux: 0
maxwellian_characteristic_energy: 5000
gaussian_peak_energy: 1000
gaussian_spectral_width: 100
nrlmsis_model_version: '2.0'
oxygen_correction_factor: 1
timescale_auroral: 600
timescale_transport: 600
custom_spectrum:
energy: []
flux: []
output:
height_integrated_rayleighs_4278: false
height_integrated_rayleighs_5577: false
height_integrated_rayleighs_6300: false
height_integrated_rayleighs_8446: false
height_integrated_rayleighs_lbh: false
height_integrated_rayleighs_1304: false
height_integrated_rayleighs_1356: false
altitudes: false
emission_4278: false
emission_5577: false
emission_6300: false
emission_8446: false
emission_lbh: false
emission_1304: false
emission_1356: false
plasma_electron_density: false
plasma_o2plus_density: false
plasma_oplus_density: false
plasma_noplus_density: false
plasma_ionisation_rate: false
plasma_electron_temperature: false
plasma_ion_temperature: false
plasma_pederson_conductivity: false
plasma_hall_conductivity: false
neutral_o2_density: false
neutral_o_density: false
neutral_n2_density: false
neutral_n_density: false
neutral_temperature: false
no_cache: false
example0:
summary: A simple example
description: A simple example
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 51.04
geodetic_longitude: -114.5
output:
height_integrated_rayleighs_4278: true
height_integrated_rayleighs_5577: true
height_integrated_rayleighs_6300: true
height_integrated_rayleighs_8446: true
height_integrated_rayleighs_lbh: true
height_integrated_rayleighs_1304: true
height_integrated_rayleighs_1356: true
altitudes: true
example1:
summary: A simple example with all output parameters
description: A simple example with all output parameters
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 51.04
geodetic_longitude: -114.5
output:
height_integrated_rayleighs_4278: true
height_integrated_rayleighs_5577: true
height_integrated_rayleighs_6300: true
height_integrated_rayleighs_8446: true
height_integrated_rayleighs_lbh: true
height_integrated_rayleighs_1304: true
height_integrated_rayleighs_1356: true
altitudes: true
emission_4278: true
emission_5577: true
emission_6300: true
emission_8446: true
emission_lbh: true
emission_1304: true
emission_1356: true
plasma_electron_density: true
plasma_o2plus_density: true
plasma_oplus_density: true
plasma_noplus_density: true
plasma_ionisation_rate: true
plasma_electron_temperature: true
plasma_ion_temperature: true
plasma_pederson_conductivity: true
plasma_hall_conductivity: true
neutral_o2_density: true
neutral_o_density: true
neutral_n2_density: true
neutral_n_density: true
neutral_temperature: true
no_cache: false
example2:
summary: A simple example without using the cache
description: A simple example without using the cache
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 51.04
geodetic_longitude: -114.5
output:
height_integrated_rayleighs_4278: true
height_integrated_rayleighs_5577: true
height_integrated_rayleighs_6300: true
height_integrated_rayleighs_8446: true
height_integrated_rayleighs_lbh: true
height_integrated_rayleighs_1304: true
height_integrated_rayleighs_1356: true
altitudes: true
no_cache: true
required: true
responses:
'200':
description: Calculated outputs
content:
application/json:
schema:
$ref: '#/components/schemas/src__atm__v1__schemas_forward__ATMForwardResponse'
'400':
description: Problematic request made
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: Data generation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/atm/inverse:
post:
tags:
- Auroral Transport Model (ATM)
summary: Perform inverse ATM calculation
description: "Perform an inverse calculation using **VERSION 1** of the TREx Auroral Transport Model\
\ and the supplied \ninput parameters.\n\nInput notes:\n - timestamp\n - timestamp is expected\
\ to be in UTC\n - only specific dates are valid at this time. A 400 error will be returned\
\ if an unsupported date is\n requested. If you want to get a date that we have not enabled\
\ support for yet, please contact us.\n - the 'Z' character at the end of the timestamp is\
\ optional, and will be ignored if it is supplied\n - latitude and longitude\n - are to be\
\ in geodetic coordinates\n - latitude is currently limited to >=50.0 and <61.5 degrees\n \
\ - longitude is currently limited >=-110 and <-70 and degrees\n - valid values for nrlmsis_model_version\
\ are '00' and '2.0'\n - valid values for precipitation_flux_spectral_type are 'gaussian' and\
\ 'maxwellian'\n - intensity parameters are expected to be height-integrated values, and in Rayleighs\n\
\ - by default requests are cached; use the 'no_cache' parameter to disable this functionality\n\
\nOutput notes:\n - output parameter of the request are toggles the enable/disable each field's\
\ inclusion in the response\n - all output parameters are false by default\n - altitude is in\
\ kilometers\n - energy flux: erg/cm2/s\n - characteristic energy: eV\n - emission data: 1-D\
\ array -- volume emission rate (1/cm^3/s)\n - plasma electron density: 1-D array -- density\
\ (cm^-3)\n - plasma O2+ density: 1-D array -- density (cm^-3)\n - plasma NO+ density: 1-D array\
\ -- density (cm^-3)\n - plasma O+ density: 1-D array -- density (cm^-3)\n - plasma ionisation\
\ rate: 1-D array -- ionisation rate (1/cm^3/s)\n - plasma electron temperature: 1-D array --\
\ temperature (K)\n - plasma ion temperature: 1-D array -- temperature (K)\n - plasma peterson\
\ conductivity: 1-D array -- conductivity (S/m)\n - plasma hall conductivity: 1-D array -- conductivity\
\ (S/m)\n - neutral O2 density: 1-D array -- density (cm^-3)\n - neutral O density: 1-D array\
\ -- density (cm^-3)\n - neutral N2 density: 1-D array -- density (cm^-3)\n - neutral N density:\
\ 1-D array -- density (cm^-3)\n - neutral temperature: 1-D array -- temperature (K)"
operationId: atm_inverse_api_v1_atm_inverse_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/src__atm__v1__schemas_inverse__ATMInverseRequest'
examples:
base:
summary: Default request object
description: Default field values, adjust accordingly
value:
atm_model_version: '1.0'
timestamp: '2024-10-01T06:00:00'
geodetic_latitude: 0
geodetic_longitude: 0
intensity_4278: 1000
intensity_5577: 6000
intensity_6300: 600
intensity_8446: 400
precipitation_flux_spectral_type: gaussian
nrlmsis_model_version: '2.0'
atmospheric_attenuation_correction: false
output:
altitudes: false
energy_flux: false
characteristic_energy: false
oxygen_correction_factor: false
height_integrated_rayleighs_4278: false
height_integrated_rayleighs_5577: false
height_integrated_rayleighs_6300: false
height_integrated_rayleighs_8446: false
emission_4278: false
emission_5577: false
emission_6300: false
emission_8446: false
plasma_electron_density: false
plasma_o2plus_density: false
plasma_oplus_density: false
plasma_noplus_density: false
plasma_ionisation_rate: false
plasma_electron_temperature: false
plasma_ion_temperature: false
plasma_pederson_conductivity: false
plasma_hall_conductivity: false
neutral_o2_density: false
neutral_o_density: false
neutral_n2_density: false
neutral_n_density: false
neutral_temperature: false
no_cache: false
example0:
summary: A simple example
description: A simple example
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 58.28
geodetic_longitude: -103.68
intensity_4278: 2300
intensity_5577: 11400
intensity_6300: 530
intensity_8446: 427
output:
altitudes: true
energy_flux: true
characteristic_energy: true
oxygen_correction_factor: true
example1:
summary: A simple example with all output parameters
description: A simple example with all output parameters
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 58.28
geodetic_longitude: -103.68
intensity_4278: 2300
intensity_5577: 11400
intensity_6300: 530
intensity_8446: 427
output:
altitudes: true
energy_flux: true
characteristic_energy: true
oxygen_correction_factor: true
height_integrated_rayleighs_4278: true
height_integrated_rayleighs_5577: true
height_integrated_rayleighs_6300: true
height_integrated_rayleighs_8446: true
emission_4278: true
emission_5577: true
emission_6300: true
emission_8446: true
plasma_electron_density: true
plasma_o2plus_density: true
plasma_oplus_density: true
plasma_noplus_density: true
plasma_ionisation_rate: true
plasma_electron_temperature: true
plasma_ion_temperature: true
plasma_pederson_conductivity: true
plasma_hall_conductivity: true
neutral_o2_density: true
neutral_o_density: true
neutral_n2_density: true
neutral_n_density: true
neutral_temperature: true
example2:
summary: A simple example without using the cache
description: A simple example without using the cache
value:
timestamp: '2024-01-01T06:00:00'
geodetic_latitude: 58.28
geodetic_longitude: -103.68
intensity_4278: 2300
intensity_5577: 11400
intensity_6300: 530
intensity_8446: 427
output:
altitudes: true
energy_flux: true
characteristic_energy: true
oxygen_correction_factor: true
no_cache: true
required: true
responses:
'200':
description: Calculated outputs
content:
application/json:
schema:
$ref: '#/components/schemas/src__atm__v1__schemas_inverse__ATMInverseResponse'
'400':
description: Problematic request made
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: Data generation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v2/atm/forward:
post:
tags:
- Auroral Transport Model (ATM)
summary: Perform forward ATM calculation
description: "Perform a forward calculation using **VERSION 2** of the TREx Auroral Transport Model\
\ and the supplied \ninput parameters.\n\n**NOTE**: As of API version 1.41.0 (released 2026-01-30),\
\ the `height_integrated_rayleighs_lbh` and \n`emission_lbh` output flags have been renamed to\
\ `height_integrated_rayleighs_smile_uvi_lbh` and \n`emission_smile_uvi_lbh`. Further, the `plasma_pederson_conductivity`\
\ output flag has been renamed to \n`plasma_pedersen_conductivity`. The original names will be\
\ removed in a later release to be determined.\n\nInput notes:\n - By default requests are cached.\
\ Use the 'no_cache' parameter to disable this functionality\n - Latitude and longitude are to\
\ be in geodetic coordinates (-90 to 90 lat, -180 to 180 lon)\n - Timestamp\n - timestamp\
\ is expected to be in UTC, and is valid for any value up to the end of the previous day\n \
\ - the 'Z' character at the end of the timestamp is optional, and will be ignored if it is supplied\n\
\ - Spectral shapes\n - If the maxwellian_energy_flux is not 0, then maxwellian_characteristic_energy\
\ will be used. If\n maxwellian_characteristic_energy is not specified, then the default\
\ will be used.\n - If the gaussian_energy_flux is not 0, then gaussian_peak_energy and gaussian_spectral_width\
\ will be\n used. If these two values are not specified, then the defaults will be used.\
\ \n - If kappa_energy_flux is not 0, then kappa_mean_energy and kappa_k_index will be used.\
\ If these two \n values are not specified, then the defaults will be used.\n - If exponential_energy_flux\
\ is not 0, then exponential_characteristic_energy and exponential_starting_energy\n will\
\ be used. If these two values are not specified, then the defaults will be used.\n - **IMPORTANT**:\
\ All the above spectral shapes are super-imposable except exponential. The exponential spectrum\
\ \n should be only be used for high-energy tail and, starting from E0 (proton_starting_energy),\
\ will override any \n other spectral specification.\n - If proton_energy_flux is not 0,\
\ then proton_characteristic_energy will be used. If the \n proton_characteristic_energy is\
\ not specified, then the default will be used.\n - The ATM model is 1D and time-independent.\
\ However, the optional parameters timescale_auroral and \n timescale_transport provide limited\
\ support for time-dependent and transport process.\n - timescale_auroral (T0) is the duration\
\ of the precipitation; default value is 600 sec\n - timescale_transport is defined by L/v0,\
\ in which L is the dimension of the auroral structure, \n and v0 is the cross-structure\
\ drift speed. Default value is 600 sec.\n - the model quasi-analytically solves the continuity\
\ equation under a square input (with time \n duration T0 and spatial width L) input of\
\ precipitation. The initial/boundary conditions are \n given by IRI. The output yields\
\ the mean density/VER over [0-L] at time T0.\n - **NOTE**: proton precipitation is presently\
\ only for ionization rate and density calculations. Proton auroras are \n not nominal TREx\
\ characteristics and currently not computed in this version of the model.\n - Units and defaults\n\
\ - maxwellian total energy flux: erg/cm2/s, default is 10 \n - maxwellian characteristic\
\ energy: eV, default is 5000 \n - gaussian total energy flux: erg/cm2/s, default is 0 (indicating\
\ all gaussian parameters are disabled) \n - gaussian peak energy: eV, default is 1000\n \
\ - gaussian spectral width: eV, default is 100\n - kappa total energy flux: erg/cm2/s, default\
\ is 0 (indicating all kappa parameters are disabled) \n - kappa mean energy: eV, default is\
\ 30000\n - kappa k-index: no unit, default is 5\n - exponential total energy flux: erg/cm2/s,\
\ default is 0 (indicating all exponential parameters are disabled) \n - exponential characteristic\
\ energy: eV, default is 50000\n - exponential starting energy: eV, default is 50000\n -\
\ proton total energy flux: erg/cm2/s, default is 0 (indicating all proton parameters are disabled)\
\ \n - proton characteristic energy: eV, default is 10000\n - d-region flag: defaults to\
\ false\n - custom spectrum (precipitation) \n - energy in eV, flux in 1/cm2/s/eV \n \
\ - energy and flux arrays must be the same length \n - users are responsible for fully\
\ covering the energy range of interest in the provided spectrum. The model \n only performs\
\ interpolation, not extrapolation.\n - custom neutral profile \n - altitude in km, density\
\ in cm^-3, temperature in K. \n - users are responsible for fully covering the altitude\
\ range of interest in the provided profile (80-800 km \n if d_region_flag=0, or 50-500\
\ km if d_region_flag=1). The model only performs interpolation, not extrapolation.\n - nrlmsis_model_version:\
\ valid values are \"00\" and \"2.0\",
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-calgary/refs/heads/main/openapi/university-of-calgary-srs-api.yaml