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;

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

In practice, it is probably not useful to retrieve data from any source more often than once every four hours, and in fact daily usually suffices.

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 to retrieve content from the Space Track web site.

DEPRECATION NOTICE: SPACE SHUTTLE

It is with a sense of regret that I announce the deprecation of the celestrak() 'sts' catalog and the spaceflight() 'SHUTTLE' argument, because of the end of the Space Shuttle program on July 21 2011.

With this release (0.071), all uses of celestrak() 'sts' or spaceflight() 'SHUTTLE' will generate an exception.

With the first release on or after August 16 2013, the deprecated functionality will be removed. This means (probably) you will get a 404 error when you try to use it.

DEPRECATION NOTICE: SPACE TRACK VERSION 1 API

The Space Track version 1 API was taken out of service July 16 2013 at 18:00 UT. Therefore, as of version 0.077, an attempt to set the space_track_version attribute to 1 will result in a fatal error. Subsequent releases of this package will remove the code related to the version 1 API.

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. This method may not require a Space Track username and password, depending on how you have the Astro::SpaceTrack object configured. See the documentation on this method for the details.

Other methods (amsat(), spaceflight() ...) have been added to access other repositories of orbital data, and in general these do not require a Space Track username and password.

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, and a 'Pragma: spacetrack-source =' header to specify what source the data came from.

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. On a successful return, the response object will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = amsat

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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->box_score ();

This method returns the SATCAT Satellite Box Score information from the Space Track web site. If it succeeds, the content will be the actual box score data, including headings and totals, with the fields tab-delimited.

This method takes option -json, specified either command-style (i.e. $st->box_score( '-json' )) or as a hash reference (i.e. $st->box_score( { json => 1 } )). This causes the body of the response to be the JSON data as returned from Space Track.

This method requires a Space Track username and password. It 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, the response will contain headers

Pragma: spacetrack-type = box_score
Pragma: spacetrack-source = spacetrack

There are no arguments.

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

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

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.

The Celestrak web site makes a few items available for direct-fetching only ($st->set(direct => 1), see below.) These are typically debris from collisions or explosions. I have not corresponded with Dr. Kelso on this, but I think it reasonable to believe that asking Space Track for a couple thousand sets of data at once would not be a good thing.

As of this release, the following data sets may be direct-fetched only:

1999-025: This is the debris of Chinese communication satellite Fengyun 1C, created by an antisatellite test on January 11 2007. As of February 21 2010 there are 2631 pieces of debris in the data set. This is an increase from the 2375 recorded on March 9 2009.
usa-193-debris: This is the debris of U.S. spy satellite USA-193 shot down by the U.S. on February 20 2008. As of February 21 2010 there are no pieces of debris in the data set. I noted 1 piece on March 9 2009, but this was an error - that piece actually decayed October 9 2008, but I misread the data. The maximum was 173. Note that as of February 21 2010 you still get the remaining piece when you direct-fetch the data from Celestrak.
cosmos-2251-debris: This is the debris of Russian communication satellite Cosmos 2251, created by its collision with Iridium 33 on February 10 2009. As of February 21 2010 there are 1105 pieces of debris in the data set, up from the 357 that had been cataloged as of March 9 2009.
iridium-33-debris: This is the debris of U.S. communication satellite Iridium 33, created by its collision with Cosmos 2251 on February 10 2009. As of February 21 2010 there are 461 pieces of debris in the data set, up from the 159 that had been cataloged as of March 9 2009.
2012-044: This is the debris of a Breeze-M upper stage (OID 38746, International Designator 2012-044C), which exploded October 16 2012. As of October 25 there were 81 pieces of debris in the data set.

Before the end of the Space Shuttle program, data on the current mission (if any) was available as data set 'sts'. This catalog is now deprecated, and will be removed in a future release. See the "DEPRECATION NOTICE" for details.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source =

The spacetrack-source will be 'spacetrack' if the TLE data actually came from Space Track, or 'celestrak' if the TLE data actually came from Celestrak. The former will be the case if the direct attribute is false and either the fallback attribute was false or the Space Track web site was accessible. Otherwise, the latter will be the case.

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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

$resp = $st->celestrak_supplemental ($name);

This method takes the name of a Celestrak supplemental data set and returns an HTTP::Response object whose content is the relevant element sets.

These TLE data are not redistributed from Space Track, but are derived from publicly available ephemeris data for the satellites in question.

The -rms option can be specified to return the RMS data, if it is available.

A list of valid names and brief descriptions can be obtained by calling $st->names( 'celestrak_supplemental' ). 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.

For more information, see http://celestrak.com/NORAD/elements/supplemental/.

$source = $st->content_source($resp);

This method takes the given HTTP::Response object and returns the data source specified by the 'Pragma: spacetrack-source =' header. What values you can expect depend on the content_type (see below) as follows:

If the content_type() method returns 'box_score', you can expect a content-source value of 'spacetrack'.

If the content_type method returns 'iridium-status', you can expect content_source values of 'kelso', 'mccants', or 'sladen', corresponding to the main source of the data.

If the content_type() method returns 'orbit', you can expect content-source values of 'amsat', 'celestrak', 'spaceflight', or 'spacetrack', corresponding to the actual source of the TLE data. Note that the celestrak() method may return a content_type of 'spacetrack' if the direct attribute is false.

If the content_type() method returns 'search', you can expect a content-source value of 'spacetrack'.

For any other values of content-type (e.g. 'get', 'help'), the expected values are undefined. In fact, you will probably literally get undef, but the author does not commit even to this.

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

If the response object is provided, you can call this as a static method (i.e. as Astro::SpaceTrack->content_source($response)).

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

'box_score': The content is the Space Track satellite
        box score.
'get': The content is a parameter value.
'help': The content is help text.
'iridium_status': The content is Iridium status.
'modeldef': The content is a REST model definition.
'orbit': The content is NORAD data sets.
'search': The content is Space Track search results.
'set': The content is the result of a 'set' operation.
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.

If the response object is provided, you can call this as a static method (i.e. as Astro::SpaceTrack->content_type($response)).

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

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

1: The content was obtained using the version 1 interface.
2: The content was obtained using the version 2 interface.
undef: The content did not come from Space Track.

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

If the response object is provided, you can call this as a static method (i.e. as Astro::SpaceTrack->content_type($response)).

$resp = $st->country_names()

This method returns the list of country abbreviations and names from the Space Track web site. If it succeeds, the content will be the abbreviations and names, including headings, with the fields tab-delimited.

This method takes option -json, specified either command-style (i.e. $st->country_names( '-json' )) or as a hash reference (i.e. $st->country_names( { json => 1 } )). This causes the body of the response to be the JSON representation of a hash whose keys are the country abbreviations, and whose values are the corresponding country names.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = box_score
Pragma: spacetrack-source = spacetrack

There are no arguments.

$resp = $st->favorite( $name )

This method takes the name of a favorite set up by the user on the Space Track web site, and returns the bodies specified. The 'global' favorites (e.g. 'Navigation', 'Weather', and so on) may also be fetched. Additionally, the -json option may be specified, either in command-line format or as a leading hash reference. For example,

$resp = $st->favorite( '-json', 'Weather' );
$resp = $st->favorite( { json => 1 }, 'Weather' );

both work.

$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, retrieved from the Space Track web site. 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.

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, the response will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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.

If this method succeeds, the response will contain header

Pragma: spacetrack-type = get

This can be accessed by $st->content_type( $resp ).

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

$value = $st->getv (attrib)

This method returns the value of the given attribute, which is what get() should have done.

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.

If this method succeeds and the webcmd attribute is not set, the response will contain header

Pragma: spacetrack-type = help

This can be accessed by $st->content_type( $resp ).

Otherwise (i.e. in any case where the response does not contain actual help text) this header will be absent.

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

No Space Track username and password are required to use this method.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = iridium_status
Pragma: spacetrack-source =

The spacetrack-source will be 'kelso', 'mccants', or 'sladen', depending on the format requested.

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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 03-Dec-2010 Mike's web page documented the possible statuses as follows:

 blank   Object is operational
 tum     tumbling - no flares, but flashes seen on favorable
         transits.
 unc     uncontrolled
 ?       controlled, but not at operational altitude -
         flares may be unreliable.
 man     maneuvering, at least slightly. Flares may be
	 unreliable and the object may be early or late
         against prediction.

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 failed satellites will be marked '[-]', with the corresponding portable statuses. As of version 0.035, all failed satellites will be marked '[-]'. Previous to this release, failed satellites not specifically marked as tumbling were 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->launch_sites()

This method returns the list of launch site abbreviations and names from the Space Track web site. If it succeeds, the content will be the abbreviations and names, including headings, with the fields tab-delimited.

This method takes option -json, specified either command-style (i.e. $st->launch_sites( '-json' )) or as a hash reference (i.e. $st->launch_sites( { json => 1 } )). This causes the body of the response to be the JSON representation of a hash whose keys are the launch site abbreviations, and whose values are the corresponding launch site names.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = launch_sites
Pragma: spacetrack-source = spacetrack

There are no arguments.

$resp = $st->login ( ... )

If any arguments are given, this method passes them to the set () method. Then it executes a login to the Space Track web site. 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 HTTP_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 HTTP_PRECONDITION_FAILED from HTTP::Status (a.k.a. 412).

A Space Track username and password are required to use this method.

$st->logout()

This method deletes all session cookies. It returns an HTTP::Response object that indicates success.

$resp = $st->names (source)

This method retrieves the names of the catalogs for the given source, either 'celestrak', 'iridium_status', 'spaceflight', 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, in that order (suitable for inserting into a Tk Optionmenu).

No Space Track username and password are required to use this method, since all it is doing is returning data kept by this module.

$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) from The Space Track web site. Non-numeric catalog numbers are ignored, as are (at a later stage) numbers that do not actually represent a satellite.

A Space Track username and password are required to use this method.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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.
-json
  specifies the TLE be returned in JSON format
-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.
-since_file number
  specifies that only data since the given Space Track
  file number be retrieved.
-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 (and optional hour, hour:minute, or hour:minute:second, but these are ignored under the Space Track version 1 interface), 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.

If you specify -json and more than one retrieval is needed, data from retrievals after the first may have field _file_of_record added. This is because of the theoretical possibility that the database may be updated between the first and last queries, and therefore taking the maximum FILE from queries after the first may cause updates to be skipped. The _file_of_record key will appear only in data having a FILE value greater than the largest FILE in the first retrieval.

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 Space Track 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.

A Space Track username and password are required to use this method.

You can specify options for the search as either command-type options (e.g. $st->search_date (-status => 'onorbit', ...)) or as a leading hash reference (e.g. $st->search_date ({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.
-rcs
  specifies that the radar cross-section returned by
  the search is to be appended to the name, in the form
  --rcs radar_cross_section. If the with_name attribute
  is false, the radar cross-section will be inserted as
  the name. Historical rcs data appear NOT to be
  available.
-status
  specifies the desired status of the returned body
  (or bodies). Must be 'onorbit', 'decayed', or 'all'.
  The default is 'all' under version 1 of the Space
  Track interface, and 'onorbit' under version 2. 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.
-tle
  specifies that you want TLE data retrieved for all
  bodies that satisfy the search criteria. This is
  true by default, but may be negated by specifying
  -notle ( or { tle => 0 } ). If negated, the content
  of the response object is the results of the search,
  one line per body found, with the fields tab-
  delimited.

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');
search_date ( '-notle', '2005-12-25' );

The -exclude option is implemented in terms of the OBJECT_TYPE predicate, which is one of the values 'PAYLOAD', 'ROCKET BODY', 'DEBRIS', 'UNKNOWN', or 'OTHER'. It works by selecting all values other than the ones specifically excluded.

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

What you get on success depends on the value specified for the -tle option.

Unless you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the relevant element sets. It will also have the following headers set:

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

If you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the results of the relevant search, one line per object found. Within a line the fields are tab-delimited, and occur in the same order as the underlying web page. The first line of the content is the header lines from the underlying web page. It will also have the following headers set:

Pragma: spacetrack-type = search
Pragma: spacetrack-source = spacetrack

If you call this method in list context, the first element of the returned object is the aforementioned HTTP::Response object, and the second is a reference to an array containing the search results. The first element is a reference to an array containing the header lines from the web page. Subsequent elements are references to arrays containing the actual search results.

$resp = $st->search_decay (decay ...)

This method searches the Space Track database for objects decayed 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 decays for the given month. You can omit -month (or specify it as 0) as well to get all decays for the given year.

The options are the same as for "search_date".

A Space Track username and password are required to use this method.

What you get on success depends on the value specified for the -tle option.

Unless you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the relevant element sets. It will also have the following headers set:

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

Pragma: spacetrack-type = search
Pragma: spacetrack-source = spacetrack

$resp = $st->search_id (id ...)

This method searches the Space Track 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 ZZZ, 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.

The options are the same as for "search_date".

A Space Track username and password are required to use this method.

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

What you get on success depends on the value specified for the -tle option.

Unless you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the relevant element sets. It will also have the following headers set:

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

Pragma: spacetrack-type = search
Pragma: spacetrack-source = spacetrack

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

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

The options are the same as for "search_date". The -status option is known to work, but I am not sure about the efficacy the -exclude option.

A Space Track username and password are required to use this method.

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

What you get on success depends on the value specified for the -tle option.

Unless you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the relevant element sets. It will also have the following headers set:

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

Pragma: spacetrack-type = search
Pragma: spacetrack-source = spacetrack

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

This method searches the Space Track database for the given Space Track IDs (also known as OIDs, hence the method name).

Note that in effect this is just a stupid, inefficient version of retrieve(), which does not understand ranges. Unless you assert -notle or -rcs, or call it in list context to get the search data, you should simply call retrieve() instead.

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

rcs
  specifies that the radar cross-section returned by
  the search is to be appended to the name, in the form
  --rcs radar_cross_section. If the with_name attribute
  is false, the radar cross-section will be inserted as
  the name. Historical rcs data appear NOT to be
  available.
tle
  specifies that you want TLE data retrieved for all
  bodies that satisfy the search criteria. This is
  true by default, but may be negated by specifying
  -notle ( or { tle => 0 } ). If negated, the content
  of the response object is the results of the search,
  one line per body found, with the fields tab-
  delimited.

If you specify -notle, all other options are ignored, except for -descending.

A Space Track username and password are required to use this method.

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

What you get on success depends on the value specified for the -tle option.

Unless you explicitly specified -notle (or { tle => 0 }), this method returns an HTTP::Response object whose content is the relevant element sets. It will also have the following headers set:

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

If the content_type() method returns 'box_score', you can expect a content-source value of 'spacetrack'.

Pragma: spacetrack-type = search
Pragma: spacetrack-source = spacetrack

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

There are also a couple meta-commands, that in effect wrap other commands. These are specified before the command, and can (depending on the meta-command) have effect either right before the command is executed, right after it is executed, or both. If more than one meta-command is specified, the before-actions take place in the order specified, and the after-actions in the reverse of the order specified.

The 'time' meta-command times the command, and writes the timing to standard error before any output from the command is written.

The 'olist' meta-command turns TLE data into an observing list. This only affects results with spacetrack-type of 'orbit'. If the content is affected, the spacetrack-type will be changed to 'observing-list'. This meta-command is experimental, and may change function or be retracted. It is unsupported when applied to commands that do not return TLE data.

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.

Redirections will not be recognized as such if quoted or escaped. That is, both >foo and >'foo' (without the double quotes) are redirections to file foo, but both "'>foo'" and \>foo are arguments whose value is >foo.

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 21 2011 you only get the International Space Station.

You can specify either or both of the arguments 'ISS' and 'SHUTTLE' (case-insensitive) to retrieve the data for the International Space Station or the Space Shuttle respectively. Since the end of the Space Shuttle program, the 'SHUTTLE' argument retrieves nothing, and is deprecated. See the "DEPRECATION NOTICE" for details.

In addition you can specify options, either as command-style options (e.g. -all) or by passing them in a hash as the first argument (e.g. {all = 1}>). The options specific to this method are:

all
 causes all TLEs for a body to be downloaded;
effective
 causes the effective date to be added to the data.

In addition, any of the "retrieve" options is valid for this method as well.

The -all option is recommended, but is not the default for historical reasons. If you specify -start_epoch, -end_epoch, or -last5, -all will be ignored.

The -effective option hacks the effective date of the data onto the end of the common name (i.e. the first line of the 'NASA TLE') in the form --effective=date where the effective date is encoded the same way the epoch is. Specifying this forces the generation of a 'NASA TLE'.

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.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spaceflight

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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.

$resp = $st->spacetrack ($name);

This method returns predefined sets of data from the Space Track web site, using either canned queries or global favorites.

The following catalogs are available:

Name            Description
full            Full catalog
full_fast       Full catalog, faster but less
                    accurate query (DEPRECATED)
payloads        All payloads
navigation      Navigation satellites
weather         Weather satellites
geosynchronous  Geosynchronous bodies
geosynchronous_fast Geosynchronous bodies, faster
                    but less accurate query (DEPRECATED)
iridium         Iridium satellites
orbcomm         OrbComm satellites
globalstar      Globalstar satellites
intelsat        Intelsat satellites
inmarsat        Inmarsat satellites
amateur         Amateur Radio satellites
visible         Visible satellites
special         Special satellites

The *_fast queries are, as of version 0.069_02, the same as their un-fast versions. The queries are those implemented on the Space Track web site, and may included recently-decayed satellites.

The *_fast queries are also deprecated as of version 0.069_02. Because these were always considered unsupported, the deprecation cycle will be accelerated. They will carp() on every use, and six months after release 0.070 will produce fatal errors. Six months after they become fatal, they will be removed completely.

The following option is supported:

-json
  specifies the TLE be returned in JSON format

Options may be specified either in command-line style (that is, as spacetrack( '-json', ... )) or as a hash reference (that is, as spacetrack( { json => 1 }, ... )).

This method returns an HTTP::Response object. If the operation succeeded, the content of the response will be the requested data, unzipped if you used the version 1 interface.

If you requested a non-existent catalog, the response code will be HTTP_NOT_FOUND (a.k.a. 404); otherwise the response code will be whatever the underlying HTTPS request returned.

A Space Track username and password are required to use this method.

If this method succeeds, the response will contain headers

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack

These can be accessed by $st->content_type( $resp ) and $st->content_source( $resp ) respectively.

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 the list of valid names. Note, however, that under version 1 of the interface this list does not determine what can be retrieved.

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->spacetrack_query_v2( @path );

This method exposes the Space Track version 2 interface (a.k.a the REST interface). It has nothing to do with the (probably badly-named) spacetrack() method.

The arguments are the arguments to the REST interface. These will be URI-escaped, and a login will be performed if necessary. This method returns an HTTP::Response object containing the results of the operation.

Except for the URI escaping of the arguments and the implicit login, this method interfaces directly to Space Track. It is provided for those who want a way to experiment with the REST interface, or who wish to do something not covered by the higher-level methods.

For example, if you want the JSON version of the satellite box score (rather than the tab-delimited version provided by the box_score() method) you will find the JSON in the response object of the following call:

my $resp = $st->spacetrack_query_v2( qw{
    basicspacedata query class boxscore
    format json predicates all
    } );
);

If this method is called directly from outside the Astro::SpaceTrack name space, pragmata will be added to the results based on the arguments, as follows:

For basicspacedata => 'modeldef'

Pragma: spacetrack-type = modeldef
Pragma: spacetrack-source = spacetrack
Pragma: spacetrack-interface = 2

For basicspacedata => 'query' and class => 'tle' or 'tle_latest',

Pragma: spacetrack-type = orbit
Pragma: spacetrack-source = spacetrack
Pragma: spacetrack-interface = 2

$resp = $st->update( $file_name );

This method updates the named TLE file, which must be in JSON format. On a successful update, the content of the returned HTTP::Response object is the updated TLE data, in whatever format is desired. If any updates were in fact found, the file is rewritten. The rewritten JSON will be pretty if the pretty attribute is true.

The file to be updated can be generated by using the -json option on any of the methods that accesses Space Track data. For example,

# Assuming $ENV{SPACETRACK_USER} contains
# username/password
my $st = Astro::SpaceTrack->new(
    pretty              => 1,
);
my $rslt = $st->spacetrack( { json => 1 }, 'iridium' );
$rslt->is_success()
    or die $rslt->status_line();
open my $fh, '>', 'iridium.json'
    or die "Failed to open file: $!";
print { $fh } $rslt->content();
close $fh;

The following is the equivalent example using the SpaceTrack script:

SpaceTrack> set pretty 1
SpaceTrack> spacetrack -json iridium >iridium.json

This method reads the file to be updated, determines the highest FILE value, and then requests the given OIDs, restricting the return to FILE values greater than the highest found. If anything is returned, the file is rewritten.

The following options may be specified:

-json
  specifies the TLE be returned in JSON format

Options may be specified either in command-line style (that is, as spacetrack( '-json', ... )) or as a hash reference (that is, as spacetrack( { json => 1 }, ... )).

Note that there is no way to specify the -rcs or -effective options. If the file being updated contains these values, they will be lost as the individual OIDs are updated.

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.

banner (boolean)

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

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

cookie_expires (number)

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

cookie_name (string)

This attribute specifies the name of the session cookie. You should not need to change this in normal circumstances, but if Space Track changes the name of the session cookie you can use this to get you going again.

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

domain_space_track (string)

This attribute specifies the domain name of the Space Track web site. The user will not normally need to modify this, but if the web site changes names for some reason, this attribute may provide a way to get queries going again.

The default is 'www.space-track.org'. This will change if necessary to remain appropriate to the Space Track web site.

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.

pretty (boolean)

This attribute specifies whether the content of the returned HTTP::Response is to be pretty-formatted. Currently this only applies to Space Track data returned in JSON format. Pretty-formatting the JSON is extra overhead, so unless you intend to read the JSON yourself this should probably be false.

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

scheme_space_track (string)

This attribute specifies the URL scheme used to access the Space Track web site. The user will not normally need to modify this, but if the web site changes schemes for some reason, this attribute may provide a way to get queries going again.

The default is 'https'.

session_cookie (text)

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

The default is an empty string.

space_track_version (integer)

This attribute specifies the version of the Space Track interface to use to retrieve data. The only valid value is 2. If you set it to a false value (i.e. undef, 0, or '') it will be set to the default.

The default is 2.

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

verify_hostname (boolean)

This attribute specifies whether https: certificates are verified. If you set this false, you can not verify that hosts using https: are who they say they are, but it also lets you work around invalid certificates. Currently only the Space Track web site uses https:.

Note that the default has changed. In version 0.060_08 and earlier, the default was true, to mimic earlier behavior. In version 0.060_09 this was changed to false, in the belief that the code should work out of the box (which it did not when verify_hostname was true, at least as of mid-July 2012). But on September 30 2012 Space Track announced that they had their SSL certificates set up, so in 0.064_01 the default became false again.

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

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 and password, separated by either a slash ('/') or a colon (':'). That is, either 'yehudi/menuhin' or 'yehudi:menuhin' are accepted.

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

SPACETRACK_REST_RANGE_OPERATOR

This environment variable controls whether the Space Track version 2 interface (a.k.a. the REST interface) uses OID ranges in its queries. A value Perl sees as false (i.e. 0 or '') causes ranges not to be used. A value Perl sees as true (i.e. anything else) causes ranges to be used. The default is to use ranges.

Support for this environment variable will be removed the first release after January 1 2014, since I think range support in the REST interface is stable.

SPACETRACK_REST_FRACTIONAL_DATE

This environment variable controls whether the Space Track version 2 interface (a.k.a. the REST interface) will query epoch ranges (i.e. the -start_epoch and -end_epoch retrieve() options) to fractional-day resolution. A value Perl sees as false (i.e. 0 or '') causes epoch queries to be truncated to even days. A value Perl sees as true (i.e. anything else) causes epoch queries to be to the nearest second. The default is to query to the nearest second.

Support for this environment variable will be removed the first release after January 1 2014, since I think fractional-day query support in the REST interface is stable.

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

See the Changes file.

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 AND LICENSE

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

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

To install Astro::SpaceTrack, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::SpaceTrack

CPAN shell

perl -MCPAN -e shell
install Astro::SpaceTrack

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

LEGAL NOTICE

DEPRECATION NOTICE: SPACE SHUTTLE

DEPRECATION NOTICE: SPACE TRACK VERSION 1 API

DESCRIPTION

Methods

Attributes

ENVIRONMENT

SPACETRACK_OPT

SPACETRACK_USER

SPACETRACK_REST_RANGE_OPERATOR

SPACETRACK_REST_FRACTIONAL_DATE

EXECUTABLES

SpaceTrack

SpaceTrackTk

BUGS

MODIFICATIONS

ACKNOWLEDGMENTS

AUTHOR

COPYRIGHT AND LICENSE

LICENSE

Module Install Instructions