Astro::SpaceTrack - Retrieve orbital data from www.space-track.org.

NAME

Astro::SpaceTrack - Retrieve orbital data from www.space-track.org.

SYNOPSIS

 my $st = Astro::SpaceTrack->new (username => $me,
     password => $secret, with_name => 1) or die;
 my $rslt = $st->spacetrack ('special');
 print $rslt->is_success ? $rslt->content :
     $rslt->status_line;

or

 perl -MAstro::SpaceTrack=shell -e shell


 (some banner text gets printed here)

 SpaceTrack> set username me password secret
 OK
 SpaceTrack> set with_name 1
 OK
 SpaceTrack> spacetrack special >special.txt
 SpaceTrack> celestrak visual >visual.txt
 SpaceTrack> exit

LEGAL NOTICE

The following two paragraphs are quoted from the Space Track web site.

Due to existing National Security Restrictions pertaining to access of and use of U.S. Government-provided information and data, all users accessing this web site must be an approved registered user to access data on this site.

By logging in to the site, you accept and agree to the terms of the User Agreement specified in http://www.space-track.org/perl/user_agreement.pl.

You should consult the above link for the full text of the user agreement before using this software.

DESCRIPTION

This package accesses the Space-Track web site, http://www.space-track.org, and retrieves orbital data from this site. You must register and get a username and password before you can make use of this package, and you must abide by the site's restrictions, which include not making the data available to a third party.

In addition, the celestrak method queries http://celestrak.com/ for a named data set, and then queries http://www.space-track.org for the orbital elements of the objects in the data set.

There is no provision for the retrieval of historical data.

Nothing is exported by default, but the shell method/subroutine can be exported if you so desire.

Methods

The following methods should be considered public:

$st = Astro::SpaceTrack->new ( ... )
This method instantiates a new Space-Track accessor object. If any arguments are passed, the set () method is called on the new object, and passed the arguments given.

Proxies are taken from the environment if defined. See the ENVIRONMENT section of the Perl LWP documentation for more information on how to set these up.

$resp = banner ();
This method is a convenience/nuisance: it simply returns a fake HTTP::Response with standard banner text. It's really just for the benefit of the shell method.

$resp = $st->celestrak ($name);
This method takes the name of a Celestrak data set and returns an HTTP::Response object whose content is the relevant element sets. If called in list context, the first element of the list is the aforementioned HTTP::Response object, and the second element is a list reference to list references (i.e. a list of lists). Each of the list references contains the catalog ID of a satellite or other orbiting body and the common name of the body.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

$resp = $st->file ($name)
This method takes the name of an observing list file, or a handle to an open observing list file, and returns an HTTP::Response object whose content is the relevant element sets. If called in list context, the first element of the list is the aforementioned HTTP::Response object, and the second element is a list reference to list references (i.e. a list of lists). Each of the list references contains the catalog ID of a satellite or other orbiting body and the common name of the body.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

The observing list file is (how convenient!) in the Celestrak format, with the first five characters of each line containing the object ID, and the rest containing a name of the object. Lines whose first five characters do not look like a right-justified number will be ignored.

$resp = $st->get (attrib)
This method returns an HTTP::Response object whose content is the value of the given attribute. If called in list context, the second element of the list is just the value of the attribute, for those who don't want to winkle it out of the response object. We croak on a bad attribute name.

Since we currently have no read-only attributes, see the set() documentation for what you can get().

$resp = $st->help ()
This method exists for the convenience of the shell () method. It always returns success, with the content being whatever it's convenient (to the author) to include.

$resp = $st->login ( ... )
If any arguments are given, this method passes them to the set () method. Then it executes a login. The return is normally the HTTP::Response object from the login. But if no session cookie was obtained, the return is an HTTP::Response with an appropriate message and the code set to RC_UNAUTHORIZED from HTTP::Status (a.k.a. 401). If a login is attempted without the username and password being set, the return is an HTTP::Response with an appropriate message and the code set to RC_PRECONDITION_FAILED from HTTP::Status (a.k.a. 412).

$resp = $st->names (source)
This method retrieves the names of the catalogs for the given source, either 'celestrak' or 'spacetrack', in the content of the given HTTP::Response object. In list context, you also get a reference to a list of two-element lists; each inner list contains the description and the catalog name (suitable for inserting into a Tk Optionmenu).

$resp = $st->retrieve (number ...)
This method retrieves the latest element set for each of the given catalog numbers. Non-numeric catalog numbers are ignored, as are (at a later stage) numbers that don't actually represent a satellite.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

$resp = $st->search_id (id ...)
This method searches the database for objects having the given international IDs. The international ID is the last two digits of the launch year (in the range 1957 through 2056), the three-digit sequence number of the launch within the year (with leading zeroes as needed), and the piece (A through ZZ, with A typically being the payload). You can omit the piece and get all pieces of that launch, or omit both the piece and the launch number and get all launches for the year. There is no mechanism to restrict the search to a given date range, on-orbit status, or to filter out debris or rocket bodies.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

On success, this method returns an HTTP::Response object whose content is the relevant element sets. If called in list context, the first element of the list is the aforementioned HTTP::Response object, and the second element is a list reference to list references (i.e. a list of lists). The first list reference contains the header text for all columns returned, and the subsequent list references contain the data for each match.

$resp = $st->search_name (name ...)
This method searches the database for the named objects. Matches are case-insensitive and all matches are returned. There is no mechanism to restrict the search to a given date range, on-orbit status, or to filter out debris or rocket bodies.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

On success, this method returns an HTTP::Response object whose content is the relevant element sets. If called in list context, the first element of the list is the aforementioned HTTP::Response object, and the second element is a list reference to list references (i.e. a list of lists). The first list reference contains the header text for all columns returned, and the subsequent list references contain the data for each match.

$st->set ( ... )
This is the mutator method for the object. It can be called explicitly, but other methods as noted may call it implicitly also. It croaks if you give it an odd number of arguments, or if given an attribute that either does not exist or cannot be set.

For the convenience of the shell method, we return a HTTP::Response object with a success status if all goes well. But if we encounter an error we croak.

The following attributes may be set:

 addendum text
   specifies text to add to the output of the banner() method.
 banner boolean
   specifies whether or not the shell() method should emit the banner
   text on invocation. True by default.
 cookie_expires number
   specifies the expiration time of the cookie. You should only set
   with a previously-retrieved value, which matches the cookie.
 password text
   specifies the Space-Track password.
 session_cookie text
   specifies the session cookie. You should only set this with a
   previously-retrieved value.
 username text
   specifies the Space-Track username.
 verbose boolean
   specifies verbose error messages. False by default.
 with_name boolean
   specifies whether the returned element sets should include the
   common name of the body (three-line format) or not (two-line
   format). False by default.

$st->shell ()
This method implements a simple shell. Any public method name except 'new' or 'shell' is a command, and its arguments if any are parameters. We use Text::ParseWords to parse the line, and blank lines or lines beginning with a hash mark ('#') are ignored. Input is via Term::ReadLine if that's available. If not, we do the best we can.

We also recognize 'bye' and 'exit' as commands.

For commands that produce output, we allow a sort of pseudo-redirection of the output to a file, using the syntax ``>filename'' or ``>>filename''. If the ``>'' is by itself the next argument is the filename. In addition, we do pseudo-tilde expansion by replacing a leading tilde with the contents of environment variable HOME. Redirection can occur anywhere on the line. For example,

 SpaceTrack> catalog special >special.txt

sends the ``Special Interest Satellites'' to file special.txt. Line terminations in the file should be appropriate to your OS.

This method can also be called as a subroutine - i.e. as

 Astro::SpaceTrack::shell (...)

Whether called as a method or as a subroutine, each argument passed (if any) is parsed as though it were a valid command. After all such have been executed, control passes to the user. Unless, of course, one of the arguments was 'exit'.

Unlike most of the other methods, this one returns nothing.

$st->source ($filename);
This convenience method reads the given file, and passes the individual lines to the shell method. It croaks if the file is not provided or cannot be read.

$resp = $st->spacetrack ($name_or_number);
This method downloads the given bulk catalog of orbital elements. If the argument is an integer, it represents the number of the catalog to download. Otherwise, it is expected to be the name of the catalog, and whether you get a two-line or three-line dataset is specified by the setting of the with_name attribute. The return is the HTTP::Response object fetched. If an invalid catalog name is requested, an HTTP::Response object is returned, with an appropriate message and the error code set to RC_NOTFOUND from HTTP::Status (a.k.a. 404).

Assuming success, the content of the response is the literal element set requested. Yes, it comes down gzipped, but we unzip it for you. See the synopsis for sample code to retrieve and print the 'special' catalog in three-line format.

This method implicitly calls the login () method if the session cookie is missing or expired. If login () fails, you will get the HTTP::Response from login ().

ENVIRONMENT

The following environment variables are recognized by Astro::SpaceTrack.

SPACETRACK_OPT

If environment variable SPACETRACK_OPT is defined at the time an Astro::SpaceTrack object is instantiated, it is broken on spaces, and the result passed to the set command.

If you specify username or password in SPACETRACK_OPT and you also specify SPACETRACK_USER, the latter takes precedence, and arguments passed explicitly to the new () method take precedence over both.

SPACETRACK_USER

If environment variable SPACETRACK_USER is defined at the time an Astro::SpaceTrack object is instantiated, the username and password will be initialized from it. The value of the environment variable should be the username followed by a slash (``/'') and the password.

An explicit username and/or password passed to the new () method overrides the environment variable, as does any subsequently-set username or password.

EXECUTABLES

A couple specimen executables are included in this distribution:

SpaceTrack

This is just a wrapper for the shell () method.

SpaceTrackTk

This provides a Perl/Tk interface to Astro::SpaceTrack.

BUGS

This software is essentially a web page scraper, and relies on the stability of the user interface to Space Track. The Celestrak portion of the functionality relies on the presence of .txt files named after the desired data set residing in the expected location.

This software has not been tested under a HUGE number of operating systems, Perl versions, and Perl module versions. It is rather likely, for example, that the module will die horribly if run with an insufficiently-up-to-date version of LWP or HTML::Parser.

MODIFICATIONS

 0.003 26-Mar-2005 T. R. Wyant
   Initial release to CPAN.
 0.004 30-Mar-2005 T. R. Wyant
   Added file method, for local observing lists.
   Changed Content-Type header of spacetrack () response
     to text/plain. Used to be text/text.
   Manufactured pristine HTTP::Response for successsful
     login call.
   Added source method, for passing the contents of a file
     to the shell method
   Skip username and password prompts, and login and
     retrieval tests if environment variable
     AUTOMATED_TESTING is true and environment variable
     SPACETRACK_USER is undefined.
 0.005 02-Apr-2005 T. R. Wyant
   Proofread and correct POD.
 0.006 08-Apr-2005 T. R. Wyant
   Added search_id method.
   Made specimen scripts into installable executables.
   Add pseudo-tilde expansion to shell method.
 0.007 15-Apr-2005 T. R. Wyant
   Document attributes (under set() method)
   Have login return actual failure on HTTP error. Used
     to return 401 any time we didn't get the cookie.
 0.008 19-Jul-2005 T. R. Wyant
   Consolidate dump code.
   Have file() method take open handle as arg.
   Modify cookie check.
   Add mutator, accessor for cookie_expires,
     session_cookie.
 0.009 17-Sep-2005 T. R. Wyant
   Only require Term::ReadLine and create interface if
   the shell() method actually called.

ACKNOWLEDGMENTS

The author wishes to thank Dr. T. S. Kelso of http://celestrak.com/ and the staff of http://www.space-track.org/ (whose names are unfortunately unknown to me) for their co-operation, assistance and encouragement.

AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)

COPYRIGHT

Copyright 2005 by Thomas R. Wyant, III (wyant at cpan dot org)

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself.

The data obtained by this module is provided subject to the Space Track user agreement (http://www.space-track.org/perl/user_agreement.pl).

This software is provided without any warranty of any kind, express or implied. The author will not be liable for any damages of any sort relating in any way to this software.

 Astro::SpaceTrack - Retrieve orbital data from www.space-track.org.