Astro-SpaceTrack
view release on metacpan or search on metacpan
lib/Astro/SpaceTrack.pm view on Meta::CPAN
=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
The Celestrak web site, L<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 C<celestrak()>
and C<celestrak_supplemental()> methods will track this, growing new
arguments as needed.
=head2 DEPRECATION NOTICE: IRIDIUM STATUS
As of version 0.137, Iridium status format C<'mccants'> is fully
deprecated, and will result in an exception.
As of version 0.143, any access of attribute
C<url_iridium_status_mccants> is fatal.
As of version 0.169, any use of attribute C<url_iridium_status_kelso> is
fatal.
As of version 0.181, B<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.
=head1 DESCRIPTION
This package retrieves orbital data from the Space Track web site
L<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 (C<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
lib/Astro/SpaceTrack.pm view on Meta::CPAN
name => 'Planet (no, not Mercury etc)',
# source => 'Planet-E',
rms => 1,
match => 1,
},
# Removed 2024-04-26
# Added back 2024-05-23
ses => {
name => 'SES',
# source => 'SES-11P',
rms => 1,
match => 1,
},
starlink => {
name => 'Starlink',
# source => 'SpaceX-E',
rms => 1,
match => 1,
},
telesat => {
name => 'Telesat',
# source => 'Telesat-E',
rms => 1,
match => 1,
},
},
iridium_status => {
kelso => {name => 'Celestrak (Kelso)'},
mccants => {name => 'McCants'},
sladen => {name => 'Sladen'},
spacetrack => { name => 'SpaceTrack' },
},
mccants => {
classified => {
name => 'Classified TLE file',
member => undef, # classfd.tle
spacetrack_type => 'orbit',
url => 'https://www.mmccants.org/tles/classfd.zip',
},
integrated => {
name => 'Integrated TLE file',
member => undef, # inttles.tle
spacetrack_type => 'orbit',
url => 'https://www.mmccants.org/tles/inttles.zip',
},
mcnames => {
name => 'Molczan-format magnitude file',
member => undef, # mcnames
spacetrack_type => 'molczan',
url => 'https://www.mmccants.org/tles/mcnames.zip',
},
# Removed 2025-12-15 or thereabouts
quicksat => {
name => 'Quicksat-format magnitude file',
member => undef, # qs.mag
spacetrack_type => 'quicksat',
url => 'https://www.mmccants.org/programs/qsmag.zip',
},
# Removed 2024-12-29.
#rcs => {
# name => 'McCants-format RCS data (404 2024-04-27)',
# member => undef, # rcs
# spacetrack_type => 'rcs.mccants',
# url => 'https://www.mmccants.org/catalogs/rcs.zip',
#},
vsnames => {
name => 'Molczan-format magnitude file (visual only)',
member => undef, # vsnames
spacetrack_type => 'molczan',
url => 'https://www.mmccants.org/tles/vsnames.zip',
},
},
spacetrack => [ # Numbered by space_track_version
undef, # No interface version 0
undef, # No interface version 1 any more
{ # Interface version 2 (REST)
# On Space Track "Recent ELSETs" tab
full => {
name => 'Full catalog',
# As of 2026-01-19
# https://www.space-track.org/basicspacedata/query/class/gp/EPOCH/%3Enow-30/orderby/NORAD_CAT_ID,EPOCH/format/3le
# We have to go through satcat to eliminate bodies that
# are not on orbit, since tle_latest includes bodies
# decayed in the last two years or so
# satcat => {},
tle => {
EPOCH => '>now-30',
},
# number => 1,
},
geosynchronous => { # GEO
name => 'Geosynchronous satellites',
# As of 2026-01-19
# https://www.space-track.org/basicspacedata/query/class/gp/EPOCH/%3Enow-30/MEAN_MOTION/0.99--1.01/ECCENTRICITY/%3C0.01/OBJECT_TYPE/payload/orderby/NORAD_CAT_ID,EPOCH/format/3le
# number => 3,
# We have to go through satcat to eliminate bodies that
# are not on orbit, since tle_latest includes bodies
# decayed in the last two years or so
# satcat => {
# PERIOD => '1425.6--1454.4'
# },
# Note that the v2 interface specimen query is
# PERIOD 1430--1450.
# The v1 definition is
# MEAN_MOTION 0.99--1.01
# ECCENTRICITY <0.01
# tle => {
# ECCENTRICITY => '<0.01',
## MEAN_MOTION => '0.99--1.01',
# },
tle => {
ECCENTRICITY => '<0.01',
EPOCH => '>now-30',
MEAN_MOTION => '0.99--1.01',
OBJECT_TYPE => 'payload',
},
},
medium_earth_orbit => { # MEO
name => 'Medium Earth Orbit',
# As of 2026-01-19
lib/Astro/SpaceTrack.pm view on Meta::CPAN
Pragma: spacetrack-source = mccants
The content of the spacetrack-type pragma depends on the catalog
fetched, as follows:
classified: 'orbit'
integrated: 'orbit'
If the C<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 C<cache_hit()> method. If this pragma is
true, the C<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.
=cut
# Called dynamically
sub _mccants_opts { ## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
return [
'file=s' => 'Name of cache file',
];
}
sub mccants {
my ( $self, @args ) = @_;
( my $opt, @args ) = _parse_args( @args );
return $self->_get_from_net(
%{ $opt },
catalog => $args[0],
post_process => sub {
my ( undef, $resp, $info ) = @_; # Invocant unused
my ( $content, @zip_opt );
defined $info->{member}
and push @zip_opt, Name => $info->{member};
IO::Uncompress::Unzip::unzip( \( $resp->content() ),
\$content, @zip_opt )
or return HTTP::Response->new(
HTTP_NOT_FOUND,
$IO::Uncompress::Unzip::UnzipError );
$resp->content( $content );
return $resp;
},
);
}
=for html <a name="names"></a>
=item $resp = $st->names (source)
This method retrieves the names of the catalogs for the given source,
either C<'celestrak'>, C<'celestrak_supplemental'>, C<'iridium_status'>,
C<'mccants'>, or C<'spacetrack'>, in the content of
the given HTTP::Response object. If the argument is not one of the
supported values, the C<$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
C<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.
=cut
sub names {
my ( $self, $name ) = @_;
delete $self->{_pragmata};
my $src = $self->__catalog( $name )
or return HTTP::Response->new(
HTTP_NOT_FOUND, "Data source '$name' not found.");
my @list;
foreach my $cat (sort keys %$src) {
push @list, defined ($src->{$cat}{number}) ?
"$cat ($src->{$cat}{number}): $src->{$cat}{name}\n" :
"$cat: $src->{$cat}{name}\n";
defined $src->{$cat}{note}
and $list[-1] .= " $src->{$cat}{note}\n";
}
my $resp = HTTP::Response->new (HTTP_OK, undef, undef, join ('', @list));
return $resp unless wantarray;
@list = ();
foreach my $cat (sort {$src->{$a}{name} cmp $src->{$b}{name}}
keys %$src) {
push @list, [$src->{$cat}{name}, $cat];
defined $src->{$cat}{note}
and push @{ $list[-1] }, $src->{$cat}{note};
}
return ($resp, \@list);
}
=for html <a name="retrieve"></a>
=item $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 C<< $st->content_type( $resp ) >> and
C<< $st->content_source( $resp ) >> respectively.
lib/Astro/SpaceTrack.pm view on Meta::CPAN
$readline::rl_completion_function = sub {
my ( $text, $line, $start ) = @_;
return $self->__readline_completer(
$text, $line, $start );
};
}
return sub { $rdln->readline ( $self->getv( 'prompt' ) ) };
}
=for html <a name="source"></a>
=item $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.
=cut
# We really just delegate to _source, which unpacks.
sub source {
my $self = _instance( $_[0], __PACKAGE__ ) ? shift :
Astro::SpaceTrack->new ();
$self->shell ($self->_source (@_), 'exit');
return;
}
=for html <a name="spacetrack"></a>
=item $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 C<< spacetrack( '-json', ... ) >>) or as a hash reference
(that is, as C<< spacetrack( { json => 1 }, ... ) >>).
This method returns an L<HTTP::Response|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
C<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 C<< $st->content_type( $resp ) >> and
C<< $st->content_source( $resp ) >> respectively.
A list of valid names and brief descriptions can be obtained by calling
C<< $st->names ('spacetrack') >>.
If you have set the C<verbose> attribute true (e.g. C<< $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 C<login()> method if the session cookie
is missing or expired. If C<login()> fails, you will get the
HTTP::Response from C<login()>.
=cut
{
my %unpack_query = (
ARRAY_REF() => sub { return @{ $_[0] } },
HASH_REF() => sub { return $_[0] },
);
# Unpack a Space Track REST query. References are unpacked per the
# above table, if found there. Undefined values return an empty hash
# reference. Anything else croaks with a stack trace.
sub _unpack_query {
my ( $arg ) = @_;
my $code = $unpack_query{ref $arg}
or Carp::confess "Bug - unexpected query $arg";
return $code->( $arg );
}
}
# Called dynamically
sub _spacetrack_opts { ## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
return [
'json!' => 'Return data in JSON format',
'format=s' => 'Specify retrieval format',
];
}
# Called dynamically
sub _spacetrack_catalog_version { ## no critic (Subroutines::ProhibitUnusedPrivateSubroutines)
return $_[0]->getv( 'space_track_version' );
}
sub spacetrack {
( run in 0.793 second using v1.01-cache-2.11-cpan-39bf76dae61 )