Astro::SpaceTrack(3pm)

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

 $ SpaceTrack

 (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 either of the above, username and password entry can be omitted if you have installed Config::Identity, created an IDENTITY FILE (see below) containing these values, and set the "identity" attribute to a true value. You probably want to encrypt the identity file, if you have "gpg2" and "gpg-agent".

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.

CAVEAT
Version 0.180 was an emergency release of this module. It was caused by Space Track deprecating and ultimately revoking the 'tle_latest' and 'tle' data classes in favor of 'gp' and 'gp_history' respectively, and me being oblivious until the revocation occurred.

Unlike the previous release (v0.172) release 0.180 will actually return Space Track data.

Known changes:

The --last5 option is ignored.
    It is also deprecated, will warn on every use, and will be removed in a future release. This functionality relied on a datum ("ORDINAL") that Space Track no longer provides.

The "OBJECT_NUMBER" datum is missing from JSON data.
    This datum is no longer provided by Space Track, and I am not minded to fudge it in. "NORAD_CAT_ID" has the same value.

Favorites do not work
    In the previous release spacetrack() would fetch canned favorites curated by Space Track. As of January 21 2026 these are 404. If I find these data sets I will restore them. Favorites can still be retrieved via the favorite() method.

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 <https://www.space-track.org/documentation#/user_agree>.

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.

FUNCTIONAL NOTICES

  CELESTRAK API
The Celestrak web site, <https://celestrak.org/>, is in transition from being simply a file based repository of TLEs to an API-based service providing orbital elements in a number of formats. The celestrak() and celestrak_supplemental() methods will track this, growing new arguments as needed.

  DEPRECATION NOTICE: IRIDIUM STATUS
As of version 0.137, Iridium status format 'mccants' is fully deprecated, and will result in an exception.

As of version 0.143, any access of attribute "url_iridium_status_mccants" is fatal.

As of version 0.169, any use of attribute "url_iridium_status_kelso" is fatal.

As of version 0.181, any remaining functionality relating to Iridium Classic satellites is fatal, except for attribute iridium_status_format, which I missed, and which warns on the first use. This will be put through the usual deprecation cycle. Six months after it becomes fatal, all Iridium functionality will be dropped.

DESCRIPTION
This package retrieves orbital data from the Space Track web site <https://www.space-track.org> and several others. You must register and get a user name and password before you can get data from Space Track.

Other methods (celestrak() ...) 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.

    For both historical and operational reasons, this method can get the "username" and "password" values from multiple locations. It uses the first defined value it finds in the following list:

    a value explicitly specified as an argument to new();
    a value from the IDENTITY FILE, if the "identity" attribute is explicitly specified as true and Config::Identity is installed;
    a value from environment variable "SPACETRACK_USER" if that has a non-empty value;
    a value from the IDENTITY FILE, if the "identity" attribute defaulted to true and Config::Identity s installed;
    a value from environment variable "SPACETRACK_OPT".

    The reason for preferring "SPACETRACK_USER" over an identity file value taken by default is that I have found that under Mac OS X an SSH session does not have access to the system keyring, and Config::Identity provides no other way to specify the passphrase used to decrypt the private key. I concluded that if the user explicitly requested an identity that it should be preferred to anything from the environment, but that, for SSH access to be usable, I needed to provide a source of username and password that would be taken before the IDENTITY FILE was tried by default.

    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 ()
    Note that this method is non-functional as of September 8 2025 (probably earlier), because Amsat has gone to a "humans-only" policy for their web site. It will be put through the usual deprecation cycle and removed.

    This method downloads current orbital elements from the Radio Amateur Satellite Corporation's web page, <https://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. As of version 0.150 the setting of the 'with_name' attribute is honored.

    You can specify options as either command-type options (e.g. "amsat( '-file', 'foo.dat' )") or as a leading hash reference (e.g. "amsat( { file => 'foo.dat' } )"). 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:

     -file
       specifies the name of the cache file. If the data
       on line are newer than the modification date of
       the cache file, the cache file will be updated.
       Otherwise the data will be returned from the file.
       Either way the content of the file and the content
       of the returned HTTP::Response object end up the
       same.

    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.

    If the "file" option was passed, the following additional header will be provided:

     Pragma: spacetrack-cache-hit = (either true or false)

    This can be accessed by the cache_hit() method. If this pragma is true, the "Last-Modified" header of the response will contain the modification time of the file.

    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 an HTTP::Response object. If the request succeeds, the content of the object will be the SATCAT Satellite Box Score information in the desired format. If the desired format is 'legacy' or 'json' and the method is called in list context, the second returned item will be a reference to an array containing the parsed data.

    This method takes the following options, specified either command-style or as a hash reference.

    "-format" specifies the desired format of the retrieved data. Possible values are 'xml', 'json', 'html', 'csv', and 'legacy', which is the default. The legacy format is tab-delimited text, such as was returned by the version 1 interface.

    "-json" specifies JSON format. If you specify both "-json" and "-format" you will get an exception unless you specify "-format=json".

    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);
    As of version 0.158 this version is an interface to the CelesTrak API. The argument is the argument of a Celestrak query (see <https://celestrak.org/NORAD/documentation/gp-data-formats.php>). The following options are available:

    format
         --format json

        This option specifies the format of the returned data. Valid values are 'TLE', '3LE', '2LE', 'XML', 'KVN', 'JSON', or 'CSV'. See <https://celestrak.org/NORAD/documentation/gp-data-formats.php> for a discussion of these. 'JSON-PRETTY' is not a valid format option, but will be generated if the "pretty" attribute is true.

        The default is 'TLE'.

    query
         --query name

        This option specifies the type of query to be done. Valid values are

        CATNR
            The argument is a NORAD catalog number (1-9 digits).

        GROUP
            The argument is the name of a named group of satellites.

        INTDES
            The argument is an international launch designator of the form yyyy-nnn, where the "yyyy" is the Gregorian year, and the "nnn" is the launch number in the year.

        NAME
            The argument is a satellite name or a portion thereof.

        SPECIAL
            The argument specifies a special data set.

        The default is 'CATNR' if the argument is numeric, 'INTDES' if the argument looks like an international designator, or 'GROUP' otherwise.

    A list of valid "GROUP" 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.

    If this method succeeds, the response will contain headers

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

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

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

    As of version 0.158 this version is an interface to the CelesTrak API. The argument is the argument of a Celestrak query (see <https://celestrak.org/NORAD/documentation/gp-data-formats.php>). The following options are available:

    file
         --file my_data.tle

        This option specifies the name of an output file for the data.

    format
         --format json

        This option specifies the format of the returned data. Valid values are 'TLE', '3LE', '2LE', 'XML', 'KVN', 'JSON', or 'CSV'. See <https://celestrak.org/NORAD/documentation/gp-data-formats.php> for a discussion of these. 'JSON-PRETTY' is not a valid format option, but will be generated if the "pretty" attribute is true.

        The default is 'TLE'.

    match
        This Boolean option specifies that match data be returned rather than TLE data, if available. This option is valid only on known catalogs that actually have match data. If this option is asserted, "--format" and "--query" are invalid.

    query
         --query name

        This option specifies the type of query to be done. Valid values are

        CATNR
            The argument is a NORAD catalog number (1-9 digits).

        FILE
            The argument is the name of a standard data set.

        INTDES
            The argument is an international launch designator of the form yyyy-nnn, where the "yyyy" is the Gregorian year, and the "nnn" is the launch number in the year.

        NAME
            The argument is a satellite name or a portion thereof.

        SOURCE
            The argument specifies a data source as specified at <https://celestrak.org/NORAD/documentation/sup-gp-queries.php>.

        SPECIAL
            The argument specifies a special data set.

        The default is 'CATNR' if the argument is numeric, 'INTDES' if the argument looks like an international designator, or 'FILE' otherwise.

    rms This Boolean option specifies that RMS data be returned rather than TLE data, if available. This option is valid only on known catalogs that actually have RMS data. If this option is asserted, "--format" and "--query" are invalid.

    Valid catalog names are:

     ast      AST Space Mobile
     cpf      CPF (no match data)
     css      CSS (no match data)
     glonass  Glonass satellites
     gps      GPS satellites
     intelsat Intelsat satellites
     iridium  Iridium Next
     iss      ISS (from NASA, no match data)
     kuiper   Project Kuiper (Amazon; no match data)
     oneweb   OneWeb
     planet   Planet (no, not Mercury etc.)
     ses      SES satellites
     starlink Starlink
     telesat  Telesat

    You can specify options as either command-type options (e.g. "celestrak_supplemental( '-file', 'foo.dat' )") or as a leading hash reference (e.g. "celestrak_supplemental( { file => 'foo.dat' })"). 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.

    A list of valid catalog 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.

    If the "file" option was passed, the following additional header will be provided:

     Pragma: spacetrack-cache-hit = (either true or false)

    This can be accessed by the cache_hit() method. If this pragma is true, the "Last-Modified" header of the response will contain the modification time of the file.

    Note that it is my belief that the current Celestrak API (as of September 26 2022) does not support this kind of functionality, so cache_hit() will always return false.

    For more information, see <https://celestrak.org/NORAD/elements/supplemental/>.

$bool = $st->cache_hit( $resp );
    This method takes the given HTTP::Response object and returns the cache hit indicator specified by the 'Pragma: spacetrack-cache-hit =' header. This will be true if the response came from cache, false if it did not, and "undef" if cache was not available.

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

$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 'molczan', you can expect a content_source value of 'mccants'.

    If the content_type() method returns 'orbit', you can expect content-source values of 'amsat', 'celestrak', 'mccants', or 'spacetrack', corresponding to the actual source of the TLE data.

    If the content_type method returns 'quicksat', you can expect a content_source value of 'mccants'.

    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.
     'molczan': Molczan-format magnitude data.
     'orbit': The content is NORAD data sets.
     'quicksat': Quicksat-format magnitude data.
     '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)).

    For the format of the magnitude data, see <https://www.mmccants.org//tles/index.html>.

$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 an HTTP::Response object. If the request succeeds, the content of the object will be the known country names and their abbreviations in the desired format. If the desired format is 'legacy' or 'json' and the method is called in list context, the second returned item will be a reference to an array containing the parsed data.

    This method takes the following options, specified either command-style or as a hash reference.

    "-format" specifies the desired format of the retrieved data. Possible values are 'xml', 'json', 'html', 'csv', and 'legacy', which is the default. The legacy format is tab-delimited text, such as was returned by the version 1 interface.

    "-json" specifies JSON format. If you specify both "-json" and "-format" you will get an exception unless you specify "-format=json".

    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 = country_names
     Pragma: spacetrack-source = spacetrack

    There are no arguments.

$resp = $st->favorite( $name )
    This method returns an HTTP::Response object. If the request succeeds, the content of the response will be TLE data specified by the named favorite in the desired format. The named favorite must have previously been set up by the user, or be one of the 'global' favorites (e.g. 'Navigation', 'Weather', and so on).

    This method takes the following options, specified either command-style or as a hash reference.

    "-format" specifies the desired format of the retrieved data. Possible values are 'xml', 'json', 'html', 'csv', and 'legacy', which is the default. The legacy format is tab-delimited text, such as was returned by the version 1 interface.

    "-json" specifies JSON format. If you specify both "-json" and "-format" you will get an exception unless you specify "-format=json".

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

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

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

    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 <https://metacpan.org/> web page for 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.

    If no format is specified, the format specified in the "iridium_status_format" attribute is used.

    There is one option, 'raw', which can be specified either command-line style (i.e. "-raw") or as a leading hash reference. Asserting this option causes status information from sources other than Celestrak and Rod Sladen not to be supplemented by Celestrak data. In addition, it prevents all sources from being supplemented by canned data that includes all original-design Iridium satellites, including those that have decayed. By default this option is not asserted.

    Format 'mccants' is deprecated, and throws an exception as of version 0.137. This entire method will be deprecated and removed once the last flaring Iridium satellite is removed from service.

    A Space Track username and password are required only if the format is 'spacetrack'.

    If this method succeeds, the response will contain headers

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

    The spacetrack-source will be 'kelso', 'sladen', or 'spacetrack', 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 ("https://celestrak.org/SpaceTrack/query/iridium.txt") is queried for the data. The possible status values are documented at <https://celestrak.org/satcat/status.php>, and repeated here for convenience:

        '[+]' - Operational
        '[-]' - Nonoperational
        '[P]' - Partially Operational
        '[B]' - Backup/Standby
        '[S]' - Spare
        '[X]' - Extended Mission
        '[D]' - Decayed
        '[?]' - Unknown

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

    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 format is 'spacetrack', the data come from both Celestrak and Space Track. For any given OID, we take the Space Track data if it shows the OID as being decayed, or if the OID does not appear in the Celestrak data; otherwise we take the Celestrak data. The idea here is to get a list of statuses that include decayed satellites dropped from the Celestrak list. You will need a Space Track username and password for this. The format of the returned data is the same as for Celestrak data.

    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,
          and capable of producing predictable flares;
      1 = BODY_STATUS_IS_SPARE means object is a spare or
          otherwise not in regular service, but is controlled
          and may be capable of producing predictable flares;
      2 = BODY_STATUS_IS_TUMBLING means object is tumbling
          or otherwise unservicable, and incapable of producing
          predictable flares
      3 - BODY_STATUS_IS_DECAYED neans that the object is decayed.

    In terms of the Kelso statuses, the mapping is:

        '[+]' - BODY_STATUS_IS_OPERATIONAL
        '[-]' - BODY_STATUS_IS_TUMBLING
        '[P]' - BODY_STATUS_IS_SPARE
        '[B]' - BODY_STATUS_IS_SPARE
        '[S]' - BODY_STATUS_IS_SPARE
        '[X]' - BODY_STATUS_IS_SPARE
        '[D]' - BODY_STATUS_IS_DECAYED
        '[?]' - BODY_STATUS_IS_TUMBLING

    The BODY_STATUS constants are exportable using the :status tag.

    This method and the associated manifest constants are deprecated.

$resp = $st->launch_sites()
    This method returns an HTTP::Response object. If the request succeeds, the content of the object will be the known launch sites and their abbreviations in the desired format. If the desired format is 'legacy' or 'json' and the method is called in list context, the second returned item will be a reference to an array containing the parsed data.

    This method takes the following options, specified either command-style or as a hash reference.

    "-format" specifies the desired format of the retrieved data. Possible values are 'xml', 'json', 'html', 'csv', and 'legacy', which is the default. The legacy format is tab-delimited text, such as was returned by the version 1 interface.

    "-json" specifies JSON format. If you specify both "-json" and "-format" you will get an exception unless you specify "-format=json".

    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 = 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->mccants( catalog )
    This method retrieves one of several pieces of data that Mike McCants makes available on his web site. The return is the HTTP::Response object from the retrieval. Valid catalog names are:

     classified: Classified TLE file (classfd.zip)
     integrated: Integrated TLE file (inttles.zip)
     mcnames: Molczan-format magnitude file (mcnames.zip) REMOVED
     quicksat: Quicksat-format magnitude file (qsmag.zip) REMOVED
     vsnames: Molczan-format mags of visual bodies (vsnames.zip) REMOVED

    The files marked REMOVED have been removed from Mike McCants' web site. As of version 0.181, use of the associated arguments is fatal.

    You can specify options as either command-type options (e.g. "mccants( '-file', 'foo.dat', ... )") or as a leading hash reference (e.g. "mccants( { file => 'foo.dat' }, ...)"). 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:

     -file
       specifies the name of the cache file. If the data
       on line are newer than the modification date of
       the cache file, the cache file will be updated.
       Otherwise the data will be returned from the file.
       Either way the content of the file and the content
       of the returned HTTP::Response object end up the
       same.

    On success, the content of the returned object is the actual data, unzipped and with line endings normalized for the current system.

    If this method succeeds, the response will contain headers

     Pragma: spacetrack-type = (see below)
     Pragma: spacetrack-source = mccants

    The content of the spacetrack-type pragma depends on the catalog fetched, as follows:

     classified: 'orbit'
     integrated: 'orbit'

    If the "file" option was passed, the following additional header will be provided:

     Pragma: spacetrack-cache-hit = (either true or false)

    This can be accessed by the cache_hit() method. If this pragma is true, the "Last-Modified" header of the response will contain the modification time of the file.

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

$resp = $st->names (source)
    This method retrieves the names of the catalogs for the given source, either 'celestrak', 'celestrak_supplemental', 'iridium_status', 'mccants', or 'spacetrack', in the content of the given HTTP::Response object. If the argument is not one of the supported values, the $resp object represents a 404 (Not found) error.

    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). If the argument is not one of the supported values, the second return will be "undef".

    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 ('-json', ...)") or as a leading hash reference (e.g. "retrieve ({json => 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.
     -format format_name
       specifies the format in which the data are retrieved.
     -json
       specifies the TLE be returned in JSON format.
     -last5
       Ignored and deprecated.
     -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.

    The "-format" option takes any argument supported by the Space Track interface: "tle", "3le", "json", "csv", "html", or "xml". Specifying "-json" is equivalent to specifying "-format json", and if you specify "-json", specifying "-format" with any other value than 'json' results in an exception being thrown. In addition, you can specify format 'legacy' which is equivalent to 'tle' if the "with_name" attribute is false, or '3le' (but without the leading '0 ' before the common name) if "with_name" is true. The default is 'legacy' unless "-json" is specified.

    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), 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 Boolean options like 'descending' and 'json'. 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 200. 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 'payload', 'debris', 'rocket',
       'unknown', 'tba', or 'other'. If you specify this as a
       command-line option you may either specify this more
       than once or specify the values comma-separated.
     -include
       specifies the types of bodies to include. The possible
       values are the same as for -exclude. If you specify a
       given body as both included and excluded it is included.
     -rcs
       used to specify that the radar cross-section returned
       by the search was to be appended to the name, in the form
       --rcs radar_cross_section. Beginning with version 0.086_02
       it does nothing, since as of August 18 2014 Space Track
       no longer provides quantitative RCS data.
     -status
       specifies the desired status of the returned body (or
       bodies). Must be 'onorbit', 'decayed', or 'all'.  The
       default is 'onorbit'. 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.
     -comment
       specifies that you want the comment field. This will
       not appear in the TLE data, but in the satcat data
       returned in array context, or if C<-notle> is
       specified. The default is C<-nocomment> for backward
       compatibility.

    The "-rcs" option does not work with all values of "-format". An exception will be thrown unless "-format" is 'tle', '3le', 'legacy', or 'json'.

    Examples:

     search_date (-status => 'onorbit', -exclude =>
        'debris,rocket', '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', 'TBA', or 'OTHER'. It works by selecting all values other than the ones specifically excluded. The 'TBA' status was introduced October 1 2013, supposedly replacing 'UNKNOWN', but I have retained both.

    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 in the format specified by the "-format" retrieval option (q.v.). If the format is 'legacy' (the default if "-json" is not specified) the content mimics what was returned under the version 1 interface; that is, it 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.

    The returned object will also have the following headers set if "-notle" is specified:

     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.

    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_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 zeros 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.

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

    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_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 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
       Used to specify that the radar cross-section returned by
       the search is to be appended to the name, in the form
       --rcs radar_cross_section. Starting with version 0.086_02
       it does nothing, since as of August 18 2014 Space Track
       no longer provides quantitative RCS data.
     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'.

    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.

$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->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
        payloads        All payloads
      * navigation      Navigation satellites
      * weather         Weather satellites
        geosynchronous  Geosynchronous bodies
        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
      * bright_geosynchronous
                        Bright Geosynchronous satellites
      * human_spaceflight
                        Human Spaceflight
        well_tracked_objects
                        Well-Tracked Objects not associated
                        with a specific launch

    The starred items are 404 as of 2026-01-19. They are deprecated and will be removed.

    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.

Astro::SpaceTrack->flush_identity_cache();
    The identity file is normally read only once, and the data cached. This static method flushes the cache to force the identity data to be reread.

  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.

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

identity (Boolean)
    If this attribute is set to a true value, the "Astro::SpaceTrack" object will attempt to load attributes from an identity file. This will only do anything if the identity file exists and Config::Identity is installed. In addition, if the identity file is encrypted "gpg2" must be installed and properly configured. See IDENTITY FILE below for details of the identity file.

    I have found that "gpg" does not seem to work nicely, even though Config::Identity prefers it to "gpg2" if both are present. The Config::Identity documentation says that you can override this by setting environment variable "CI_GPG" to the executable you want used.

    If this attribute is unspecified (to new() or specified as "undef" (to new() or set()), the value of environment variable "SPACETRACK_IDENTITY" will be used as the new value.

    When a new object is instantiated, the identity is processed first; in this way attribute values that come from the environment or are specified explicitly override those that come from the identity file. If you explicitly set this on an already-instantiated object, the attribute values from the identity file will replace those in the object.

    When you instantiate an object, the identity from environment variable "SPACETRACK_USER" will be preferred over the value from the identity file, if any, even if the "identity" attribute is explicitly set true.

iridium_status_format (string)
    This attribute specifies the default format of the data returned by the iridium_status() method. Valid values are 'kelso', 'sladen' or 'spacetrack'. See that method for more information.

    As of version 0.100_02, the default is 'kelso'. It used to be 'mccants', but Mike McCants no longer maintains his Iridium status web page, and format 'mccants' was removed as of version 0.137.

    This attribute is deprecated.

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

prompt (string)
    This attribute specifies the prompt issued by the shell() method. The default is 'SpaceTrack> '.

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.org 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 'https://celestrak.org/SpaceTrack/query/iridium.txt'

    This attribute is deprecated.

url_iridium_status_mccants (text)
    This attribute is deprecated, and any access of it will be fatal.

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

    This attribute is deprecated.

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, as follows:

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

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

    * On August 19 2014 Perl's SSL logic stopped accepting Mike McCants' GoDaddy certificate, so starting with version 0.086_02 the default is false once again.

    * On December 11 2014 I noticed that Perl was accepting Mike McCants' certificate again, so starting with version 0.088_01 the default is restored to true.

    If environment variable "SPACETRACK_VERIFY_HOSTNAME" is defined, its value will be used as the default of this attribute. Otherwise 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 metacpan.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.

    As of version 0.105_01, a value of '1' causes Browser::Open to be loaded, and the web command is taken from it. All other true values are deprecated, on the following schedule:

    2018-11-01: First use of deprecated value will warn;
    2019-05-01: All uses of deprecated value will warn;
    2019-11-01: Any use of deprecated value is fatal;
    2020-05-01: Attribute is treated as Boolean.

    The above schedule may be extended based on what other changes are needed, but will not be compressed.

    The default is "undef", which leaves the functionality disabled.

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). This attribute may be ignored; see the individual method for details.

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

IDENTITY FILE
This is a Config::Identity file which specifies the username and password values for the user. This file is stored in the user's home directory, and is spacetrack.id under "MSWin32" or "VMS", or .spacetrack-identity under any other operating system.

If desired, the file can be encrypted using GPG; in this case, to be useful, "gpg" and "gpg-agent" must be installed and properly configured. Because of implementation details in Config::Identity, you may need to either ensure that "gpg" is not in your "PATH", or set the "CI_GPG" environment variable to the path to "gpg2". The encrypted file can optionally have ".gpg" appended to its name for the convenience of users of the vim-gnupg plugin and similar software. If the identity file exists both with and without the ".gpg" suffix, the suffixed version will be used.

Note that this file is normally read only once during the life of the Perl process, and the result cached. The username and password that are set when "identity" becomes true come from the cache. If you want a running script to see new identity file information you must call static method flush_identity_cache().

GLOBALS
The following globals modify the behaviour of this class. If you modify their values, your modifications should be properly localized. For example:

 {
     local $SPACETRACK_DELAY_SECONDS = 42;
     $rslt = $st->search_name( 'iss' );
 }

  $SPACETRACK_DELAY_SECONDS
This global holds the delay in seconds between queries. It defaults to 3 (or the value of environment variable "SPACETRACK_DELAY_SECONDS" if that is true), and should probably not be messed with. But if Space Track is being persnickety about timing you can set it to a larger number. This variable must be set to a number. If Time::HiRes is not available this number must be an integer.

This global is not exported. You must refer to it as $Astro::SpaceTrack::SPACETRACK_DELAY_SECONDS.

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

  SPACETRACK_DELAY_SECONDS
This environment variable should be set to a positive number to change the default delay between Space Track queries. This is "not" something you should normally need to do. If Time::HiRes is not available this number must be an integer.

This environment variable is only used to initialize $SPACETRACK_DELAY_SECONDS. If you wish to change the delay you must assign to the global.

  SPACETRACK_IDENTITY
This environment variable specifies the default value for the identity attribute any time an undefined value for that attribute is specified.

  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_TEST_LIVE
If environment variable "SPACETRACK_TEST_LIVE" is defined to a true value (in the Perl sense), tests that use the Space Track web site will actually access it. Otherwise they will either use canned data (i.e. a regression test) or be skipped.

  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_VERIFY_HOSTNAME
As of version 0.086_02, if environment variable "SPACETRACK_VERIFY_HOSTNAME" is defined at the time an "Astro::SpaceTrack" object is instantiated, its value will be used for the default value of the "verify_hostname" attribute.

  SPACETRACK_SKIP_OPTION_HASH_VALIDATION
As of version 0.081_01, method options passed as a hash reference will be validated. Before this, only command-line-style options were validated. If the validation causes problem, set this environment variable to a value Perl sees as true (i.e. anything but 0 or '') to revert to the old behavior.

Support for this environment variable will be put through a deprecation cycle and removed once the validation code is deemed solid.

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.

Support is by the author. Please file bug reports at <https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-SpaceTrack>, <https://github.com/trwyant/perl-Astro-SpaceTrack/issues/>, or in electronic mail to the author.

MODIFICATIONS OF HISTORICAL INTEREST

  Data Throttling
Space Track announced August 19 2013 that beginning September 22 they would limit users to less than 20 API queries per minute. Experience seems to say they jumped the gun - at least, server errors during testing were turned into success by throttling queries to one every three seconds.

The throttling functionality will make use of Time::HiRes if it is available; otherwise it will simply use the built-in sleep() and time(), with consequent loss of precision.

Unfortunately this makes testing slower. Sorry.

  Quantitative RCS Data
On July 21 2014 Space Track announced the plan to remove quantitative RCS data (the "RCSVALUE" field), replacing it with a qualitative field ("RCS_SIZE", values 'SMALL' (< 0.1 square meter), 'MEDIUM', (>= 0.1 square meter but < 1 square meter), 'LARGE' (> 1 square meter), and of course, null.

This removal took place August 18 2014. Beginning with version 0.086_02, any RCS functionality specific to the Space Track web site "RCSVALUE" datum (such as the "-rcs" search option) has been removed. The "-rcs" option itself will be put through a deprecation cycle, with the first release on or after March 1 2015 generating a warning on the first use, the first release six months later generating a warning on every use, and the warning becoming fatal six months after that.

On the other hand, the "RCSVALUE" and "RCS_SIZE" data will continue to be returned in such ways and places that the Space Track web site itself returns them.

ACKNOWLEDGMENTS
The author wishes to thank Dr. T. S. Kelso of <https://celestrak.org/> and the staff of <https://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
Copyright 2005-2026 by Thomas R. Wyant, III (wyant at cpan dot org).

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 files LICENSE-Artistic and LICENSE-GPL.

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 (<https://www.space-track.org/documentation#/user_agree>).