Satellite Prediction Listing

SPL Documentation | KML Examples | Screenshots

The Satellite Prediction Listing (SPL) provides web based orbital propagation based on a REST based interface for requesting orbital position. SPL is based on KepCalc an open source orbital propagation library available in several languages on SourceForge. SPL currently uses the SGP orbital model as described in Space-Track Report Number 3.

Several output formats are supported including readable HTML, XML, and KML (Keyhole Markup Language) for plotting using Google Earth or Google Maps. Support for KML allows for interesting combinations of requests as shown with KML Examples.

The spacecraft catalog is maintained using an autoupdate engine operating on a cached version of the celestrak.com spacecraft catalog of active objects. The autoupdate engine will attempt to synchronize a segment of the library with celestrak if a requested satellite has not been updated in 6 hours. Every 24 hours the entire library is flushed resulting in new objects added to celestrak to be included in the SPL library.

Entries from several unlisted US Government classified spacecraft distributed by Mike McCants are additionally part of the SPL library. UNKNOWN is listed as the name of these sats. Many of these TLEs are sourced from the Seesat-L mailing list.

Howto Use

Requests are made via a standard REST based interface using the http GET to specify the conditions of propagation. Malformed parameters are reported in the response format protecting SPL from out of range requests.

Parameters

The following table describes the request parameters for SPL. Parameter names are case sensitive.

ParameterDefinitionRequired
Satellite

This field allows for selection of the Spacecraft of interest

Type: NORAD catalog ID of spacecraft of interest. Zarya (ISS) is 25544 for example. The active list of spacecraft currently loaded into the system is available here. The list of spacecraft is automatically maintained from celestrak.com which is the only public distributor of NORAD published orbital elements through space-track.org. Celestrak filters the NORAD published list from a catalog of over 32000 entries down to one of about 1200 active spacecraft.

Default: 29655 (Genesat-1)

Valid Values: Positive Integers - Catalog ID 1 was Sputnik which, due to rentry, is no longer an active sat. The catalog ids currently are in the 32000 range though this increases on a nearly daily basis.

No
TimeStart

Propagation start time.

Type: Date specified in UTC in the following format YYYY-MM-DD-hh-mm-ss

Default: The current time

Valid Values: 01 Jan 1970 00:00:00 +0000 to 19 Jan 2038 03:14:07 +0000

No
TimeEnd

Propagation end time. Mutually exclusive with TimeSpan.

Type: Date specified in UTC in the following format YYYY-MM-DD-hh-mm-ss. It is possible for this value to be less than TimeStart resulting in backwards propagation.

Default: The current time + 1 day (86400 seconds)

Valid Values: 01 Jan 1970 00:00:00 +0000 to 19 Jan 2038 03:14:07 +0000

No
TimeSpan

Time period of propagation relative to TimeStart. Mutually exclusive with TimeEnd, TimeSpan takes precedent when both are present.

Type: Signed integer – Allows for forward or backwards propagation periods.

Default: 86400 seconds (1 day)

Valid Values: Any 32bit integer

No
SamplePeriod

Time period between samples.

Type: Positive Integer

Default: 86400 seconds (1 day)

Valid Values: Any positive integer

No
SampleCount

Total number of samples.

Type: Positive Integer

Default: 86400 seconds (1 day)

Valid Values: Any positive integer

No
ObserverLatitude

Latitude of the observer.

Type: Degrees

Default: No default value

Valid Values: -90.0 to 90.0 degrees North Latitude

No
ObserverLongitude

Longitude of the observer.

Type: Degrees

Default: No default value

Valid Values: -180.0 to 180.0 degrees East Longitude

No
ObserverAltitude

Altitude of the observer.

Type: Meters

Default: No default value

Valid Values: Must be on surface of earth between -2540m and 9000m

No
Output

Format of the response data.

Type: Enumeration

Default: html

Valid Values: html, xml, kml

No

  • ObserverLatitude, ObserverLongitude, and ObserverAltitude must all be specified for observer data to be included in the response set. If there is an error in the value of any of these components observer data in the response is not included.

  • SamplePeriod and SampleCount are coupled parameters. If neither are specified a single sample is used. If SamplePeriod is specified and SampleCount is not, SampleCount is calculated as a function of SamplePeriod and TimeSpan:

    SampleCount = TimeSpan / SamplePeriod

    If SamplePeriod is not specified and SampleCount is, SamplePeriod is calculated as a function of SampleCount and TimeSpan:

    SamplePeriod = TimeSpan / SampleCount

    If both are specified, SamplePeriod is limited to be no larger than (TimeSpan / SampleCount). Then SampleCount samples are taken at SamplePeriod regardless of whether the entire TimeSpan is covered.

Use SPL in the following ways:

  • This performs a search using all default parameters. The result is a single sample of the current position of Genesat-1 (29655).

    http://www.williamslabs.com/sat/spl.py

    The response to this request is shown in, Response to Sample Request.

  • This performs a search using all default parameters except for the selected Satellite. In this case satellite 27845 is selected, a query for a single sample of the current position of 27845 is performed.

    http://www.williamslabs.com/sat/spl.py?
Satellite=27845

  • Zarya ISS is selected (25544) and the position on May 1st 2008 at 00:00:00 UTC is selected.

    http://www.williamslabs.com/sat/spl.py?
Satellite=25544&
TimeStart=2008-05-01-00-00-00

  • The position of Libertad-1 is displayed between May 1st 2008 00:00:00 and 00:12:00 with 100 samples. The SamplePeriod of 432 seconds is autocalculated.

    http://www.williamslabs.com/sat/spl.py?
Satellite=31128&
TimeStart=2008-05-01-00-00-00&
TimeEnd=2008-05-01-12-00-00&
SampleCount=100

  • The position of default selected Genesat-1 29655 is shown over the 24hour period of June 12th 2008. A sample period of 600 seconds (10 minutes) is specified resulting in 144 samples over the 24 hour period. 

    http://www.williamslabs.com/sat/spl.py?
TimeStart=2008-06-12-00-00-00&
SamplePeriod=600

  • An observer in southern california is specified observing the default satellite position of Genesat-1 (29655) over the default 1 day period. 400 samples are specified during this period.

    http://www.williamslabs.com/sat/spl.py?
ObserverAltitude=700.0&
ObserverLatitude=32&
ObserverLongitude=-118&
SampleCount=400

  • A single pass of the default satellite Genesat-1 is shown with an observer in upstate New York specified. A position is specified every 30 seconds.

    http://www.williamslabs.com/sat/spl.py?
ObserverAltitude=300.0&
ObserverLatitude=42.4402&
ObserverLongitude=-76.4922&
SamplePeriod=30&
TimeStart=2008-05-14-05-13-00&
TimeEnd=2008-05-14-05-24-00

For XML and HTML formatted responses the data is presented very similarly. For HTML formatted data a browser side xsl transform is used to format the XML document in the browser. Though the source of the response is identical to the XML format otherwise. The response format is maintained in the XML Schema Document (xsd) here. This response document is broken into 3 key components.

Query Details – Details of the query, necessary for validating input.

Satellite – Details of current orbital elements of selected spacecraft.

Positions – Listing of positions based on the query details

KML response format details are still being explored.

Response to Sample Request

The following XML is a snippet of the full response to the first sample request.

<SatellitePositionListing xmlns="http://www.williamslabs.com/sat/spl#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.williamslabs.com/sat/spl# http://www.williamslabs.com/sat/spl.xsd">
	<QueryDetails>
		<<SatelliteNumber>
			29655
		</SatelliteNumber>
		<TimeStart>
			Thu, 29 May 2008 22:36:55 +0000
		</TimeStart>
		<TimeEnd>
			Fri, 30 May 2008 22:36:55 +0000
		</TimeEnd>
		<TimeSpan>
			86400.0
		</TimeSpan>
		<SamplePeriod>
			86400
		</SamplePeriod>
		<SampleCount>
			1
		</SampleCount>
		<ObserverSpecified>
			False
		</ObserverSpecified>
		<ObserverLatitude>
			0.0
		</ObserverLatitude>
		<ObserverLongitude>
			0.0
		</ObserverLongitude>
		<ObserverAltitude>
			0.0
		</ObserverAltitude>
		<OutputFormat>
			html
		</OutputFormat>
		<ValidOutput>
			True
		</ValidOutput>
		<ParseError>
			No Error
		</ParseError>
	</QueryDetails>
	<Satellite>
		<SatelliteName>
			GENESAT-1               
		</SatelliteName>
		<SatelliteNumber>
			29655
		</SatelliteNumber>
		<IntlDesignator>
			06058C
		</IntlDesignator>
		<Epoch>
			8144.17711416
		</Epoch>
		<ndot_0div2>
			2.75768081986e-10
		</ndot_0div2>
		<ndotdot_0div6>
			0.0
		</ndotdot_0div6>
		<Bstar>
			0.00011924
		</Bstar>
		<ElementNumber>
			421
		</ElementNumber>
		<Inclination>
			0.698531381196
		</Inclination>
		<RightAscension>
			1.61607540358
		</RightAscension>
		<Eccentricity>
			0.000493
		</Eccentricity>
		<ArguementOfPerigee>
			4.72020281945
		</ArguementOfPerigee>
		<MeanAnomaly>
			1.56342754669
		</MeanAnomaly>
		<MeanMotion>
			0.0680008621597
		</MeanMotion>
		<EpochRev>
			8148
		</EpochRev>
		<tle1>
			1 29655U 06058C   08144.17711416  .00009101  00000-0  11924-3 0  4212
		</tle1>
		<tle2>
			2 29655  40.0229  92.5943 0004930 270.4477  89.5778 15.58464962 81480
		</tle2>
		<SourceURI>
			http://www.celestrak.com/NORAD/elements/cubesat.txt
		</SourceURI>
		<LastUpdate>
			2008-05-23 15:17:44.036123
		</LastUpdate>
	</Satellite>
	<Positions>
		<Position>
			<Time>
				Thu, 29 May 2008 22:36:55 +0000
			</Time>
			<Latitude>
				-19.0885978796
			</Latitude>
			<Longitude>
				-332.173673377
			</Longitude>
			<Altitude>
				396.700737788
			</Altitude>
		</Position>
	</Positions>
</SatellitePositionListing>

SPL was developed during some free time in April and May 2008 by Phelps Williams