Public RESTful API for the AuroraX auroral-science data platform, developed and operated with the University of Calgary. Provides search and access to auroral metadata, ephemeris, and imagery data. An API key is only required for write operations; read access is open. Python (PyAuroraX) and IDL client libraries are available.
openapi: 3.0.1
info:
title: AuroraX API
description: "## Overview\n\nThis webpage is an interactive documentation interface for the AuroraX\
\ RESTful API. This API\nis used by several applications including the AuroraX Conjunction Search,\
\ Event Explorer,\nKeogramist, PyAuroraX, and IDL-AuroraX. You can view these applications and libraries\
\ at\n<a href='https://aurorax.space' target='_blank'>https://aurorax.space</a> and\n<a href='https://github.com/aurorax-space'\
\ target='_blank'>https://github.com/aurorax-space</a>.\n\nDetailed documentation about the AuroraX\
\ platform and examples of using this API can be found at\n<a href='https://docs.aurorax.space' target='_blank'>https://docs.aurorax.space</a>.\n\
\nBelow, we outline the major categories of endpoints available for use:\n\n| Interface | Description\
\ |\n| ---------------- | ---------------------------------------------------------------------------\
\ |\n| Accounts | Operations relating to user accounts, API keys, and saved user data \
\ |\n| Authentication | Authentication using an email address and password, or an API key \
\ |\n| Availability | Retrieve information describing what data is in the database \
\ |\n| Data Sources | Interact with data sources \
\ |\n| Conjunctions | Search for conjunctions between multiple sets of data sources\
\ |\n| Ephemeris | Search and manage ephemeris data associated with a data source\
\ |\n| Data Products | Search and manage data products data associated with a data\
\ source |\n| Utils | Utilities, such as describing a search query in an SQL-like\
\ format |\n\n## Authentication\n\nAuroraX allows for two methods of authentication:\n\n\
1. Authenticate via username and password using the /authenticate endpoint to obtain an access\n \
\ token. Access tokens need to be sent on every request for secure resources. Inactive access tokens\n\
\ timeout after 30 minutes.\n\n2. Authenticate using an API key sent in the request header (key\
\ called 'x-aurorax-api-key')\n\nMore information can be found\n<a href='https://docs.aurorax.space/code/advanced_usage/authentication'\
\ target='_blank'>here</a>.\n\n## Errors\n\nThis API uses standard HTTP status codes to indicate the\
\ success or failure of the\nAPI call. When an error occurs, the body of the response will be JSON\
\ and contain an error code\nand message. All errors will respond with this format:\n```\n{\n \"\
error_code\": \"DUPLICATE\",\n \"error_message\": \"There was a duplicate record found. No changes\
\ were made.\"\n}\n```\n"
version: stable
servers:
- url: https://api.aurorax.space
description: AuroraX production server
variables: {}
- url: https://api.staging.aurorax.space
description: AuroraX staging server
variables: {}
- url: http://localhost:8080/
description: Local Development and Debugging
variables: {}
tags:
- name: Availability
description: Retrieve information about data in the database
- name: Conjunction Search
description: Search for conjunctions between multiple sets of data sources
- name: Data Products Search
description: Search for data products
- name: Data Sources
description: Interact with data sources
- name: Manage Data
description: Operations relating to managing ephemeris and data products data
- name: Ephemeris Search
description: Search ephemeris records
- name: Authenticate
description: Authenticate via email and password to get an Access Token. Use your API Key if you are
building software without user interaction to run against the API.
- name: Utils
description: Various utilities
paths:
/api/v1/availability/data_products:
get:
tags:
- Availability
summary: Get the data_product availability for all Data Sources
description: Returns a count of data by day for each data source. Provide query parameters to filter
the results to just the sources you wish, in the time frames you wish
operationId: getDataProductAvailability
parameters:
- name: start
in: query
description: Start date (default to Jan 1 of this year
schema:
type: string
format: date
- name: end
in: query
description: End date (default to start + 12 months or today + 1 month if start not provided)
schema:
type: string
format: date
- name: program
in: query
description: Filter by Program
schema:
type: string
- name: platform
in: query
description: Filter by Platform
schema:
type: string
- name: instrument_type
in: query
description: Filter by Instrument Type
schema:
type: string
- name: source_type
in: query
description: Filter by Source Type
schema:
type: string
enum:
- ground
- heo
- leo
- lunar
- event_list
- not_applicable
- name: data_product_type
in: query
description: Filter by Data Product Type
schema:
type: string
enum:
- keogram
- montage
- movie
- summary_plot
- data_availability
- name: owner
in: query
description: Filter by Owner
schema:
type: string
- name: format
in: query
description: The format of the Data Source returned. Default is basic_info.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
- name: slow
in: query
description: Query the data directly (slower) for more accurate results. Default is false.
schema:
type: boolean
responses:
'200':
description: List of data_product availability.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataProduct Availability'
'400':
description: Not foundThis can occur if start or end is not in the ISO format YYYY-MM-DD.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'503':
description: 'Maintenance Mode
The API is in maintenance mode. Slow mode is currently not available.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/availability/ephemeris:
get:
tags:
- Availability
summary: Get the ephemeris availability for all Data Sources
description: Returns a count of data by day for each data source. Provide query parameters to filter
the results to just the sources you wish, in the time frames you wish
operationId: getEphemerisAvailability
parameters:
- name: start
in: query
description: Start date (default to Jan 1 of this year
schema:
type: string
format: date
- name: end
in: query
description: End date (default to start + 12 months or today + 1 month if start not provided)
schema:
type: string
format: date
- name: program
in: query
description: Filter by Program
schema:
type: string
- name: platform
in: query
description: Filter by Platform
schema:
type: string
- name: instrument_type
in: query
description: Filter by Instrument Type
schema:
type: string
- name: source_type
in: query
description: Filter by Source Type
schema:
type: string
enum:
- ground
- heo
- leo
- lunar
- event_list
- not_applicable
- name: owner
in: query
description: Filter by Owner
schema:
type: string
- name: format
in: query
description: The format of the Data Source returned. Default is basic_info.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
- name: slow
in: query
description: Query the data directly (slower) for more accurate results. Default is false.
schema:
type: boolean
responses:
'200':
description: List of ephemeris availability.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Ephemeris Availability'
'400':
description: Not foundThis can occur if start or end is not in the ISO format YYYY-MM-DD.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'503':
description: 'Maintenance Mode
The API is in maintenance mode. Slow mode is currently not available.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/conjunctions/requests/{request_id}:
get:
tags:
- Conjunction Search
summary: Get the conjunction search request details
description: This endpoint is anonymous. The request ID can be shared with anyone.
operationId: getSearchRequestDetails
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
delete:
tags:
- Conjunction Search
summary: Cancel the conjunction search request
description: Attempts to cancel the search request. If the request is already finished, attempts
to delete the associated data file. If the request could be cancledd, the log will contain an
error against the request noting the cancellation.
operationId: cancelRequest
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'204':
description: The search request finished and is no longer cancellable. The data file was deleted
if it exists.
'400':
description: Request did not contain a request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/conjunctions/requests/{request_id}/data:
get:
tags:
- Conjunction Search
summary: Get the conjunction search result data
description: Anonymous endpoint. The request ID can be shared with anyone.
operationId: getSearchResultData
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
- name: generate_ephemeris_queries
in: query
description: Return generated ephemeris queries. Default is false.
schema:
type: boolean
- name: data_source_record_format
in: query
description: Control which epehermis source data is returned. Default is basic.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
responses:
'200':
description: Get the search result data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConjunctionEvent'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
post:
tags:
- Conjunction Search
summary: Get the conjunction search result data with a data format specification
description: Anonymous endpoint. The request ID can be shared with anyone.
operationId: getSearchResultWithDatAdvancedFormatting
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SuperConjunctionEventFormat'
required: true
responses:
'200':
description: Get the search result data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConjunctionEvent'
'400':
description: The request is invalid. Please correct it and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
delete:
tags:
- Conjunction Search
summary: Delete a search result data file.
description: Deletes the data file containing the search results. If this search is run in the future,
the query will re-create the data file.
operationId: deleteDataFile
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'400':
description: Request did not contain a request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/conjunctions/search:
post:
tags:
- Conjunction Search
summary: Search for conjunctions
description: "Anonymous unless logged in. Conjunctions may occur between satellites, or between\
\ satellites and ground instruments. AuroraX maintains an index of all conjunctions for north\
\ and south B-trace footprints (or magnetic location for ground-instruments). Conjunction queries\
\ describe the conjunction relationship between sources you are interested in.\n\n Some examples\
\ of conjunction queries are: \n Find all the nbtrace conjunction events that occured in Sep-2019\
\ between any satellite in the swarm program and themisd platform that were within 200 km of\
\ each other.\n\n Find all the nbtrace conjunction events that occured in 2019 between any themis\
\ satellite and any themis-asi platform that were within 450 km of the themis-asi platform but\
\ only when the themis satellite was also in a Dayside Magnetosphere (D_Msphere) region of space.\n\
\n Data returned when a ground-instrument is involved returns the time ranges for when that instrument\
\ was operational."
operationId: searchMulti
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SuperConjunctionQuery'
required: true
responses:
'400':
description: 'Missing or invalid parameters.
Please refer to the documentation for correctness of this operation.'
/api/v1/data_products/requests/{request_id}:
get:
tags:
- Data Products Search
summary: Get the data_product search request details
description: This endpoint is anonymous. The request ID can be shared with anyone.
operationId: getSearchRequestDetails_1
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
delete:
tags:
- Data Products Search
summary: Cancel the data_product search request
description: Attempts to cancel the search request. The system will log an error against the request
noting the cancellation.
operationId: cancelRequest_1
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'400':
description: Request did not contain a request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/data_products/requests/{request_id}/data:
get:
tags:
- Data Products Search
summary: Get the data_product search result data
description: Get the data returned by the given search request. If the data has expired, then 404
will be returned.
operationId: getSearchResultData_1
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
- name: data_source_record_format
in: query
description: Control which epehermis source data is returned. Default is basic.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
responses:
'200':
description: Get the search result data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataProduct'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
post:
tags:
- Data Products Search
summary: Get the data_product search result data with a data format specification
description: Get the data returned by the given search request. If the data has expired, then 404
will be returned.
operationId: getSearchResultDataWithAdvancedFormatting
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductFormat'
required: true
responses:
'200':
description: Get the search result data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataProduct'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
delete:
tags:
- Data Products Search
summary: Delete a search result data file.
description: Deletes the data file containing the search results. If this search is run in the future,
the query will re-create the data file.
operationId: deleteDataFile_1
parameters:
- name: request_id
in: path
description: The request ID
required: true
schema:
type: string
responses:
'200':
description: The request details
content:
application/json:
schema:
$ref: '#/components/schemas/SearchQueryResponse'
'400':
description: Request did not contain a request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: No request with given request id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/data_products/search:
post:
tags:
- Data Products Search
summary: Search for data products
description: Data products have their own metadata and can be filtered on those. Additionally, because
data products are also linked to one or more data sources, they can also be found by adding metadata
filters to data source criteria
operationId: search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductQuery'
required: true
responses:
'400':
description: 'Missing or invalid parameters.
Please refer to the documentation for correctness of this operation.'
/api/v1/data_products/search_synchronous:
post:
tags:
- Data Products Search
summary: Synchronously search for data products
description: Anonymous unless logged in. The same search functionality as asynchronous search, except
it is synchronous. Search results are limited to 10 years of data products. These requests are
not saved, even if you are logged in.
operationId: searchSynchronous
parameters:
- name: data_source_record_format
in: query
description: Control how the data product data source data is returned. Default is basic.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductQueryWithResponseFormat'
required: true
responses:
'200':
description: List of data products
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataProduct'
'400':
description: 'Missing or invalid parameters.
Please refer to the documentation for correctness of this operation.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
/api/v1/data_sources:
get:
tags:
- Data Sources
summary: List all data sources
description: Data Sources are entities like satellites and ground stations (platforms) that produce
data.
operationId: getList
parameters:
- name: program
in: query
description: Filter by Program
schema:
type: string
- name: platform
in: query
description: Filter by Platform
schema:
type: string
- name: instrument_type
in: query
description: Filter by Instrument Type
schema:
type: string
- name: source_type
in: query
description: Filter by Source Type
schema:
type: string
enum:
- ground
- heo
- leo
- lunar
- event_list
- not_applicable
- name: owner
in: query
description: Filter by Owner
schema:
type: string
- name: format
in: query
description: The format of the Data Source returned. Default is basic_info.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
- name: include_stats
in: query
description: Include the data_source stats with the response. Default is false.
schema:
type: boolean
responses:
'200':
description: List of data sources.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Data Source'
post:
tags:
- Data Sources
summary: Add an Data Source record
description: "*Must have the Administrator or Owner role to perform this operation* \n\n*Must be\
\ authenticated*"
operationId: add_1
requestBody:
description: The Data Source record to add
content:
application/json:
schema:
$ref: '#/components/schemas/Data Source'
required: true
responses:
'200':
description: Data Source record created
content:
application/json:
schema:
$ref: '#/components/schemas/Data Source'
'400':
description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this\
\ operation."
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'401':
description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid\
\ API key\n * Invalid access token\n * Access token expired"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'403':
description: 'Not Permitted
Only the Data Source Owner or an Administrator may create new data sources.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'409':
description: "Duplicate. \nThere is already a Data Source record with this identifier"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'503':
description: 'Maintenance Mode
The API is in maintenance mode. This endpoint is currently offline.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
security:
- ApiKeyAuth: []
- AccessToken: []
/api/v1/data_sources/{identifier}:
get:
tags:
- Data Sources
summary: Get details about a Data Source
operationId: getDetail
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
- name: format
in: query
description: The format of the Data Source returned. Default is basic_info.
schema:
type: string
enum:
- identifier_only
- basic_info
- with_metadata
- full_record
- name: include_stats
in: query
description: Include the data_source stats with the response. Default is false.
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Data Source'
'400':
description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this\
\ operation."
'404':
description: identifier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
put:
tags:
- Data Sources
summary: Update an Data Source record
description: "*Must be an Administrator or be the Owner of this record* \n\n*Must be authenticated*"
operationId: update_1
parameters:
- name: identifier
in: path
description: The identifier of the Data Source
required: true
schema:
type: integer
format: int32
requestBody:
description: The Data Source record to update
content:
application/json:
schema:
$ref: '#/components/schemas/Data Source'
required: true
responses:
'200':
description: Data Source record updated
content:
application/json:
schema:
$ref: '#/components/schemas/Data Source'
'400':
description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this\
\ operation."
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'401':
description: "Not Authorized. \nCould be attributable to any of the following:\n\n\n * Invalid\
\ API key\n * Invalid access token\n * Access token expired"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'403':
description: 'Not Permitted
Only the Data Source Owner or an Administrator may update data sources.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'404':
description: identifier not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'409':
description: "Duplicate. \nThere is already an Data Source record for this identifier"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'503':
description: 'Maintenance Mode
The API is in maintenance mode. This endpoint is currently offline.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
security:
- ApiKeyAuth: []
- AccessToken: []
delete:
tags:
- Data Sources
summary: Delete an Data Source record
description: "*Must be an Owner of the Data Source or an Administrator in order to perform this\
\ operation* \n\n*Must be authenticated*"
operationId: delete_1
parameters:
- name: identifier
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-calgary/refs/heads/main/openapi/university-of-calgary-aurorax-api.yaml