Astrospheric Data API (Beta)

Table of contents

API Key

API Documentation

GetForecastData Example

GetSky Example

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