/ 
Astro-SpaceTrack-0.033
River stage one • 1 direct dependent • 2 total dependents
/ Astro::SpaceTrack

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.

Beginning with version 0.017, there is provision for retrieval of historical data.

Nothing is exported by default, but the shell method/subroutine and the BODY_STATUS constants (see "iridium_status") can be exported if you so desire.

Most methods return an HTTP::Response object. See the individual method document for details. Methods which return orbital data on success add a 'Pragma: spacetrack-type = orbit' header to the HTTP::Response object if the request succeeds.

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 = $st->amsat ()

This method downloads current orbital elements from the Radio Amateur Satellite Corporation's web page, http://www.amsat.org/. This lists satellites of interest to radio amateurs, and appears to be updated weekly.

No Space Track account is needed to access this data, even if the 'direct' attribute is false. But if the 'direct' attribute is true, the setting of the 'with_name' attribute is ignored.

This method is a web page scraper. any change in the location of the web page will break this method.

@names = $st->attribute_names

This method returns a list of legal attribute names.

$resp = $st->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.

A list of valid names and brief descriptions can be obtained by calling $st->names ('celestrak'). If you have set the 'verbose' attribute true (e.g. $st->set (verbose => 1)), the content of the error response will include this list. Note, however, that this list does not determine what can be retrieved; if Dr. Kelso adds a data set, it can be retrieved even if it is not on the list, and if he removes one, being on the list won't help.

In general, the data set names are the same as the file names given at http://celestrak.com/NORAD/elements/, but without the '.txt' on the end; for example, the name of the 'International Space Station' data set is 'stations', since the URL for this is http://celestrak.com/NORAD/elements/stations.txt.

As of October 11 2007, the data set for the debris from the People's Republic of China's anti-satellite test against their Fengyun 1C satellite is available from Celestrak only by direct-fetching ($st->set (direct => 1), see below), as data set '1999-025'. I have not corresponded with Dr. Kelso on this, but I think it reasonable to believe that the effect of asking Space Track for all 2126 pieces of debris at once would not be good.

The data set for the current US Space Shuttle Mission (if any) will be available as data set 'sts'. If there is no current mission, you will get a 404 error with text "Missing Celestrak catalog 'sts'." Since the data ultimately come from NORAD, the shuttle will have to be up and actually tracked by NORAD before this is available.

If the 'direct' attribute is true, or if the 'fallback' attribute is true and the data are not available from Space Track, the elements will be fetched directly from Celestrak, and no login is needed. Otherwise, this method implicitly calls the login () method if the session cookie is missing or expired, and returns the SpaceTrack data for the OIDs fetched from Celestrak. If login () fails, you will get the HTTP::Response from login ().

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

You can specify the "retrieve" options on this method as well, but they will have no effect if the 'direct' attribute is true.

$type = $st->content_type ($resp);

This method takes the given HTTP::Response object and returns the data type specified by the 'Pragma: spacetrack-type =' header. The following values are supported:

'get': The content is a parameter value.
'help': The content is help text.
'orbit': The content is NORAD data sets.
undef: No spacetrack-type pragma was specified. The
       content is something else (typically 'OK').

If the response object is not provided, it returns the data type from the last method call that returned an HTTP::Response object.

$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.

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

You can specify the "retrieve" options on this method as well.

$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.

See "Attributes" for the names and functions of the attributes.

$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.

If the webcmd attribute is set, the http://search.cpan.org/ web page for this version of Astro::Satpass is launched.

$resp = $st->iridium_status ($format);

This method queries its sources of Iridium status, returning an HTTP::Response object containing the relevant data (if all queries succeeded) or the status of the first failure. If the queries succeed, the content is a series of lines formatted by "%6d %-15s%-8s %s\n", with NORAD ID, name, status, and comment substituted in.

The source of the data and, to a certain extent, the format of the results is determined by the optional $format argument, which defaults to the value of the "iridium_status_format" attribute.

If the format is 'kelso', only Dr. Kelso's Celestrak web site (http://celestrak.com/SpaceTrack/query/iridium.txt) is queried for the data. The possible status values are:

'[S]' - Spare;
'[-]' - Tumbling (or otherwise unservicable);
'[+]' - In service and able to produce predictable flares.

The comment will be 'Spare', 'Tumbling', or '' depending on the status.

If the format is 'mccants', the primary source of information will be Mike McCants' "Status of Iridium Payloads" web page, http://www.io.com/~mmccants/tles/iridium.html (which gives status on non-functional Iridium satellites). The Celestrak list will be used to fill in the functioning satellites so that a complete list is generated. The comment will be whatever text is provided by Mike McCants' web page, or 'Celestrak' if the satellite data came from that source.

As of 20-Feb-2006 Mike's web page documented the possible statuses as follows:

blank - object is operational
'tum' - tumbling
'?' - not at operational altitude
'man' - maneuvering, at least slightly.

In addition, the data from Celestrak may contain the following status:

'dum' - Dummy mass

A blank status indicates that the satellite is in service and therefore capable of producing flares.

If the format is 'sladen', the primary source of information will be Rod Sladen's "Iridium Constellation Status" web page, http://www.rod.sladen.org.uk/iridium.htm, which gives status on all Iridium satellites, but no OID. The Celestrak list will be used to provide OIDs for Iridium satellite numbers, so that a complete list is generated. Mr. Sladen's page simply lists operational and failed satellites in each plane, so this software imposes Kelso-style statuses on the data. That is to say, operational satellites will be marked '[+]', spares will be marked '[S]', and tumbling satellites will be marked '[-]', with the corresponding portable statuses. The one twist is that failed satellites not marked as tumbling will be considered spares.

The comment field in 'sladen' format data will contain the orbital plane designation for the satellite, 'Plane n' with 'n' being a number from 1 to 6. If the satellite is failed but not tumbling, the text ' - Failed on station?' will be appended to the comment. The dummy masses will be included from the Kelso data, with status '[-]' but comment 'Dummy'.

If the method is called in list context, the first element of the returned list will be the HTTP::Response object, and the second element will be a reference to a list of anonymous lists, each containing [$id, $name, $status, $comment, $portable_status] for an Iridium satellite. The portable statuses are:

0 = BODY_STATUS_IS_OPERATIONAL means object is operational
1 = BODY_STATUS_IS_SPARE means object is a spare
2 = BODY_STATUS_IS_TUMBLING means object is tumbling
    or otherwise unservicable.

The correspondence between the Kelso statuses and the portable statuses is pretty much one-to-one. In the McCants statuses, '?' identifies a spare, '+' identifies an in-service satellite, and anything else is considered to be tumbling.

The BODY_STATUS constants are exportable using the :status tag.

$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', 'spacetrack', or 'iridium_status', 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, in that order (suitable for inserting into a Tk Optionmenu).

$resp = $st->retrieve (number_or_range ...)

This method retrieves the latest element set for each of the given satellite ID numbers (also known as SATCAT IDs, NORAD IDs, or OIDs). Non-numeric catalog numbers are ignored, as are (at a later stage) numbers that do not actually represent a satellite.

Number ranges are represented as 'start-end', where both 'start' and 'end' are catalog numbers. If 'start' > 'end', the numbers will be taken in the reverse order. Non-numeric ranges are ignored.

You can specify options for the retrieval as either command-type options (e.g. retrieve ('-last5', ...)) or as a leading hash reference (e.g. retrieve ({last5 => 1}, ...)). If you specify the hash reference, option names must be specified in full, without the leading '-', and the argument list will not be parsed for command-type options. If you specify command-type options, they may be abbreviated, as long as the abbreviation is unique. Errors in either sort result in an exception being thrown.

The legal options are:

descending
  specifies the data be returned in descending order.
end_epoch date
  specifies the end epoch for the desired data.
last5
  specifies the last 5 element sets be retrieved.
  Ignored if start_epoch or end_epoch specified.
start_epoch date
  specifies the start epoch for the desired data.
sort type
  specifies how to sort the data. Legal types are
  'catnum' and 'epoch', with 'catnum' the default.

If you specify either start_epoch or end_epoch, you get data with epochs at least equal to the start epoch, but less than the end epoch (i.e. the interval is closed at the beginning but open at the end). If you specify only one of these, you get a one-day interval. Dates are specified either numerically (as a Perl date) or as numeric year-month-day, punctuated by any non-numeric string. It is an error to specify an end_epoch before the start_epoch.

If you are passing the options as a hash reference, you must specify a value for the boolean options 'descending' and 'last5'. This value is interpreted in the Perl sense - that is, undef, 0, and '' are false, and anything else is true.

In order not to load the Space Track web site too heavily, data are retrieved in batches of 50. Ranges will be subdivided and handled in more than one retrieval if necessary. To limit the damage done by a pernicious range, ranges greater than the max_range setting (which defaults to 500) will be ignored with a warning to STDERR.

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 ().

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

$resp = $st->search_date (date ...)

This method searches the database for objects launched on the given date. The date is specified as year-month-day, with any non-digit being legal as the separator. You can omit -day or specify it as 0 to get all launches for the given month. You can omit -month (or specify it as 0) as well to get all launches for the given year.

You can specify options for the search as either command-type options (e.g. search (-status => 'onorbit', ...)) or as a leading hash reference (e.g. search ({status => onorbit}, ...)). If you specify the hash reference, option names must be specified in full, without the leading '-', and the argument list will not be parsed for command-type options. Options that take multiple values (i.e. 'exclude') must have their values specified as a hash reference, even if you only specify one value - or none at all.

If you specify command-type options, they may be abbreviated, as long as the abbreviation is unique. Errors in either sort of specification result in an exception being thrown.

In addition to the options available for "retrieve", the following options may be specified:

exclude
  specifies the types of bodies to exclude. The
  value is one or more of 'debris' or 'rocket'.
  If you specify both as command-style options,
  you may either specify the option more than once,
  or specify the values comma-separated.
status
  specifies the desired status of the returned body
  (or bodies). Must be 'onorbit', 'decayed', or 'all'.
  The default is 'all'. Note that this option
  represents status at the time the search was done;
  you can not combine it with the retrieve() date
  options to find bodies onorbit as of a given date
  in the past.

Examples:

search_date (-status => 'onorbit', -exclude =>
   'debris,rocket', -last5 '2005-12-25');
search_date (-exclude => 'debris',
   -exclude => 'rocket', '2005/12/25');
search_date ({exclude => ['debris', 'rocket']},
   '2005-12-25');
search_date ({exclude => 'debris,rocket'}, # INVALID!
   '2005-12-25');

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.

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

$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 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.

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

You can specify the "retrieve" options on this method as well.

$resp = $st->search_name (name ...)

This method searches the database for the named objects. Matches are case-insensitive and all matches are returned.

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.

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

You can specify the "retrieve" and "search_date" options on this method as well. The "search_date" -status option is known to work, but I am not sure about the efficacy the -exclude option.

$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.

See "Attributes" for the names and functions of the attributes.

$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 is available. If not, we do the best we can.

We also recognize 'bye' and 'exit' as commands, which terminate the method. In addition, 'show' is recognized as a synonym for 'get', and 'get' (or 'show') without arguments is special-cased to list all attribute names and their values. Attributes listed without a value have the undefined value.

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->spaceflight ()

This method downloads current orbital elements from NASA's human spaceflight site, http://spaceflight.nasa.gov/. As of July 2006 you get the International Space Station, and the current Space Shuttle mission, if any.

No Space Track account is needed to access this data, even if the 'direct' attribute is false. But if the 'direct' attribute is true, the setting of the 'with_name' attribute is ignored.

This method is a web page scraper. any change in the location of the web pages, or any substantial change in their format, will break this method.

You can specify the "retrieve" options on this method as well. In addition, you can specify -all to get all data. -all will be ignored if -start_epoch, -end_epoch, or -last5 is specified.

$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). This will also happen if the HTTP get succeeds but we do not get the expected content.

Note that when requesting spacetrack data sets by catalog number the setting of the 'with_name' attribute is ignored.

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.

A list of valid names and brief descriptions can be obtained by calling $st->names ('spacetrack'). If you have set the 'verbose' attribute true (e.g. $st->set (verbose => 1)), the content of the error response will include this list. Note, however, that this list does not determine what can be retrieved; if Space Track adds a data set, it can still be retrieved by number, even if it does not appear in the list by either number or name. Similarly, if they remove a data set, being on the list will not help. If they decide to renumber the data sets, retrieval by name will become useless until I get the code updated. The numbers correspond to the 'id=' portion of the URL for the dataset on the Space Track web site

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 ().

If this method succeeds, a 'Pragma: spacetrack-type = orbit' header is added to the HTTP::Response object returned.

Attributes

The following attributes may be modified by the user to affect the operation of the Astro::SpaceTrack object. The data type of each is given in parentheses after the attribute name.

Boolean attributes are typically set to 1 for true, and 0 for false.

addendum (text)

This attribute specifies text to add to the output of the banner() method.

The default is an empty string.

This attribute specifies whether or not the shell() method should emit the banner text on invocation.

The default is true (i.e. 1).

This attribute specifies the expiration time of the cookie. You should only set this attribute with a previously-retrieved value, which matches the cookie.

direct (boolean)

This attribute specifies that orbital elements should be fetched directly from the redistributer if possible. At the moment the only methods affected by this are celestrak() and spaceflight().

The default is false (i.e. 0).

fallback (boolean)

This attribute specifies that orbital elements should be fetched from the redistributer if the original source is offline. At the moment the only method affected by this is celestrak().

The default is false (i.e. 0).

filter (boolean)

If true, this attribute specifies that the shell is being run in filter mode, and prevents any output to STDOUT except orbital elements -- that is, if I found all the places that needed modification.

The default is false (i.e. 0).

iridium_status_format (string)

This attribute specifies the format of the data returned by the iridium_status method. Valid values are 'kelso' and 'mccants'. See that method for more information.

The default is 'mccants' for historical reasons, but 'kelso' is probably preferred.

max_range (number)

This attribute specifies the maximum size of a range of NORAD IDs to be retrieved. Its purpose is to impose a sanity check on the use of the range functionality.

The default is 500.

password (text)

This attribute specifies the Space-Track password.

The default is an empty string.

This attribute specifies the session cookie. You should only set it with a previously-retrieved value.

The default is an empty string.

url_iridium_status_kelso (text)

This attribute specifies the location of the celestrak.com Iridium information. You should normally not change this, but it is provided so you will not be dead in the water if Dr. Kelso needs to re-arrange his web site.

The default is 'http://celestrak.com/SpaceTrack/query/iridium.txt'

url_iridium_status_mccants (text)

This attribute specifies the location of Mike McCants' Iridium status page. You should normally not change this, but it is provided so you will not be dead in the water if Mr. McCants needs to change his ISP or re-arrange his web site.

The default is 'http://www.io.com/~mmccants/tles/iridium.html'

url_iridium_status_sladen (text)

This attribute specifies the location of Rod Sladen's Iridium Constellation Status page. You should normally not need to change this, but it is provided so you will not be dead in the water if Mr. Sladen needs to change his ISP or re-arrange his web site.

The default is 'http://www.rod.sladen.org.uk/iridium.htm'.

username (text)

This attribute specifies the Space-Track username.

The default is an empty string.

verbose (boolean)

This attribute specifies verbose error messages.

The default is false (i.e. 0).

webcmd (string)

This attribute specifies a system command that can be used to launch a URL into a browser. If specified, the 'help' command will append a space and the search.cpan.org URL for the documentation for this version of Astro::SpaceTrack, and spawn that command to the operating system. You can use 'open' under Mac OS X, and 'start' under Windows. Anyone else will probably need to name an actual browser.

with_name (boolean)

This attribute specifies whether the returned element sets should include the common name of the body (three-line format) or not (two-line format). It is ignored if the 'direct' attribute is true; in this case you get whatever the redistributer provides.

The default is false (i.e. 0).

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. The Human Space Flight portion of the functionality relies on the stability of the layout of the relevant web pages.

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 did not 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.
 0.010 14-Oct-2005 T. R. Wyant
   Added the 'direct' attribute, to fetch elements
   directly from celestrak. And about time, too.
 0.011 30-Oct-2005 T. R. Wyant
   Added 'Pragma: spacetrack-type = orbit' header to
   the response for those methods that return orbital
   elements, if the request in fact succeeded.
   Added content_type() method to check for the above.
   Played the CPANTS game.
   Added "All rights reserved." to copyright statement.
 0.012 04-Nov-2005 T. R. Wyant
   Added support for number ranges in retrieve(), to
   track support for these on www.space-track.org.
   Added max_range attribute for sanity checking.
 0.013 21-Nov-2005 T. R. Wyant
   Added spaceflight() method.
   Added "All rights reserved." to banner() output.
   Spiffed up the documentation.
 0.014 28-Jan-2006 T. R. Wyant
   Added filter attribute.
   Jocky the Term::ReadLine code yet again.
 0.015 01-Feb-2006 T. R. Wyant
   Added webcmd attribute, and use it in help().
 0.016 11-Feb-2006 T. R. Wyant
   Added content types 'help' and 'get', so -filter
   does not supress output.
   Added iridium_status, & content type 'iridium-status'.
 0.017 27-Apr-2006 T. R. Wyant
   Added retrieve() options.
 0.018 30-May-2006 T. R. Wyant
   Added amsat() method.
 0.019 11-Jun-2006 T. R. Wyant
   Added the retrieve() options to celestrak() and file().
 0.020 01-Jul-2006 T. R. Wyant
   Add the retrieve() qualifiers to spaceflight().
   Add the attribute_names() method.
   Tweak docs, correct spelling.
 0.021 13-Jul-2006 T. R. Wyant
   Add -all qualifier to spaceflight().
   Add search_date().
 0.022 20-Jul-2006 T. R. Wyant
    Documentation corrections.
 0.023 08-Sep-2006 T. R. Wyant
    Added spaceflight() pseudo-catalogs 'iss' and 'station'.
    Have spaceflight() return NO_RECORDS on failure, not
      NO_CAT_ID.
    Have attribute_names() return list ref in scalar context.
    Add attribute iridium_status_format; have iridium_status()
      use this to decide who to access and what format to
      return, including support for the new Celestrak status
      information.
    Have iridium_status() return parsed data with 'portable'
      status if called in list context.
 0.024 12-Sep-2006 T. R. Wyant
    No substantive changes to this module, but retracted
      t/pod_spelling.t, and tried to make Build.PL work with
      ActiveState's build system.
 0.025 19-Oct-2006 T. R. Wyant
    Recognize new Kelso Iridium status '[+]' = working.
    Make Makefile.PL not run Build.PL with old MakeMaker.
    Retract kluge to Build.PL, which is no longer needed.
 0.026 06-Nov-2006 T. R. Wyant
    New location for Mike McCants' Iridium status page.
    New attributes url_iridium_status_kelso and
      url_iridium_status_mccants so users are not dead
      in the water if this happens again.
 0.027 30-Jan-2007 T. R. Wyant
    Add ability to search by on-orbit status ('onorbit',
      'decayed', or 'all'), and to exclude 'debris' and
      'rocket' (bodies).
    Tweak docs.
    Update copyright.
 0.028 15-May-2007 T. R. Wyant
    Interpret missing spacetrack() catalog as a failure,
      even though the request succeeds.
    Ditto missing Space Track retrieve() data.
    Add 'fallback' attribute to cause celestrak() to fall
      back to using Celestrak data if Space Track data
      are not available.
    Clear session cookie when username or password change.
 0.029 13-Oct-2007 T. R. Wyant
     Add Celestrak galileo and sbas data set names to catalog.
     Document celestrak data set names, or at least how to get them and
	 in general how they are formed.
     Trap and error out on invalid spacetrack() data set numbers.
     Add data set numbers to spacetrack() help.
     Document how to get the current spacetrack data set names and
	 numbers, and what happens if they renumber.
     Trap case where 'get' is called without an argument.
     Have 'shell' method interpret 'show' as 'get', and special-case
	 'get' without arguments to display all attributes. Document
	 this.
 0.030 24-Oct-2007 T. R. Wyant
     Add Celestrak 'sts' data set name to catalog.
     Different error text for data sets in catalog but 404 and data sets
	 not in catalog and 404.
 0.031 21-Dec-2007 T. R. Wyant
     Fix embedded modifier bug, exposed by the fixing of the
	 corresponding Perl bug (id=22354) in 5.10.0 -- or 5.9.0
	 actually. Thanks to Andy Lester's article:
	 http://perlbuzz.com/mechanix/2007/12/code-broken-by-regex-fixes-in.html
	 which tipped me off before I had to discover the problem
	 for myself.
     Fixed dependencies in Makefile.PL and Build.PL.
     Went back to prompting for executables in Makefile.PL and
         Build.PL, as a way to handle apparant ActiveState built
	 failure because both they and I were running pl2bat.bat.
     Enhance ExtUtils::MakeMaker version detection in Makefile.PL,
         since ActiveState is apparantly deploying a Perl 5.10
	 with a development version of that module.
 0.032 06-Jul-2008 T. R. Wyant
     More graceful failure when unable to parse Space Track data.
 0.033 30-Sep-2008 T. R. Wyant
     Fix Build.PL -y (and -n)
     Add iridium_status('sladen') to scrape Rod Sladen's Iridium
         Constallation Status web page.
     Add attribute 'url_iridium_status_sladen'.

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, 2006, 2007, 2008 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.

LICENSE

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.