Astrospheric logo
Astrospheric Data API (Beta)

Table of contents

API Key
API Documentation
API Endpoint
API Details
API Examples

Astrospheric processes gigabytes of data every day from government and public institutions. The Astrospheric Data API allows pro members to access the data produces in a programmatic way which can be used in automation, heads up displays, or other places where astronomy data may be useful!

Astrospheric's Data API is available to Astrospheric Professional members for use in personal projects.  For public or commercial projects, or access to map data, please email developer@astrospheric.com.  You may also consider using the Astrospheric Embed Control.

Note: Any API requests to endpoints not specified below is against Astrospheric's terms of use and will lead to IP blocks and/or charges.

The Astrospheric Data API is in beta and will continue to see more content and data added over time.  If you have feedback please contact us at developer@astrospheric.com.  Using the API will automatically register your account for API update emails.

All Pro users will be given 100 credits per day to use against these APIs.  API call cost has been calculated based on server resources required to complete the task.  We'll likely raise the per day credit as the API becomes more mature.  Credits refresh at midnight UTC.

API Key

A Private API key is required in order to pull content from the Data API.  To get your private key, visit the "My Profile" tab in Astrospheric and copy your key.

Pro users have 100 API credits per day.  Credits refresh at midnight UTC.

API Documentation

API Endpoint

All APIs are hosted under the following endpoint. 

https://astrosphericpublicaccess.azurewebsites.net/api/

Data is sent to the APIs as a HTTP Post request.  Post data must be encoded as a JSON string with the necessary variables.  The API will return data in an HTTP response encoded in JSON.  The APIs are versioned and unique, this means that if a new version of an API is introduced, the old version will remain as well. This allows apps to be built upon the API without having to worry about future breaking changes.  If an old version of an API must be retired, we'll provide time and notification to migrate to the next version.

API Details

GetForecastData_V1

Provided a Latitude and Longitude, this function will return an 81 hour long forecast.  Time zone and offsets from UTC will also be calculated for the given Latitude and Longitude.  Forecast data is updated every 6 hours.  The provided location must be within the bounds of the RDPS forecast model represented on Astrospheric.  Domain details can be found here.  The API will return an error if a location outside of the forecast domain is requested.

API Cost 5 Credits/Call
HTTP Method Post
Input
  • Latitude (float)
  • Longitude (float)
  • APIKey (string)
Output
  • HTTP 400 Bad Request
    • JSON ErrorInfo
  • HTTP 403 Unathorized
    • JSON ErrorInfo
  • HTTP 500 Server Error
  • HTTP 200 Good Request
    • JSON Full Response Object

Full Response Object A successful request to GetForecastData_V1 will return the following object encoded in JSON format

ReturnObject
{
string TimeZone; // The name of the time zone eg: "America/Los_Angeles"
int UTCMinuteOffset; // Minute offset between the local time and UTC time
string ModelTime; // The Model identity depicting the "Model Run". YYYYMMDDHH
double Latitude;
double Longitude;
DateTime LocalStartTime; // The start time of the forecast in local time
DateTime UTCStartTime; // The start time of the forecast in UTC
int APICreditUsedToday; // How many API Credits used during a 24 hour window
Array<HourValue> Astrospheric_Seeing;
Array<HourValue> RDPS_DewPoint;
Array<HourValue> RDPS_CloudCover;
Array<HourValue> RDPS_WindVelocity;
Array<HourValue> RDPS_WindDirection;
Array<HourValue> Astrospheric_Transparency;
Array<HourValue> RDPS_Temperature;
}

The weather variables encoded in this object are described below.  Each variable is an array of values, one for each hour of the forecast.  Each hour contains the raw value as well as the color Astrospheric would use on its map to represent the value.

Variable Description Value
RDPS_CloudCover A % value representing the amount of cloud cover. 0% would represent clear skies, 100% would be complete cloud cover.  Value direct from RDPS model, augmented by Astrospheric's Cloud Sense system. 0-100
Astrospheric_Transparency A unit-less value representing the transparency of the column of atmosphere above a given location.  Transparency takes into account water vapor, aerosols (smoke), surface pressure, and elevation. Value computed from RDPS and RAP models
  • 0-5: Excellent
  • 6-9: Above Average
  • 10-13: Average
  • 14-23: Below Average
  • 24-27: Poor
  • >27: Cloudy
Astrospheric_Seeing A unit-less value representing the stability and turbulence in the column of atmosphere above a given location.  Seeing takes into account elevation, pressure, temperature gradients, wind and wind sheer, temporal temperature gradients. Value computed from RDPS model
  • 0: Cloudy
  • 1: Poor
  • 2: Below Average
  • 3: Average
  • 4: Above Average
  • 5: Excellent
RDPS_Temperature Temperature in Kelvin. Value direct from RDPS model 200-350
RDPS_DewPoint Dew Point in Kelvin. Value directly from RDPS model 200-350
RDPS_WindVelocity Wind Velocity in meters per second. Value directly from RDPS model 0-55
RDPS_WindDirection Wind direction in degrees (0 is North). Value directly from RDPS model. 0-365

 

GetSky_V1

Provided a Latitude, Longitude, and time (in UTC), this function will return the current locations of the planets and stars currently above the horizon.  Our star database includes stars under a brightness magnitude 5 (the lower the number the brighter the object).  The time provided to the API is milliseconds since epoch (Unix time) in UTC.  Sun and Moon information will always be included, even if their position is below the horizon.

API Cost 1 Credits/Call
HTTP Method Post
Input
  • Latitude (float)
  • Longitude (float)
  • MSSinceEpoch (int)
  • APIKey (string)
Output
  • HTTP 400 Bad Request
    • JSON ErrorInfo
  • HTTP 403 Unathorized
    • JSON ErrorInfo
  • HTTP 500 Server Error
  • HTTP 200 Good Request
    • JSON Full Response Object

Full Response Object A successful request to GetSky_V1 will return the following object encoded in JSON format

ReturnObject
{
DateTime Time; // The time the sky was calculated for in UTC ("2022-05-13T15:54:17.299Z")
int APICreditUsedToday; // How many API Credits used during a 24 hour window
Array<SkyObjectLocation> Planet_Star;
MoonLocation Moon;
SunLocation Sun;
}

SkyObjectLocation object contains the following information.  The API will return an Array of SkyObjectLocation objects as long as it is above the horizon (>0 Altitude)

Variable Description Value
RA Right ascension. Degrees.  This value will be 0 for planets (Type 1 objects) 0-359
Dec Declination. Degrees.  This value will be 0 for planets (Type 1 objects)

-90 to 90

Altitude Angle between the horizon and the sky object.  More Info 0-90
Azimuth Angle between true North and the sky object around the horizon. More Info 0-359
Mag The brightness magnitude of the sky object.  Our Sun is -27 (the brightest object in the database) -27 to 5
Name Planets and bright stars will have names.  This field may be empty. string
Type Is the object a Planet (1) or Star (0) 0 or 1

MoonLocation object contains the following information.  This object will always be included, even if the Moon is below the horizon.

Variable Description Value
Altitude Angle between the horizon and the sky object.  More Info 0-90
Azimuth Angle between true North and the sky object around the horizon. More Info

0-359

Illumination Percentage of the moon currently illuminated.  Full Moon = 100%, New Moon = 0% 0-100
Phase  0=New Moon, 0.25=First Quarter, 0.5=Full Moon, 0.75=Last Quarter.  Values in between the quarters indicate Waxing Crescent, Waxing Gibbous, Waning Gibbous, Waning Crescent. 0-1

SunLocation object contains the following information.  This object will always be included, even if the Sun is below the horizon

Variable Description Value
Altitude Angle between the horizon and the sky object.  More Info 0-90
Azimuth Angle between true North and the sky object around the horizon. More Info

0-359

API Examples

Code Examples

The following JavaScript code snippets can get you up and running.  Technically the APIs can be called from any programming language that can generate a HTTP POST request against the endpoint. 

GetForecastData_V1 Example

// A function to fetch the forecast at a specific location
function FetchTheForecast()
{
   
    const Astrospheric_GetForecastData='https://astrosphericpublicaccess.azurewebsites.net/api/GetForecastData_V1';

    // Create the object to hold the data we need to send to the server
    var APIData = {};
    APIData["Latitude"] = 39.03;
    APIData["Longitude"] = -110.32;
    APIData["APIKey"] =  "YOUR_API_KEY_HERE";

    // Convert the object to JSON
    var jsonDataString = JSON.stringify(APIData);

    // Create a request and send the data to the API
    const Http = new XMLHttpRequest();
    Http.open("POST", Astrospheric_GetForecastData);
    Http.setRequestHeader("Content-type", "application/json");
    Http.send(jsonDataString);

    // Handle the response from the API.  
    // It's a good idea to handle the various errors the server can return
    Http.onload = function()
    {
        if (Http.readyState == 4)
        {
            console.log(Http.responseText);
        }
    }
}

Run this GetForecastData code

Run
API Output

GetSky_V1 Example

function FetchSky()
{
    const Astrospheric_GetSkyData='https://astrosphericpublicaccess.azurewebsites.net/api/GetSky_V1';

    // Create the object to hold the data we need to send to the server
    var APIData = {};
    APIData["Latitude"] = 39.03;
    APIData["Longitude"] = -110.32;
    APIData["MSSinceEpoch"] = Date.now(); // Get the sky right now
    APIData["APIKey"] =  "YOUR_API_KEY_HERE";

    // Convert the object to JSON
    var jsonDataString = JSON.stringify(APIData);

    // Create a request and send the data to the API
    const Http = new XMLHttpRequest();
    Http.open("POST", Astrospheric_GetSkyData);
    Http.setRequestHeader("Content-type","application/json");
    Http.send(jsonDataString);

    // Handle the response from the API.  
    // It's a good idea to handle the various errors the server can return
    Http.onload = function()
    {
        if (Http.readyState == 4)
        {
            console.log(Http.responseText);
        }
    }
}

Run this GetSky code

Run
API Output