The Satellite Services REST Interface

Command-Line Interface for the Coincidence Search Engine

This service provides two functions: Two-line elements (TLE) server and satellites server.

The caller can use a REST interface to retrieve the latest TLE using the "elements" interface by providing a satellite id (number) or a satellite name (string), a from date, and a thru date. The interface will return the latest TLE that is on or before the start date. Note that this information is gathered from our local copy of the TLEs which we download regularly from Space-Track for a select list of satellites. It will not provide TLEs for satellites we do not "track".

The caller can use a REST interface to retrieve the satellite information using the "satellites" interface by providing a satellite id (number) or a satellite name (string). This service returns information about the satellite that we store locally, including the satellite's orbital period and the satellite's nominal altitude. It will also translate the name to the satellite id and vice-versa.

The "elements" interface

The syntax of the command is the following:

    https://ghrc.nsstc.nasa.gov/services/satellites/elements.pl?{options}...

The service expects the following GET data:

[satid=integer]: The satellite-id, if known. This is a five-digit number. This parameter is optional.
[satname=string]: The satellite's common name, if known. This is a string. This parameter is optional.
[fromdate=datetime]: The "from" date in the form "yyyy-mm-ddThh:mm:ssZ". This parameter is optional.
[thrudate=datetime]: The "thru" date in the form "yyyy-mm-ddThh:mm:ssZ". This parameter is optional.

Either the "satid" or "satname" must be specified. If both are specified, "satname" takes precedence. If no "fromdate" is specified, all TLEs prior to "thrudate" are returned. If no "thrudate" is specified, all TLEs from just before "fromdate" to the end of our holdings are returned. If neither is specified, all TLEs for the satellite are returned.

The TLEs returned will include the TLE on or just before the "fromdate" and the last TLE will be on or just before the "thrudate".

The following XML message is returned:

<Elements>
  {<error msg="text"/> |
   <element date="datetime" one="text" two="text"/>...}
<Elements>

A terminal error will result in a response containing a single <error> tag with an explanatory message. Otherwise, one or more <element> tags will be returned. The "date" attribute indicates the date/time of the element, and "one" and "two" are the two lines of the TLE.

Terminal errors include the following:

Missing or invalid satid or satname. One or the other must be present and it must identify a satellite for which we have TLEs.
No TLE data before "date". The "fromdate is less than the first TLE for the satellite that we have stored.

Examples:

Retrieve all of the TLEs for TRMM:

    https://ghrc.nsstc.nasa.gov/services/satellites/elements.pl?satid=25063
    https://ghrc.nsstc.nasa.gov/services/satellites/elements.pl?satname=TRMM

Either form will produce the same results. Since no bounding dates were specified, all of the TRMM TLEs will be returned.

Retrieve the AQUA TLEs from 2015-07-10 and onward:

    https://ghrc.nsstc.nasa.gov/services/satellites/elements.pl?satname=AQUA&fromdate=2015-07-10T00:00:00Z

which returns

<?xml version="1.0" encoding="UTF-8"?>
<Elements
  xsi:noNamespaceSchemaLocation="http://ghrc.nsstc.nasa.gov/satellites/Elements.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <element date="2015-07-09T03:42:42Z" one="1 27424U 02022A   15190.15465579  .00000642  00000-0  15255-3 0  9996" two="2 27424 098.1961 130.7444 0002026 108.3456 312.4721 14.57122118701027"/>
    <element date="2015-07-10T11:25:36Z" one="1 27424U 02022A   15191.47611650  .00000375  00000-0  93329-4 0  9997" two="2 27424 098.1962 132.0448 0002080 107.0119 041.6108 14.57122226701210"/>
</Elements>

The "satellites" interface

The syntax of the command is the following:

    https://ghrc.nsstc.nasa.gov/services/satellites/satellites.pl?{options}...

The service expects the following GET data:

[satid=integer]: The numeric satellite-id, if known. This argument is optional.
[satname=string]: The common satellite name, if known. This argument is optional.

If both "satid" and "satname" are specified, the results may be unpredictable (or empty). If neither is specified, information is returned for all of the satellites in our local database.

If "satname" (but not "satid") is specified, it is used as a beginning-of-name wildcard, and the data for all satellites that match that name will be returned. For example, specifying "satname=NOAA" will return all information for all of the NOAA satellites in our database.

The following XML response is returned:

<Satellites>
 {<error msg="test"/> |
 [<satellite 
    id="integer" 
    name="string" 
    from="datetime" 
   [thru="datetime"]
   [period="float"]
   [altitude="float"]
   [information="string"]
  />...]}
<Satellites>

A terminal error will result in a response containing a single <error> tag with an explanatory message. Otherwise, zero or more <satellite> tags will be returned.

The "from" and "thru" strings will be in the format yyyy-mm-ddThh:mm:ssZ. If the satellite is still orbiting, no "thru" date will be returned.

If the satellite's nominal orbital period is known, it will be returned in the "period" tag in minutes. Similarly, if its nominal altitude is known, it will be returned in the "altitude" tag in kilometers.

If the satellite has a home page URL, it will be returned in the "information" string.

Example:

The following command returns all known information about the TRMM satellite (25063):

https://ghrc.nsstc.nasa.gov/services/satellites/satellites.pl?satid=25063