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.