Astro-SpaceTrack
view release on metacpan or search on metacpan
lib/Astro/SpaceTrack.pm view on Meta::CPAN
=head1 NAME
Astro::SpaceTrack - Retrieve orbital data from www.space-track.org.
=head1 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 L<Config::Identity|Config::Identity>, created an
L<IDENTITY FILE|/IDENTITY FILE> (see below) containing these values, and
set the C<identity> attribute to a true value. You probably
want to encrypt the identity file, if you have C<gpg2> and C<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.
=head1 CAVEAT
Version 0.180 was an emergency release of this module. It was caused by Space
Track deprecating and ultimately revoking the C<'tle_latest'> and
C<'tle'> data classes in favor of C<'gp'> and C<'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:
=over
=item 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 (C<ORDINAL>) that
Space Track no longer provides.
=item The C<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. C<NORAD_CAT_ID> has the same value.
=item Favorites do not work
In the previous release C<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 C<favorite()> method.
=back
=head1 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
L<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.
=head1 FUNCTIONAL NOTICES
=head2 CELESTRAK API
lib/Astro/SpaceTrack.pm view on Meta::CPAN
( my $msg = $resp->message() ) =~
s{ ( [(] \Qcertificate verify failed\E ) [)]}
{$1; try setting the verify_hostname attribute false)}smx
or return $resp;
$resp->message( $msg );
return $resp;
}
# _mutate_attrib takes the name of an attribute and the new value
# for the attribute, and does what its name says.
# We supress Perl::Critic because we're a one-liner. CAVEAT: we MUST
# not modify the contents of @_. Modifying @_ itself is fine.
sub _mutate_attrib {
$_[0]->_deprecation_notice( attribute => $_[1] );
return ($_[0]{$_[1]} = $_[2]);
}
sub _mutate_dump_headers {
my ( $self, $name, $value, $args ) = @_;
if ( $value =~ m/ \A --? /smx ) {
$value = 0;
my $go = Getopt::Long::Parser->new();
$go->configure( qw{ require_order } );
$go->getoptionsfromarray(
$args,
map {; "$_!" => sub {
$_[1] and do {
my $method = "DUMP_\U$_[0]";
$value |= $self->$method();
};
return;
}
} @dump_options
);
push @{ $args }, $value; # Since caller pops it.
} else {
$value =~ m/ \A 0 (?: [0-7]+ | x [[:xdigit:]]+ ) \z /smx
and $value = oct $value;
}
return ( $self->{$name} = $value );
}
{
my %id_file_name = (
MSWin32 => sub {
my $home = $ENV{HOME} || $ENV{USERPROFILE} || join '',
$ENV{HOMEDRIVE}, $ENV{HOMEPATH};
return "$home\\spacetrack.id";
},
VMS => sub {
my $home = $ENV{HOME} || 'sys$login';
return "$home:spacetrack.id";
},
);
sub __identity_file_name {
my $id_file = ( $id_file_name{$^O} || sub {
return join '/', $ENV{HOME}, '.spacetrack-identity' }
)->();
my $gpg_file = "$id_file.gpg";
-e $gpg_file
and return $gpg_file;
return $id_file;
}
}
# This basically duplicates the logic in Config::Identity
sub __identity_file_is_encrypted {
my $fn = __identity_file_name();
-B $fn
and return 1;
open my $fh, '<:encoding(utf-8)', $fn
or return;
local $/ = undef;
my $content = <$fh>;
close $fh;
return $content =~ m/ \Q----BEGIN PGP MESSAGE----\E /smx;
}
sub _mutate_identity {
my ( $self, $name, $value ) = @_;
defined $value
or $value = $ENV{SPACETRACK_IDENTITY};
if ( $value and my $identity = __spacetrack_identity() ) {
$self->set( %{ $identity } );
}
return ( $self->{$name} = $value );
}
=for html <a name="flush_identity_cache"></a>
=item 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.
=cut
{
my $identity;
my $loaded;
sub flush_identity_cache {
$identity = $loaded = undef;
return;
}
sub __spacetrack_identity {
$loaded
and return $identity;
$loaded = 1;
my $fn = __identity_file_name();
-f $fn
or return $identity;
{
local $@ = undef;
eval {
require Config::Identity;
$identity = { Config::Identity->load( $fn ) };
1;
} or return;
lib/Astro/SpaceTrack.pm view on Meta::CPAN
=over
=item addendum (text)
This attribute specifies text to add to the output of the banner()
method.
The default is an empty string.
=item 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).
=item 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.
=item 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.
=item 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 C<'www.space-track.org'>. This will change if necessary
to remain appropriate to the Space Track web site.
=item 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).
=item 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).
=item identity (Boolean)
If this attribute is set to a true value, the C<Astro::SpaceTrack>
object will attempt to load attributes from an identity file. This will
only do anything if the identity file exists and
L<Config::Identity|Config::Identity> is installed. In addition, if the
identity file is encrypted C<gpg2> must be installed and properly
configured. See L<IDENTITY FILE|/IDENTITY FILE> below for details of the
identity file.
I have found that C<gpg> does not seem to work nicely, even though
L<Config::Identity|Config::Identity> prefers it to C<gpg2> if both are
present. The L<Config::Identity|Config::Identity> documentation says
that you can override this by setting environment variable C<CI_GPG>
to the executable you want used.
If this attribute is unspecified (to C<new()> or specified as C<undef>
(to C<new()> or C<set()>), the value of environment variable
C<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
C<SPACETRACK_USER> will be preferred over the value from the identity
file, if any, even if the C<identity> attribute is explicitly set true.
=item iridium_status_format (string)
This attribute specifies the default format of the data returned by the
C<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 C<'kelso'>. It used to be
C<'mccants'>, but Mike McCants no longer maintains his Iridium status
web page, and format C<'mccants'> was removed as of version 0.137.
This attribute is B<deprecated>.
=item 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.
=item password (text)
This attribute specifies the Space-Track password.
The default is an empty string.
=item pretty (Boolean)
This attribute specifies whether the content of the returned
L<HTTP::Response|HTTP::Response> is to be pretty-formatted. Currently
this only applies to Space Track data returned in C<JSON> format.
Pretty-formatting the C<JSON> is extra overhead, so unless you intend to
read the C<JSON> yourself this should probably be false.
The default is C<0> (i.e. false).
=item prompt (string)
This attribute specifies the prompt issued by the C<shell()> method. The
default is C<< 'SpaceTrack> ' >>.
=item scheme_space_track (string)
lib/Astro/SpaceTrack.pm view on Meta::CPAN
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 C<SPACETRACK_VERIFY_HOSTNAME> is defined, its
value will be used as the default of this attribute. Otherwise the
default is false (i.e. 0).
=item 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 C<'1'> causes
L<Browser::Open|Browser::Open> to be loaded, and the web command is
taken from it. All other true values are deprecated, on the following
schedule:
=over
=item 2018-11-01: First use of deprecated value will warn;
=item 2019-05-01: All uses of deprecated value will warn;
=item 2019-11-01: Any use of deprecated value is fatal;
=item 2020-05-01: Attribute is treated as Boolean.
=back
The above schedule may be extended based on what other changes are
needed, but will not be compressed.
The default is C<undef>, which leaves the functionality disabled.
=item 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).
=back
=head1 IDENTITY FILE
This is a L<Config::Identity|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 F<spacetrack.id> under C<MSWin32> or
C<VMS>, or F<.spacetrack-identity> under any other operating system.
If desired, the file can be encrypted using GPG; in this case, to be
useful, C<gpg> and C<gpg-agent> must be installed and properly
configured. Because of implementation details in
L<Config::Identity|Config::Identity>, you may need to either ensure that
C<gpg> is not in your C<PATH>, or set the C<CI_GPG> environment variable
to the path to C<gpg2>. The encrypted file can optionally have C<.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 C<.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 C<identity> becomes true come from the cache. If you want a
running script to see new identity file information you must call static
method C<flush_identity_cache()>.
=head1 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' );
}
=head2 $SPACETRACK_DELAY_SECONDS
This global holds the delay in seconds between queries. It defaults to 3
(or the value of environment variable C<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
L<Time::HiRes|Time::HiRes> is not available this number must be an
integer.
This global is not exported. You must refer to it as
C<$Astro::SpaceTrack::SPACETRACK_DELAY_SECONDS>.
=head1 ENVIRONMENT
The following environment variables are recognized by Astro::SpaceTrack.
=head2 SPACETRACK_DELAY_SECONDS
This environment variable should be set to a positive number to change
the default delay between Space Track queries. This is C<not> something
you should normally need to do. If L<Time::HiRes|Time::HiRes> is not
available this number must be an integer.
This environment variable is only used to initialize
C<$SPACETRACK_DELAY_SECONDS>. If you wish to change the delay you must
assign to the global.
=head2 SPACETRACK_IDENTITY
This environment variable specifies the default value for the identity
attribute any time an undefined value for that attribute is specified.
=head2 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.
( run in 0.516 second using v1.01-cache-2.11-cpan-df04353d9ac )