Various utilities
openapi: 3.0.1
info:
title: AuroraX Application.wadl Utils 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\n1. 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: Utils
description: Various utilities
paths:
/api/v1/utils/timezones/convert:
get:
tags:
- Utils
summary: Given a timestamp in ISO format and a timezone, return the UTC equivelant
description: This is the same operation for Citizen Science timestamps that are provided, but allows for preview of the calculated value
operationId: calcUtc
parameters:
- name: ts
in: query
description: The timestamp
schema:
type: string
format: date-time
- name: tz
in: query
description: The timezone ts is in
schema:
type: string
responses:
'200':
description: Timestamp in UTC
content:
application/json:
schema:
type: array
items:
type: string
/api/v1/utils/describe/cartesian_products:
post:
tags:
- Utils
summary: Returns a count of cartesian products (tuples of data sources) of the given conjunction search object. This number is the combinations simple conjunction tuples between each data source found through the criteria block
operationId: cartesianProduct
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SuperConjunctionQuery'
required: true
responses:
'200':
description: The count of cartesian products found
content:
application/json: {}
/api/v1/utils/admin/search_requests/{request_id}:
delete:
tags:
- Utils
summary: Delete a search request
description: "Removes this search request and all associated data. \n\n*Must be authenticated*"
operationId: deleteSearchRequest
parameters:
- name: request_id
in: path
description: The search request ID
required: true
schema:
type: string
responses:
'200':
description: The search request was delete
'400':
description: Invalid request. Please consult the documentation and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'401':
description: 'Not Authorized
Must be authenticated as an Administrator to remove a search request.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'403':
description: 'Not Permitted
Only an Administrator may list active searches.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
security:
- ApiKeyAuth: []
- AccessToken: []
/api/v1/utils/admin/search_requests:
get:
tags:
- Utils
summary: List search summaries
description: "List searches, optionally filtering by: active, type (ephemeris, data_product, conjunction), between start/end, file_size >=, result_count >=, query_duration >=, has error_condition \n\n*Must be authenticated*"
operationId: findSearchRequests
parameters:
- name: active
in: query
description: 'Filter by active. True: active only, false: completed only, omit: both'
schema:
type: boolean
- name: search_type
in: query
description: 'Filter by Search Type. Omit: all'
schema:
type: string
enum:
- conjunction
- ephemeris
- data_product
- name: start
in: query
description: Filter by start. Later than or equal if provided or omit for all before end
schema:
type: string
format: date-time
- name: end
in: query
description: Filter by end. Earlier than or equal if provided or omit for all before start
schema:
type: string
format: date-time
- name: file_size
in: query
description: Filter by file size. Greater than or equal if provided or omit for all file sizes (kilobytes). Overrides active to be false.
schema:
type: integer
format: int64
- name: result_count
in: query
description: Filter by result count. Greater than or equal if provided or omit for all result counts. Overrides active to be false.
schema:
type: integer
format: int32
- name: query_duration
in: query
description: Filter by query duration (millis). Greater than or equal if provided or omit for any duration
schema:
type: integer
format: int64
- name: error_condition
in: query
description: 'Filter by queries with an error condition. Ignored if filtering for active queries. True: must have error, false: must not have error, omit: both'
schema:
type: boolean
responses:
'200':
description: List of search summaries.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SearchRequestListing'
'400':
description: Invalid request. Please consult the documentation and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'401':
description: 'Not Authorized
Must be authenticated as an Administrator to list search requests.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
'403':
description: 'Not Permitted
Only an Administrator may list search requests.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDocument'
security:
- ApiKeyAuth: []
- AccessToken: []
/api/v1/utils/timezones:
get:
tags:
- Utils
summary: List available time zones
description: List available time zones. These should be standard from the TZ Database. In javascript, it is possible to use Intl.supportedValuesOf('timeZone') for valid values.
operationId: listTimeZones
responses:
'200':
description: List of time zones.
content:
application/json:
schema:
type: array
items:
type: string
/api/v1/utils/describe/query/conjunction:
post:
tags:
- Utils
summary: Parses the query into an 'SQL like' query expression
operationId: parse
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SuperConjunctionQuery'
required: true
responses:
'200':
description: The parsed query
content:
application/json:
schema:
type: array
items:
type: string
/api/v1/utils/describe/query/data_products:
post:
tags:
- Utils
summary: Parses the query into an 'SQL like' query expression
operationId: parse_1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductQuery'
required: true
responses:
'200':
description: The parsed query
content:
application/json:
schema:
type: array
items:
type: string
/api/v1/utils/describe/query/ephemeris:
post:
tags:
- Utils
summary: Parses the query into an 'SQL like' query expression
operationId: parse_2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EphemerisQuery'
required: true
responses:
'200':
description: The parsed query
content:
application/json:
schema:
type: array
items:
type: string
components:
schemas:
DataSourceCriteriaForEphemeris:
type: object
properties:
programs:
type: array
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
items:
type: string
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
platforms:
type: array
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
items:
type: string
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
instrument_types:
type: array
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
items:
type: string
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
ephemeris_metadata_filters:
$ref: '#/components/schemas/MetadataExpressionGroup'
description: Find Ephemeris data for these Data Sources. This could be a single platform (e.g., gillam; or swarma), or an entire program containing a group of platforms (e.g., all locations in the themis-asi program; or all satellites in the themis program).
EphemerisCriteriaGround:
type: object
properties:
programs:
type: array
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
items:
type: string
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
platforms:
type: array
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
items:
type: string
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
instrument_types:
type: array
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
items:
type: string
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
ephemeris_metadata_filters:
$ref: '#/components/schemas/MetadataExpressionGroup'
description: Defines the ephemeris particpants in the conjunction that are ground stations. Participants in each these criteria are OR'd while participants in different criteria are AND'd.
SuperConjunctionQuery:
type: object
properties:
request_id:
type: string
description: An optional request_id to be used for this query. Ommit to have the API generate one for you. If you are using websockets, this id can be used establish a websocket before sending the search request to avoid a race condition of the query finishing before websocket is established. This technique is used by the AuroraX website
ground:
type: array
description: Defines the ephemeris particpants in the conjunction that are ground stations. Participants in each these criteria are OR'd while participants in different criteria are AND'd.
items:
$ref: '#/components/schemas/EphemerisCriteriaGround'
space:
type: array
description: Defines the ephemeris particpants in the conjunction that are satellites. Participants in each of these criteria are OR'd while participants in different criteria are AND'd.
items:
$ref: '#/components/schemas/EphemerisCriteriaSpace'
events:
type: array
description: Defines the particpants in the conjunction that are events. Participants in each of these criteria are OR'd while participants in different criteria are AND'd.
items:
$ref: '#/components/schemas/EphemerisCriteriaEvent'
adhoc:
type: array
description: Defines the particpants in the conjunction that are locations of your choice. Participants in each of these criteria are OR'd while participants in different criteria are AND'd.
items:
$ref: '#/components/schemas/EphemerisCriteriaAdhocLatLon'
start:
type: string
description: Return conjunction events that occured after this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
end:
type: string
description: Return conjunction events that occured before this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
conjunction_types:
type: array
description: Return conjunctions of any North B-Trace, Sourth B-Trace, and Geo Location.
items:
type: string
description: Return conjunctions of any North B-Trace, Sourth B-Trace, and Geo Location.
enum:
- nbtrace
- sbtrace
- geographic
max_distances:
type: object
additionalProperties:
type: integer
description: Return conjunctions there were within this distance (km) between criteria blocks. ground-ground defaults to 0. Null defaults to 2^31.
format: int32
description: Return conjunctions there were within this distance (km) between criteria blocks. ground-ground defaults to 0. Null defaults to 2^31.
example:
ground1-space1: 300
ground2-space1: 400
ground1-events1: 900
space1-space2: null
adhoc1-space1: 700
epoch_search_precision:
type: integer
description: Runs the query with higher fidelity and interpolates each 30 second epoch. Queries can be much slower using this method, but a greater number of results may be found.
format: int32
default: 60
enum:
- 30
- 60
description: There must be at least 2 Ephemeris Criteria in order to calculate the distance between them in a conjunction.
SearchRequestListing:
type: object
properties:
search_type:
type: string
description: The type of search request (e.g., ephemeris, conjunction, etc.)
enum:
- conjunction
- ephemeris
- data_product
ip_address:
type: string
description: The IP address that requested the search
request_id:
type: string
description: The unique request id
requested:
type: string
description: The date and time when the search was requested
format: date-time
active:
type: boolean
description: The request is currently active (not completed).
query_duration:
type: integer
description: How long the query is/was running for in milliseconds
format: int64
result_file_exists:
type: boolean
description: True if the result file still exists
file_size:
type: integer
description: The size of the file in bytes (even if deleted, the size of the file that was). Null if there is no result file found.
format: int64
result_count:
type: integer
description: The number of results this search yielded. Null if there is no result yet.
format: int32
error_condition:
type: boolean
description: If the search ended with an error condition
description: Search request listing
MetadataExpression:
type: object
properties:
key:
type: string
description: The metadata key found as described in the data_source metadata schema record
operator:
type: string
description: The filter expression operator
enum:
- '='
- <
- <=
- '>'
- '>='
- '!='
- in
- not in
- between
values:
type: array
description: The value(s) to test for. Note that 'in' and 'not-in' accept a list of values; 'between' accepts two values; all others accept just one value
items:
type: string
description: The value(s) to test for. Note that 'in' and 'not-in' accept a list of values; 'between' accepts two values; all others accept just one value
description: An expression like a where clause in SQL
EphemerisCriteriaEvent:
type: object
properties:
programs:
type: array
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
items:
type: string
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
platforms:
type: array
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
items:
type: string
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
instrument_types:
type: array
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
items:
type: string
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
ephemeris_metadata_filters:
$ref: '#/components/schemas/MetadataExpressionGroup'
description: Defines the particpants in the conjunction that are events. Participants in each of these criteria are OR'd while participants in different criteria are AND'd.
EphemerisCriteriaSpace:
type: object
properties:
programs:
type: array
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
items:
type: string
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
platforms:
type: array
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
items:
type: string
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
instrument_types:
type: array
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
items:
type: string
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
hemisphere:
type: array
description: Filter these satellites to the hemisphere they are currently in geographicly
items:
type: string
description: Filter these satellites to the hemisphere they are currently in geographicly
enum:
- northern
- southern
ephemeris_metadata_filters:
$ref: '#/components/schemas/MetadataExpressionGroup'
description: Defines the ephemeris particpants in the conjunction that are satellites. Participants in each of these criteria are OR'd while participants in different criteria are AND'd.
Location:
type: object
properties:
lat:
maximum: 90
minimum: -90
type: number
lon:
maximum: 180
minimum: -180
type: number
description: A list of latitude and longitude locations of your choice
MetadataExpressionGroup:
type: object
properties:
logical_operator:
type: string
description: Specifies if these filters should be OR'd or AND'd. If omitted, the default is to AND the expressions together
enum:
- AND
- OR
expressions:
type: array
description: The list of filter expressions
items:
$ref: '#/components/schemas/MetadataExpression'
description: An expression group to allow for OR'd or AND'd expression filters
DataSourcesCriteriaForDataProducts:
type: object
properties:
programs:
type: array
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
items:
type: string
description: The list of programs in e1 or e2. Programs group platforms. Programs are like 'themis', 'swarm', 'themis-asi', 'TRex'
platforms:
type: array
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
items:
type: string
description: The list of platforms in e1 or e2. Platforms are like 'themis-asi gill' or 'swarma'. Use this to narrow the set of sources within the programs listed.
instrument_types:
type: array
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
items:
type: string
description: The list of instrument-types in e1 or e2. Instrument types are like 'panchromatic-asi'. A platform may have zero or more instrument types.
data_product_metadata_filters:
$ref: '#/components/schemas/MetadataExpressionGroup'
description: Find data products generated from data of these Data Sources. This could be a single platform (e.g., gillam; or swarma), or an entire program containing a group of platforms (e.g., all locations in the themis-asi program; or all satellites in the themis program).
DataProductQuery:
type: object
properties:
request_id:
type: string
description: An optional request_id to be used for this query. Ommit to have the API generate one for you. If you are using websockets, this id can be used establish a websocket before sending the search request to avoid a race condition of the query finishing before websocket is established. This technique is used by the AuroraX website
data_sources:
$ref: '#/components/schemas/DataSourcesCriteriaForDataProducts'
start:
type: string
description: Return data products that have a start date equal or after this this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
end:
type: string
description: Return data products that have an end date equal of before this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
data_product_type_filters:
type: array
description: Filter the data products to return only these data product types.
items:
type: string
description: Filter the data products to return only these data product types.
enum:
- keogram
- montage
- movie
- summary_plot
- data_availability
EphemerisCriteriaAdhocLatLon:
required:
- locations
type: object
properties:
locations:
type: array
description: A list of latitude and longitude locations of your choice
items:
$ref: '#/components/schemas/Location'
description: Defines a geographical location (latitude, longitude) on Earth's surface to use as a criterion for calculating distance measurements between other criteria objects
ErrorDocument:
type: object
properties:
error_message:
type: string
description: If an error code exists, this will have contextual information for debugging
error_code:
type: string
description: The error code
enum:
- Nil
- Ok
- NotPermitted
- NotAuthorized
- Duplicate
- AssertionError
- NotFound
- ApplicationError
- NotImplemented
- ToManyRequests
- Other
- Conflict
- NotAuthenticated
- Unavailable
description: This model provides additional details about error conditions that can be used for debugging.
EphemerisQuery:
required:
- data_sources
type: object
properties:
request_id:
type: string
description: An optional request_id to be used for this query. Ommit to have the API generate one for you. If you are using websockets, this id can be used establish a websocket before sending the search request to avoid a race condition of the query finishing before websocket is established. This technique is used by the AuroraX website
data_sources:
$ref: '#/components/schemas/DataSourceCriteriaForEphemeris'
start:
type: string
description: Return ephemeris data that occured after this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
end:
type: string
description: Return ephemeris data that occured before this timestamp. Optional. Large time windows may take a long time for results to return.
format: date-time
securitySchemes:
AccessToken:
type: http
description: Send the Authorization header found in the response of a successful /authentication request on all secure endpoints. Copy it verbatim to the request header. It is fine to send this header on all requests to the API. The value in Swagger UI should only include the access token part (leave out 'Bearer').
name: Authorization
in: header
scheme: bearer
bearerFormat: Generated by server
ApiKeyAuth:
type: apiKey
description: API keys are intended to be used by non-interactive software interfacing with the REST API. These can be used instead of an Access Token approach.
name: x-aurorax-api-key
in: header