Search for data products
openapi: 3.0.1
info:
title: AuroraX Application.wadl Data Products Search 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: Data Products Search
description: Search for data products
paths:
/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'
components:
schemas:
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
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.
DataProduct:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
data_source:
$ref: '#/components/schemas/Data Source'
url:
type: string
data_product_type:
type: string
enum:
- keogram
- montage
- movie
- summary_plot
- data_availability
metadata:
type: string
DataProductFormat:
type: object
properties:
start:
type: boolean
end:
type: boolean
data_source:
$ref: '#/components/schemas/DataSourceFormat'
url:
type: boolean
data_product_type:
type: boolean
metadata:
type: boolean
description: The advanced format to use in the response object data
DataProductQueryWithResponseFormat:
required:
- query
type: object
properties:
query:
$ref: '#/components/schemas/DataProductQuery'
response_format:
$ref: '#/components/schemas/DataProductFormat'
description: DataProduct Query with Response Format
DataSourceFormat:
type: object
properties:
identifier:
type: boolean
program:
type: boolean
platform:
type: boolean
instrument_type:
type: boolean
source_type:
type: boolean
display_name:
type: boolean
ephemeris_metadata_schema:
$ref: '#/components/schemas/MetadataSchemaFormat'
data_product_metadata_schema:
$ref: '#/components/schemas/MetadataSchemaFormat'
owner:
type: boolean
maintainers:
type: boolean
metadata:
type: boolean
JsonNode:
type: object
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
MetadataSchema:
type: object
properties:
field_name:
type: string
description: The name of the field found in the ephemeris metadata
description:
type: string
description: A brief description of what the metadata field represents
data_type:
type: string
description: An indicator to let you know what filter operations are available. Strings allow for =, !=, and in. Decimals allow for =, !=, <, >, <=, >=, and in.
allowed_values:
type: array
description: An optional list of possible values available in the metadata.
items:
type: string
description: An optional list of possible values available in the metadata.
additional_description:
type: string
description: More details about what this metadata field is about
searchable:
type: boolean
description: Used by UI's to include it in metadata fields exposed as searchable through the conjunction interface. The API allows for all fields to be searchable but some applications may chose to hide any fields marked searchable=false
description: Describes the metadata fields found on Ephemeris data.
DataSourceStats:
type: object
properties:
data_source:
$ref: '#/components/schemas/Data Source'
earliest_ephemeris_loaded:
type: string
format: date-time
latest_ephemeris_loaded:
type: string
format: date-time
ephemeris_count:
type: integer
format: int32
earliest_data_product_loaded:
type: string
format: date-time
latest_data_product_loaded:
type: string
format: date-time
data_product_count:
type: integer
format: int32
description: Some basic stats about this data_source, like number of ephemeris records. Read only.
SearchRequest:
type: object
properties:
request_id:
type: string
query:
type: string
requested:
type: string
format: date-time
request_type:
type: string
enum:
- conjunction
- ephemeris
- data_product
description: The original search request
MetadataSchemaFormat:
type: object
properties:
field_name:
type: boolean
description:
type: boolean
data_type:
type: boolean
allowed_values:
type: boolean
additional_description:
type: boolean
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
SearchResult:
type: object
properties:
data_uri:
type: string
result_count:
type: integer
format: int32
result_file_deleted_timestamp:
type: string
format: date-time
file_size:
type: integer
format: int64
completed_timestamp:
type: string
format: date-time
query_duration:
type: integer
format: int64
error_condition:
type: boolean
description: Search result
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).
SearchQueryResponse:
type: object
properties:
search_request:
$ref: '#/components/schemas/SearchRequest'
logs:
type: array
items:
$ref: '#/components/schemas/SearchRequestLog'
search_result:
$ref: '#/components/schemas/SearchResult'
description: Search query response details
Data Source:
required:
- display_name
- instrument_type
- platform
- program
- source_type
type: object
properties:
identifier:
type: integer
description: Uniquely identifies this record. Optional when adding a new source record; system generated, unless this is a replacement (e.g., delete old, create new with same identifier as old).
format: int32
program:
type: string
description: 'Examples: themis, themis-asi, rbsp'
platform:
type: string
description: 'Examples: themisa, gill, rbspb'
instrument_type:
type: string
description: 'Examples: pancromatic-asi'
source_type:
type: string
description: g = Ground, h = Highly Eliptical Orbit, l = Low Earth Orbit
enum:
- ground
- heo
- leo
- lunar
- event_list
- not_applicable
display_name:
type: string
description: A friendly display name for web applications
ephemeris_metadata_schema:
type: array
description: The ephemeris metadata schema and descriptions
items:
$ref: '#/components/schemas/MetadataSchema'
data_product_metadata_schema:
type: array
description: The data_product metadata schema and descriptions
items:
$ref: '#/components/schemas/MetadataSchema'
owner:
type: string
description: The Owner of this Data Source record. Defaults to the currently logged in user.
maintainers:
type: array
description: The list of Maintainers
items:
type: string
description: The list of Maintainers
stats:
$ref: '#/components/schemas/DataSourceStats'
metadata:
$ref: '#/components/schemas/JsonNode'
description: Things that produce data, like satellites, ground stations/instruments, platforms
SearchRequestLog:
type: object
properties:
timestamp:
type: string
format: date-time
level:
type: string
enum:
- debug
- info
- warn
- error
summary:
type: string
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