++ed by:
Author image Tom Wyant
and 1 contributors


passes - Compute satellite rise and set times


 passes -user yehudi -pass menuhin -lat 42 -lon -90 25544=ISS
 passes -file driver.txt
 passes -help
 passes -version


This Perl script downloads TLE data for specified satellites from the Space Track web site, and uses these data to predict passes of the satellites over the observer during the desired period of time. Output is normally chronological by culmination time. If -split is specified, output is chronological by individual event time. Location- and user-specific options such as observing location and Space Track account information can be specified in a configuration file.

The configuration of this script consists of "OPTIONS" (documented below) and the OID numbers to be displayed. You can override Space Track's common name for the object by suffixing =your_desired_name to the OID. An example of this occurs in the "SYNOPSIS".

By default, output is one line per pass. You can get an event per line by specifying the -split option.

By default, the reporting period is the seven days beginning at midnight on the current day. You can change this using the -start and -finish options.

Output is controlled by a templating system. In general the output line consists of satellite-specific data followed by event-specific data. The satellite-specific data are specified by the -body-template option. The event-specific data are specified by the -event-template option. Time formats (for strftime(3)) are set using the -time-format option. The string used to separate multiple events on the same line is specified by the -join option.


Several options are available. Option names may be abbreviated down to the shortest unique abbreviation, but the shortest abbreviation may change if new options are added.

Not all the options are in fact optional. Some of them specify information this script needs to run. You must provide values for options -username and -password to obtain satellite information, and -latitude and -longitude to provide the location of the observer. You may wish to provide the -height for the observer as well. You need not specify these if you specify -help or -version, since both cause the script to exit after they are encountered.

Other options may be of particular interest. To change the reporting period, use -start and -finish. To report only passes which can actually be seen from the ground, use -visible. To report rises and sets separately, use -split.

-body-template template_string

This option specifies the template used to insert information about the satellite into the output. The templating system is described under the -event-template option, below.

The %a (azimuth) and %e (elevation) specifications do nothing useful in a -body-template.

The default is '%N%t' (i.e. the name of the satellite, followed by a horizontal tab).

-event-template output_template

This option specifies the template used to insert information about an individual pass event into the output.

All characters in the template are output verbatim, except for the '%', which is magic. Data from the event are substituted into the output according to the character that follows the '%', as follows:

 a - azimuth of event in degrees from north;
 e - elevation of event in degrees above geometric horizon;
 i - international launch designator of satellite;
 l - illumination (lit or not, PASS_EVENT_* numeric code,
     undefined in -body-template);
 L - illumination (string, if available, undefined in
 n - a literal newline;
 N - name of satellite;
 o - OID (SATCAT ID) of satellite;
 t - a literal horizontal tab;
 T - event time (or culmination time in -body-template);
 u - number of satellites up after event (undefined if
     -split is not asserted);
 v - event (Astro::Coord::ECI::TLE PASS_EVENT_* numeric code);
 V - event (string, if available from Astro::Coord::ECI::TLE);
 % - a literal '%'.

The behavior when any other character follows the '%' is undefined. The word 'undefined' does not mean that you get a literal undef under those circumstances. It means that the behavior (whatever it is) may not be what you expect or want, and that it may change without notice.

All times are formatted according to the value of the -time-format option.

The default template is '%V %L %T' (that is, the name of the event, whether the satellite is lit or shadowed, and the time of the event).

-finish iso_time_or_days

This option specifies the finish time. It is either an ISO-8601-ish string such as is legal for -start, or a plus sign followed by an integer, which is the number of days after the -start time.

The default is '+7'.


This option specifies that rise and set take place when the satellite crosses the geometric horizon, regardless of the setting of the -horizon option. If not asserted, rise and set take place when the satellite crosses the elevation specified by the -horizon option.

This option can be negated by specifying -nogeometric.

The default is -nogeometric


This option specifies that times be either GMT (if asserted) or local (if negated). It can be negated by specifying -nogmt.

The default is -nogmt.

-height meters_above_geoid

This option specifies the observer's height in meters above the WGS84 geoid.

The default is 0.

-horizon degrees_of_elevation

This option specifies the effective horizon in degrees above (or below, if negative) the geometric horizon.

The default is 0.

-join joining_string

This option specifies the string to be inserted between events in the output. This string is run through the templating system before use, but the only supported characters after a percent sign are 't' to insert a horizontal tab, 'n' to insert a newline, and '%' to insert a literal percent sign. The results of using any other character after a percent sign are undefined.

The default is '%n%t' (that is, a newline followed by a horizontal tab).

-latitude degrees_north_of_equator

This option specifies the observer's latitude in degrees. South latitudes are negative.

This option must be specified. There is no default.

-longitude degrees_east_of_prime_meridian

This option specifies the observer's longitude in degrees east of Greenwich England. West longitudes are negative.

This option must be specified. There is no default.

-password spacetrack_password

This option specifies the Space Track password.

This option must be specified. There is no default.


This option reports individual events of a pass separately. This may be more useful for telling how many satellites are above the horizon at a given time. If negated (which is the default, and which can be specified explicitly by -nosplit) you get all events for the pass on the same line.

The default is -noevent.

-start iso_time

This option specifies the start time as an ISO-8601-ish time. Only the year-month-day-hour-minute-second version of the specification is implemented. Years must be 4 digits, and all other fields must be two digits. Trailing fields can be omitted, and default to 00 or 01 as appropriate. Non-numeric characters may appear between fields, and after the final field. So, for example,

 -start 2010-04-01:00:00:00

specifies a start at midnight of April 1 2010. In fact, so does

 -start 201004

As a convenience, the date portion can be replaced by one of the strings yesterday, today, or tomorrow. So data starting today at noon can be specified as

 -start today12

The default is 'today', meaning midnight, since all the time fields default to 0.


If asserted, this option causes each event of the pass to be reported on a separate line of output.

The default is -nosplit.

-time-format strftime_format

This option sets the strftime(3) format used to format the time in the output.

The default is '%d-%b-%Y %H:%M:%S' (that is, day, month name, four-digit year, hour, minute, second).

-twilight degrees_below_horizon

This options sets the number of degrees the Sun is below the horizon at the beginning or end of twilight. Unlike the satpass script, you must specify a number.

The default is 6, which corresponds to civil twilight.

-username spacetrack_username

This option specifies the Space Track user name.

This option must be specified. There is no default.


If asserted, this option causes only visible passes to be reported. A pass is considered visible if the satellite is sunlit and the observer is in darkness during some portion of the pass. The rise or set may actually not be visible.

This option can be negated by specifying -novisible.

The default is -novisible.

-want-events event_types

This option specifies what pass events are wanted in the output. The value is a string composed of one or more individual event type codes, as follows:

 r = rise and set;
 m = maximum elevation (culmination);
 l = illumination (passing into sunlight or shadow);
 t = beginning or end of twilight;
 b = brightest.

The default is 'rmltb'.


Configuration for this script can be done by a file as well as on the command line. Configuration information is taken in the following order:

1) The default configuration file, if any.
2) The file specified by the -file command option, if any.
3) The command line.

In the case of command options, the last-specified value of a given option is the one used. Boolean options (e.g. -gmt) can be negated by prefixing 'no' (e.g. -nogmt).

The lists of OIDs from the above sources are simply concatenated.

Blank lines and lines beginning with '#' are ignored in configuration files, as are leading and trailing whitespace on a line. Each non-blank non-comment line in a configuration file goes to make up a single token in a command line that is built internally and parsed.

This means that each option must be specified on a line by itself, as must each OID. If an option takes a value, that value must either be joined to the option name by an equals sign, or appear on the next line.

An example configuration file might look like this:

 # Observing location:
 # Elysee Palace, Rue Faubourg Saint-Honore, Paris
 # Space Track login

The name and location of the default configuration file depend on the host operating system.

For Darwin (Mac OS X) the default configuration file is the first found of $HOME/Library/Application Support/passes.ini or $HOME/.risesetrc.

For MSWin32 the default configuration file is %APPDATA%/passes.ini.

For VMS the default configuration file is SYS$LOGIN:passes.ini.

For any other operating system, the default configuration file is $HOME/.risesetrc.


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


Thomas R. Wyant, III (wyant at cpan dot org)


Copyright (C) 2010-2021 by Thomas R. Wyant, III

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

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