Saber Astronautics Data API Reference
Welcome to Saber Astronautic’s Space Data API! This API can be used to access a range of space weather services, such as ...
Infrastructure is using a REST framework.
Admin and Authentication
To get started, full access to the Saber Space Data API requires a PIGI Licence.
Refer to our website for more information on Saber Astronautics Data Services and available subscription packages.
Login and Access Token creation
post
endpoint: /login
To generate an access token, run the following script
The call will either return a warning (in which case the user details were incorrect) or the relevant json dict.
curl -X POST 'http://saberdata.space/login' \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F username=<username> \
-F password=<password>
import requests
url = "https://saberdata.space/login"
username = <username>
password = <password>
payload = {
'username': username,
'password': password
}
response = requests.post(url, data=payload)
print(response.text)
To generate an authentication token, send your user details to the login endpoint, passing in the required query parameters. From there you access your authentication token via the "access_token"
parameter. This access token will remain valid for 15 minutes, after which a refresh token is used to regain access.
Query params
Parameter | Description |
---|---|
username |
string (required) SaberData Login Username |
password |
string (required) SaberData Login Password |
The JSON encoded response looks like this
{
"access_token": <access token>,
"active_subscriptions": [
{
"name": "PIGI Casual 3 Month",
"next_billing_date": "Tue, 05 Mar 2019 00:00:00 GMT",
"status": "Active"
},
{
"name": "PIGI Casual 1 Month",
"next_billing_date": "Sat, 16 Feb 2019 00:00:00 GMT",
"status": "Inactive",
},
"current_version": "0.8.5",
"message": "Logged in",
"refresh_token": <refresh token>
}
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
access_token |
int Access token string required for accessing data resources on the API. | JWT |
refresh_token |
string Refresh token string required for periodically refreshing the access token. | JWT |
message |
string Response message. | |
current_version |
string The current version of the P.I.G.I. software package. | major.minor.revision |
active_subscriptions |
list List of current subscriptions attached to your account. With details of status, subscription type and next billing date. | |
teams |
list Only available to Team and Enterprise users. List of teams your account is attached to. Organisation name, status and licence type. |
Refresh an expired Access Token
get
endpoint: /refresh
import requests
url = "https://saberdata.space/refresh"
headers = {
'Authorization': "Bearer <access_token>",
}
response = requests.get(url, headers=headers)
print(response.text)
To refresh your access token after it has expired, send a GET request to the refresh endpoint. The refresh token is retrieved as part of the returned JSON object upon a successful login attempt.
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <refresh_token> |
The JSON encoded response looks like this
{
"access_token": <new_access_token>
}
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
access_token |
string Access token string required for accessing data assets | JWT |
Space Weather Data
A number of space weather data tables are available from the Saber API. These are listed below and can be accessed via with the table name keyword variable in the Data Tables and Latest Space Weather endpoints.
Available Tables
Name | Description | Table Keyword |
---|---|---|
GOES EPED |
GOES Energetic Proton, Electron, and Alpha Detectors sensor onboard GOES West | goes_epead |
GOES X-ray |
GOES X-ray sensor onboard GOES West | goes_xray |
GOES Magnetic |
GOES Magnetic Field sensor onboard GOES West | goes_epead |
GOES Extreme UV |
GOES Extreme Ultraviolet sensor onboard GOES West | goes_euv |
GOES Alphas |
GOES Alpha Detectors sensor onboard GOES West | goes_alphas |
Real Time Solar Wind |
Real Time Solar Wind, Temperature, Speed and Density as returned from the currently active satellite at the L1 Lagrange point. Either NASA ACE or DSCOVR. | rtsw_solar_wind |
RTSW - Magnetic Field |
Real Time Solar Wind Magnetic fields as returned from the currently active satellite at the L1 Lagrange point in the Earth-Sun system. Either NASA ACE or DSCOVR. | rtsw_mag |
RTSW - Solar Isotope Spectrometer |
Real Time Solar Wind Solar Isotope Spectrometer sensor. | rtsw_sis |
RTSW - SWEPAM |
Real Time Solar Wind Electron, Proton and Alpha monitor. Solar Wind Ions as retrieved from the NASA ACE satellite. | rtsw_swepam |
ACE - EPAM |
Energetic Ions and Electrons from the NASA ACE Electron Proton and Alpha Monitor. | ace_epam |
ACE - Magnetic Field |
Magnetic field vectors as detected by the NASA ACE satellite. | ace_mag |
Geomagenetic KP Index |
Geomagnetic storm "P" index. | kp_index |
10.7cm Solar Flux |
Solar radio flux at 10.7cm (2800MHz). Used as an indicator of solar activity. | solar_flux |
Space Weather Data Tables
get
endpoint: /spwx
To retrieve batch data from an individual table or group of tables, the /spwx endpoint is used. Data update speed and refresh rate is limited to your user licence type.
To retrieve space weather information, run the following code.
The call will either return an error (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
The call will either return None (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
curl -X GET 'http://saberdata.space/spwx?<queryparams>' \
-H 'Authorization: Bearer <access_token>' \
-H 'cache-control: no-cache'
import requests
url = "http://saberdata.space/spwx"
querystring = {
"tables": <tables>,
"end_time": <end_time>,
"start_time": <start_time>,
}
headers = {
'Authorization': "Bearer <access token>",
}
response = requests.get(url, headers=headers, params=querystring)
print(response.text)
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <access_token> |
content-type |
string (required) Returned content type | application/json |
Query params
Parameter | Description | Default |
---|---|---|
start_time |
timestamp (optional) Start time in UTC to be retrieved from. Format: YYYY-MM-DDTHH:MM:SS | Current time UTC minus 5 minutes |
end_time |
timestamp (optional) Finish time in UTC to be retrieved from. Format: YYYY-MM-DDTHH:MM:SS | Current time UTC |
tables |
stringList of tables to be retrieved. If more than a single table, the list delimiter is a colon (:). Format: table_name1:table_name2:table_name3 | None |
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
table_name |
variable Listed space weather data of the requested table. | As decribed in the relevant table data dictionary below |
Latest Space Weather Data
get
endpoint: /spwx/<tablekeyword>
To retrieve the latest data from individual tables, the /spwx/<tablekeyword> endpoint is used. Data update speed and refresh rate is limited to your user licence type.
To retrieve space weather information, run the following code.
The call will either return an error (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
The call will either return None (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
curl -X GET 'http://saberdata.space/spwx/<tablekeyword>' \
-H 'Authorization: Bearer <access_token>' \
-H 'cache-control: no-cache'
import requests
url = "http://saberdata.space/spwx/<tablekeyword>"
headers = {
'Authorization': "Bearer <access_token>",
}
response = requests.get(url, headers=headers)
print(response.text)
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <access_token> |
content-type |
string (required) Returned content type | application/json |
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
data |
variable Space weather data. | As decribed in the relevant table data dictionary below |
Current Space Weather Storm Status
get
endpoint: /spwx/status
To retrieve information relating to the space weather status , run the following code.
The call will either return an error (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
The call will either return None (in which case the specified dataset wasn’t found or had no data) or the relevant json dict.
curl -X GET 'http://saberdata.space/spwx/status' \
-H 'Authorization: Bearer <access token>' \
-H 'cache-control: no-cache'
import requests
url = "http://saberdata.space/spwx/status"
headers = {
'Authorization': "Bearer <access_token>",
}
response = requests.get(url, headers=headers)
print(response.text)
Status Data Description
The JSON encoded response looks like this
{
"status": {
"g_hazard": 3,
"g_hazard_max": 3.33,
"r_hazard": 2.45929010489476e-9,
"r_hazard_max": 2.08220001240988e-8,
"retrieved_at": "Tue, 05 Feb 2019 01:21:10 GMT",
"s_hazard": 0.1526,
"s_hazard_max": 0.3983
}
The current space weather status as defined by the NOAA scales which descipbe the space environment and it's effects upon people and infrastructure.
Field | Description | Unit |
---|---|---|
g_hazard | Latest Kp value. Measure of geomagnetic storm risk. |
|
g_hazard_max | Maximum Kp value measured over the past 24 hours. |
|
r_hazard | Latest Long X-ray flux (1 - 8 angstroms). Measure of radio blackout risk. | W/m2 |
r_hazard_max | Maximum Long X-ray flux (1 - 8 angstroms) measured over the past 24 hours. | W/m2 |
retrieved_at | Time of data retrieval. | Datetime |
s_hazard | Latest Flux level of > 10 MeV particles (ions). Measure of solar radation storm risk. | particle⋅cm-2⋅s-1⋅ster-1 |
s_hazard_max | Maximum Flux level of > 10 MeV particles (ions) measured over the past 24 hours. | particle⋅cm-2⋅s-1⋅ster-1 |
Data dictionaries
The following tables are descriptions of the data retrievable from the space weather tables and latest space weather data endpoints.
GOES EPEAD (Energetic Proton, Electron, and Alpha Detectors) Data Descripton
The JSON encoded response looks like this
{
"goes_epead": [
{
"ce1": 917.289001464844,
"ce2": 0.234077006578445,
"ce3": 12.1978998184204
"cpgt1": 4.9871301651001,
"cpgt10": 0.135848000645638,
"cpgt100": 0.029602900147438,
"cpgt30": 0.070730097591877,
"cpgt5": 0.307498008012772,
"cpgt50": 0.0574011988937855,
"cpgt60": 0.053685899823904,
"e1": 917.632019042969,
"e2": 20.6098003387451,
"e3": 19.9260005950928,
"p1": 3.28379988670349,
"p10": 0.000677507021464407,
"p11": 0.00022403200273402,
"p2": 0.169376999139786,
"p3": 0.0375235006213188,
"p4": 0.0216831006109715,
"p5": 0.0173092000186443,
"p6": 0.00521680014207959,
"p7": 0.0032621999271214,
"p8": 0.0025293598882854,
"p9": 0.00158084998838603,
"time_tag": "Fri, 01 Feb 2019 04:50:00 GMT"
}
]
}
Field | Description | Unit |
---|---|---|
ce1 | Electron Flux > 0.6 MeV | e/(cm2⋅s⋅sr) |
ce2 | Electron Flux > 2 MeV | e/(cm2⋅s⋅sr) |
ce3 | Electron Flux > 4 MeV | e/(cm2⋅s⋅sr) |
cpgt1 | Corrected Protons > 1 MeV | p/(cm2⋅s⋅sr) |
ce5 | Corrected Protons > 5 MeV | p/(cm2⋅s⋅sr) |
cpgt10 | Corrected Protons > 10 MeV | p/(cm2⋅s⋅sr) |
cpgt30 | Corrected Protons > 30 MeV | p/(cm2⋅s⋅sr) |
cpgt50 | Corrected Protons > 50 MeV | p/(cm2⋅s⋅sr) |
cpgt60 | Corrected Protons > 60 MeV | p/(cm2⋅s⋅sr) |
cpgt100 | Corrected Protons > 100 MeV | p/(cm2⋅s⋅sr) |
e1 | Electrons > 0.6 MeV | #/sec |
e2 | Electrons > 2 MeV | #/sec |
e3 | Electrons > 4 MeV | #/sec |
p1 | Telescope Protons 0.7-4 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p2 | Telescope Protons 4-9 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p3 | Telescope Protons 9-15 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p4 | Dome Protons 15-40 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p5 | Dome Protons 38-82 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p6 | Dome Protons 84-200 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p7 | Dome Protons 110-900 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p8 | High Energy Proton and Alpha Detector (HEPAD) Protons 330-420 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p9 | High Energy Proton and Alpha Detector (HEPAD) Protons 420-510 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p10 | High Energy Proton and Alpha Detector (HEPAD) Protons 510-700 MeV | p/(cm2⋅s⋅sr⋅MeV) |
p11 | High Energy Proton and Alpha Detector (HEPAD) Protons > 700 MeV | p/(cm2⋅s⋅sr⋅MeV) |
time_tag | Datetime of measurement | Datetime |
The JSON encoded response for the GOES X-ray table looks like this
{
"goes_xray": [
{
"x_long": 3.91847017056079e-8,
"x_ratio": 0.29685565829277,
"x_short": 1.16322000920377e-8
}
]
}
GOES X-RAY Data Description
Field | Description | Unit |
---|---|---|
x_long | Long X-ray flux (1 - 8 angstroms) | W/m2 |
x_ratio | GOES-10,11,12 ratio of short/long X-ray flux |
|
x_short | Short X-ray flux (0.4 - 5 angstroms) | W/m2 |
Real Time Space Weather Magnetic Field Data Description
The JSON encoded response looks like this
{
"rtsw_mag": [
{
"bt": 3.91847017056079e-8,
"bx_gse": 4.98,
"bx_gsm": 4.25,
"by_gse": -2.35,
"by_gsm": -2.58,
"bz_gse": 1.08,
"bz_gsm": 0.13,
"mag_mode": 4,
"mag_range": 0,
"phi_gse": 331.08,
"phi_gsm": 328.74,
"sensitivity": 0.002,
"source": "DSCOVR",
"theta_gse": 12.51,
"theta_gsm": 1.53,
"time_tag": "Wed, 13 Feb 2019 04:13:16 GMT"
}
]
}
Field | Description | Unit |
---|---|---|
bt | ACE IMF total field from averaged components | nT |
bx_gse | Magnetic Field in X-direction GSE Cartesian coordinates | nT |
bx_gsm | Magnetic Field in X-direction GSM Cartesian coordinates | nT |
by_gse | Magnetic Field in Y-direction GSE Cartesian coordinates | nT |
by_gsm | Magnetic Field in Y-direction GSM Cartesian coordinates | nT |
bz_gse | Magnetic Field in Z-direction GSE Cartesian coordinates | nT |
bz_gsm | Magnetic Field in Z-direction GSM Cartesian coordinates | nT |
mag_mode |
|
|
mag_range |
|
|
phi_gse | GSE Longitude | The angle in degrees with 0
at Bx and + toward By
(0 to 360 degrees) |
phi_gsm | GSM Longitude | The angle in degrees with 0
at Bx and + toward By
(0 to 360 degrees) |
sensitivity |
|
|
source |
|
|
theta_gse | GSE Latitude | The angle in degrees with 0
at Bx/By plane and + toward Bz
(-90 to +90 degrees) |
theta_gsm | GSM Latitude | The angle in degrees with 0
at Bx/By plane and + toward Bz
(-90 to +90 degrees) |
time_tag | Datetime of measurement | DateTime |
Satellite Catalogue
Retrieve Single TLE
get
The <uuid> variable in the path is the norad satellite catalog number. Saber utilises the industry standard identification ID numbers for satellites.
import requests
url = "https://saberdata.space/tle/<uuid>"
headers = {
'Authorization': "Bearer <access_token>",
}
response = requests.get(url, headers=headers)
print(response.text)
endpoint: /tle/<uuid>
To refresh your access token after it has expired, send a GET request to the refresh endpoint. The refresh token is retrieved as part of the returned JSON object upon a successful login attempt.
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <access_token> |
The JSON encoded response for the a single retrieved TLE looks like this
{
"last_updated": "Mon, 01 Jul 2019 00:07:14 GMT",
"norad_cat_id": 25544,
"object_type": "PAYLOAD",
"retrieval_time": "Mon, 01 Jul 2019 01:57:03 GMT",
"tle_line_0": "0 ISS (ZARYA)",
"tle_line_1": "1 25544U 98067A 19181.85268126 -.00006926 00000-0 -10819-3 0 9995",
"tle_line_2": "2 25544 51.6486 293.4711 0008267 104.5225 41.1392 15.51249855177371"
}
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
last_updated |
timestamp Timestamp that the satellite details were last updated. | |
norad_cat_id |
int Unique NORAD catalog ID number. | |
object_type |
string Classification of object type Valid entries are: PAYLOAD, DEBRIS, ROCKET BODY, TBA. | |
retrieval_time |
int Timestamp of request to Saber API. | |
tle_line_0 |
string TLE Line Zero. Contains the name of the object requested | |
tle_line_1 |
string TLE Line One. Standard International Line One format. | |
tle_line_2 |
string TLE Line Two. Standard International Line Two format. |
Mass Retrieve TLEs
get
The <uuid> variable in the path is the norad satellite catalog number. Saber utilises the industry standard identification ID numbers for satellites.
import requests
url = "https://saberdata.space/tle"
querystring = {
"time": <last_updated_time>,
"type": <object_type>,
"page_size": <requested_page_size>,
"range": <min_sma>:<max_sma>,
}
headers = {
'Authorization': "Bearer <access_token>",
}
response = requests.get(url, headers=headers, params=querystring)
print(response.text)
endpoint: /tle
To refresh your access token after it has expired, send a GET request to the refresh endpoint. The refresh token is retrieved as part of the returned JSON object upon a successful login attempt.
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <access_token> |
Query params
Parameter | Description | Default |
---|---|---|
time |
timestamp (optional) Time of last update to be retrieved from. | UTC - 20 minutes |
type |
string (optional) Classification of object type Valid entries are: PAYLOAD, DEBRIS, ROCKET BODY, TBA. | PAYLOAD |
page_size |
int (optional) Maximum number of TLEs to be retrieved per page. Maximum 50. | 10 |
range |
int:int (optional) Filter results based on semimajor axis (SMA). In km. Minimum SMA:Maximum SMA | None |
The JSON encoded response for the a single retrieved TLE looks like this
{
"request_time": "Mon, 01 Jul 2019 01:37:03 GMT",
"page": 1,
"total_pages": 1,
"retrieval_time": "Mon, 01 Jul 2019 01:57:03 GMT",
"tle_results": [
{
"last_updated": "Mon, 01 Jul 2019 00:07:14 GMT",
"norad_cat_id": 25544,
"object_type": "PAYLOAD",
"tle_line_0": "0 ISS (ZARYA)",
"tle_line_1": "1 25544U 98067A 19181.85268126 -.00006926 00000-0 -10819-3 0 9995",
"tle_line_2": "2 25544 51.6486 293.4711 0008267 104.5225 41.1392 15.51249855177371"
}
]
}
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
request_time |
timestamp Timestamp of earliest possible last_updated time. Reflects time query parameter. | |
retrieval_time |
timestamp Timestamp of request to Saber API. | |
page |
int Page number retrieved. | |
total_pages |
int Total number of pages for the page size. i.e. 100 found TLEs with a pagesize of 10 will have 10 total pages. | |
tle_results |
list List of TLEs retrieved. Format of individual entries below. | |
last_updated |
timestamp Timestamp that the satellite details were last updated. | |
norad_cat_id |
int Unique NORAD catalog ID number. | |
object_type |
string Classification of object type Valid entries are: PAYLOAD, DEBRIS, ROCKET BODY, TBA. | |
tle_line_0 |
string TLE Line Zero. Contains the name of the object requested | |
tle_line_1 |
string TLE Line One. Standard International Line One format. | |
tle_line_2 |
string TLE Line Two. Standard International Line Two format. |
Conjunction Analysis API
Conjunction of an Asset with Object of Interest
get
endpoint: /conjunction/interest
To request an analysis of potential conjunctions between the asset and an object of interest run the following script.
The call will either return a warning (in which case the user details were incorrect) or the relevant json dict.
import requests
url = "https://saberdata.space/conjunction/interest"
querystring = {
"asset": <asset_id>,
"target": <target_id>,
"range": <range>,
"start": <start>,
}
headers = {
'Authorization': "Bearer <access_token>",
'content-type': "application/json",
}
response = requests.get(url, params=querystring, headers=headers)
print(response.text)
To request conjunction analysis, the following parameters can get sent with the GET request. If an optional parameter is not sent, a default value is selected
Headers
Parameter | Description | Format |
---|---|---|
Authorization |
string (required) Authorization header | Bearer <access_token> |
content-type |
string (required) Returned content type | application/json |
Query params
Parameter | Description | Default |
---|---|---|
asset |
int (required) Asset for all conjunctions to be calculated from. | |
target |
int (required) Orbital object of interest. | |
start |
stringStart time for analysis in UTC. Format: YYYY-MM-DDTHH:MM:SS | UTC |
duration |
int (optional) Duration of analysis in seconds. Maximum value = 604800 (7 Days) | 259200 (3 days) |
range |
float (optional) Maximum range to be considered as a conjunction in a sphere. In km. | 5.0 (5km) |
gravity |
string (optional) Earth gravitational model to use for the calculation. Options are wgs72, wgs84. | wgs72 |
first |
boolean (optional) Flag on whether to return the first conjunction detected. | false |
The JSON encoded response looks like this:
{
"analysis_start": <start_timestamp>,
"analysis_end": <end_timestamp>,
"conjunction_range": <maximum_range>,
"conjunctions": [
{
"asset_id": "40718",
"asset_name": "CARBONITE 1",
"conjunction_start": "Tue, 05 Mar 2019 00:00:00 GMT",
"conjunction_end": "Tue, 05 Mar 2019 00:00:01 GMT",
"min_range": <minimum_range>,
"relative_velocity": <relative_velocity>,
"target_id": "34898",
"target_name": "IRIDIUM 33 DEB",
"tca": "Tue, 05 Mar 2019 00:00:01 GMT",
},
{
"asset_id": "40718",
"asset_name": "CARBONITE 1",
"conjunction_start": "Tue, 05 Mar 2019 02:00:00 GMT",
"conjunction_end": "Tue, 05 Mar 2019 02:00:01 GMT",
"min_range": <minimum_range>,
"relative_velocity": <relative_velocity>,
"target_id": "34898",
"target_name": "IRIDIUM 33 DEB",
"tca": "Tue, 05 Mar 2019 02:00:01 GMT",
},
]
}
Returns
Parameter | Description | Format |
---|---|---|
Status Code |
int 200 | |
asset_id |
int Asset ID as requested for calculating conjunctions upon. | NORAD Catalogue ID |
asset_name |
string Asset Name as requested for calculating conjunctions upon. | NORAD Catalogue Name |
target_id |
int Target object ID as requested for calculating conjunctions with. | NORAD Catalogue ID |
target_name |
int Target object Name as requested for calculating conjunctions with. | NORAD Catalogue Name |
conjunction_range |
float Maximum range to be considered a conjunction | |
conjunctions |
list List of conjunction events, with values as described below | |
conjunction_start |
string (optional) Start time of the conjunction event. Format: YYYY-MM-DDTHH:MM:SS | |
tca |
string Time of Closest Approach (TCA). The point where the closest approach between target and asset for the conjunction event. | |
conjunction_end |
string End time of the conjunction event | |
min_range |
float The minimum range during the conjunction event. Measured in kilometers. | Km |
relative_velocity |
float Relative velocity at TCA between the asset and target. Measured in kilometers per second. | Km/s |
Notes:
Standard NORAD TLEs are generated with the WGS72 Earth Gravitational Model. It is recommended to use wgs72 unless supplying TLEs created with another gravitational model.