Various helper endpoints
openapi: 3.0.1
info:
title: AuroraX Application.wadl Utilities 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: Utilities
description: Various helper endpoints
paths:
/api/v1/utils/terminator:
get:
tags:
- Utilities
summary: Retrieve terminator coordinates
description: "Retrieve coordinates for the terminator. \n\nThe timestamp parameter should be supplied in the format \"YYYY-MM-DDTHH:mm:ss\". \nUTC is the expected timezone.\n\nThe angle parameter is used for retrieving the terminator for civil, nautical, \nor astronomical twilight. Use the values -6.0, -12.0, or -18.0 for each of these \nterminators, respectively.\n\nNotes:\n - The algorithm does not account for altitude at this time\n - By default requests are cached. Use the 'no_cache' parameter to disable this functionality."
operationId: get_terminator_api_v1_utils_terminator_get
parameters:
- name: timestamp
in: query
required: true
schema:
type: string
format: date-time
title: Timestamp
- name: angle
in: query
required: false
schema:
type: number
default: -12.0
title: Angle
- name: no_cache
in: query
required: false
schema:
type: boolean
default: false
title: No Cache
responses:
'200':
description: Terminator coordinates
content:
application/json:
schema:
$ref: '#/components/schemas/Terminator'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/utils/magnetic_grid:
get:
tags:
- Utilities
summary: Retrieve geomagnetic coordinate grid
description: "Retrieve a geomagnetic coordinate grid for a given timestamp.\n\nThe timestamp parameter should be supplied in the format \"YYYY-MM-DDTHH:mm:ss\". \nUTC is the expected timezone.\n\nThe grid consists of meridian lines (constant magnetic longitude, \"vertical\") and parallel lines\n(constant magnetic latitude, \"horizontal\") for both northern and southern hemispheres.\n\nNotes\n - The resolution_lon and resolution_lat parameters control the spacing (in degrees) between\nmagnetic longitude and latitude lines, respectively. Lower values produce a denser grid.\n - By default requests are cached. Use the 'no_cache' parameter to disable this functionality."
operationId: get_magnetic_grid_api_v1_utils_magnetic_grid_get
parameters:
- name: timestamp
in: query
required: true
schema:
type: string
format: date-time
title: Timestamp
- name: resolution_lon
in: query
required: false
schema:
type: number
default: 10.0
title: Resolution Lon
- name: resolution_lat
in: query
required: false
schema:
type: number
default: 5.0
title: Resolution Lat
- name: min_latitude
in: query
required: false
schema:
type: number
default: 50.0
title: Min Latitude
- name: altitude_km
in: query
required: false
schema:
type: number
default: 0.0
title: Altitude Km
- name: no_cache
in: query
required: false
schema:
type: boolean
default: false
title: No Cache
responses:
'200':
description: Geomagnetic grid in geographic coordinates
content:
application/json:
schema:
$ref: '#/components/schemas/MagneticGrid'
'400':
description: Problematic request made
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Terminator:
properties:
timestamp:
type: string
format: date-time
title: Timestamp
coords:
items: {}
type: array
title: Coords
type: object
required:
- timestamp
- coords
title: Terminator
MagneticGrid:
properties:
timestamp:
type: string
format: date-time
title: Timestamp
north:
$ref: '#/components/schemas/MagneticGridHemisphere'
south:
$ref: '#/components/schemas/MagneticGridHemisphere'
type: object
required:
- timestamp
- north
- south
title: MagneticGrid
ErrorMessage:
properties:
detail:
type: string
title: Detail
type: object
required:
- detail
title: ErrorMessage
MagneticGridHemisphere:
properties:
vertical:
items:
items:
items:
type: number
type: array
type: array
type: array
title: Vertical
horizontal:
items:
items:
items:
type: number
type: array
type: array
type: array
title: Horizontal
type: object
required:
- vertical
- horizontal
title: MagneticGridHemisphere
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