occultations

Predicts lunar occultations — the Moon passing in front of a planet or bright star — for a given location and date, draws maps and Google Earth files of where on Earth an occultation can be seen, ana forecasts the occultations visible from a location over the coming months.

Positions come from Skyfield using the JPL DE421 ephemeris, computed topocentrically (as seen from the observer's spot on Earth, not Earth's center).

Installation

Requires Python 3.11+ and uv.

uv sync

Data files are stored in /var/data (the directory must exist and be writable):

• de421.bsp — JPL ephemeris (~17 MB), downloaded on first run
• cartopy/ — Natural Earth coastlines, borders and ocean names, downloaded the first time a map is drawn or a region is named

Usage

occultations [TARGET] DATE [LOCATION] [options]    # timing for one date, optional map
occultations forecast LOCATION [options]           # upcoming visible occultations

Argument	Description
TARGET	A planet (mercury … pluto), a bright star (see below), or coordinates as "RA_hours,Dec_deg". Optional: without it, every built-in planet and star the Moon occults somewhere on Earth on DATE is reported (and mapped), one after another
DATE	YYYY-MM-DD — the local date at LOCATION, or the UTC date when only mapping
LOCATION	"City, ST" (looked up via OpenStreetMap) or "lat,lon" in decimal degrees, west negative. Optional when --map is given

Built-in stars: Aldebaran, Alcyone (Pleiades), Antares, Elnath, Mebsuta, Nunki, Pollux, Regulus, Spica, Zubenelgenubi.

Timing options

Option	Description
--elevation M	Observer elevation in meters (defaults to the geocoder's value, or 0)
--timezone TZ	Override the IANA time zone (normally derived from the coordinates)
--prev-next	Also show the date and target of the previous and next occultation visible from LOCATION, of any built-in planet or star (searches up to 20 years each way)
--planets-only	With --prev-next, consider only planets

Map and Google Earth options

Option	Description
--map [PATH]	Also draw a visibility map as a PNG. Without PATH it is named occultation_<target>_<date>[_<region>].png in the current directory. A second, clean copy with no title, legend or labels is written alongside it as <name>_clean.png
--region NAME	Limit the map to a preset: north-america, conus, europe, africa
--extent W E S N	Limit the map to a longitude/latitude box (degrees, west/south negative)
--resolution DEG	Map grid spacing in degrees (default 0.25; smaller is slower)
--kmz [PATH]	Also write a Google Earth file (KMZ). Without PATH it is named occultation_<target>_<date>[_<region>].kmz

When TARGET is omitted and more than one occultation happens that day, the target is added to a given PATH (e.g. map.png → map_mars.png and map_jupiter.png). | --mark-location | Put a marker at LOCATION on the map / in the KMZ |

--region, --extent, --resolution and --mark-location apply to both --map and --kmz; use both flags together to get a PNG and a KMZ from one calculation. Without --region or --extent, the area is chosen automatically around where the event is visible.

Note: --map and --kmz take an optional path, so put them after LOCATION (or give them a path). occultations jupiter 2026-10-06 --map "Raleigh, NC" would treat "Raleigh, NC" as the filename.

Forecast options

occultations forecast LOCATION searches a span of dates for every occultation of the built-in planets and stars, listing first those that can actually be seen from LOCATION, then those happening elsewhere on Earth that can't.

Option	Description
--start DATE	First local date to search (default today)
--days N	Number of days to search (default 365)
--end DATE	Last local date to search, instead of --days
--targets T [T ...]	Only these targets (default: all planets and built-in stars)
--planets-only	Only planets, no stars (cannot be combined with --targets)
--include-daylight	Also list events of bright planets (Mercury–Saturn) with the Sun up or in civil twilight
--elevation M, --timezone TZ	As for timing

An occultation counts as visible when its disappearance or reappearance happens with the Moon above the horizon and the Sun at least 6° below it (or, with --include-daylight, at any Sun altitude for bright planets).

Examples

Contact times for Jupiter from Raleigh:

uv run occultations jupiter 2026-10-06 "Raleigh, NC"

Lunar occultation of Jupiter
Location: Raleigh, NC (35.7804°, -78.6391°), 0 m
Date:     2026-10-06 (America/New_York)
Moon:     20% illuminated, radius 16.05'; Jupiter radius 16.8"

Event                                Local time  UTC     Moon alt/az         PA  Sky
----------------------------------------------------------------------------------------------------
Disappearance begins (1st contact)   04:18 EDT  08:18    15.2° E    82°   113°  dark
Fully hidden (2nd contact)           04:19 EDT  08:19    15.4° E    82°   113°  dark
Reappearance begins (3rd contact)    05:21 EDT  09:21    27.6° E    91°   288°  dark
Reappearance ends (4th contact)      05:23 EDT  09:23    27.9° E    91°   288°  dark

Duration (first to last contact): 65 min

Without a target, whatever the Moon occults that day (here Jupiter, and Regulus later that evening, which isn't visible from Raleigh):

uv run occultations 2026-10-06 "Raleigh, NC"

Using coordinates instead of a city:

uv run occultations jupiter 2026-10-06 "35.78,-78.64"

Contact times plus a North America visibility map:

uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --map

Map only, framed automatically, saved to a chosen path:

uv run occultations jupiter 2026-10-06 --map jupiter.png

Google Earth file of the whole visibility path (open it in Google Earth or Google Earth Web):

uv run occultations jupiter 2026-10-06 --kmz

PNG map and KMZ together, with the observer marked:

uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --mark-location --map --kmz

Map of a custom area with the observer marked:

uv run occultations jupiter 2026-10-06 "Raleigh, NC" --extent -95 -65 25 45 --mark-location --map

Visible occultations from Raleigh over the next year:

uv run occultations forecast "Raleigh, NC" --start 2026-10-01

Lunar occultations from Raleigh, NC (35.7804°, -78.6391°)
2026-10-01 to 2027-09-30, times in America/New_York

Date            Target         Disappears                                           Reappears                                            Moon
----------------------------------------------------------------------------------------------------------------------------------------------
Tue 2026-10-06 Jupiter        04:18   15° E   dark                  bright limb    05:23   28° E   dark                  dark limb       20%
Sun 2027-06-20 Nunki          03:21   26° SSW dark                  bright limb    04:07   23° SSW dark                  dark limb       98%

Altitude and compass direction are the Moon's. Planet times are first and last contact.

Occurring elsewhere on Earth, not visible from here
Date            Target         Time   Why not                              Moon   Visible from
----------------------------------------------------------------------------------------------------------------------
Fri 2026-10-02 Elnath         03:59  path misses this location             64%   South America
Mon 2026-10-05 Mars           02:12  path misses this location             31%   northern Canada, Russian Far East, Alaska
Tue 2026-10-06 Regulus        23:08  path misses this location             14%   Eastern Africa, Middle Africa, Southern Africa
...
Fri 2026-12-11 Nunki          00:12  Moon below horizon                     4%   North Pacific Ocean
...

Only Jupiter and Regulus over the rest of the year, including daytime events:

uv run occultations forecast "Raleigh, NC" --end 2026-12-31 --targets jupiter regulus --include-daylight

Reading the output

Timing table

• Planets show four contacts, since they have a visible disk; stars disappear and reappear instantly, so they show a single disappearance and reappearance.
• Moon alt/az — the Moon's altitude and compass direction at that moment. Events with the Moon below the horizon are flagged.
• PA — position angle on the Moon's limb where the event happens, in degrees measured from celestial north through east (90° is the Moon's eastern edge).
• Sky — daylight, civil/nautical/astronomical twilight, or dark, from the Sun's altitude.
• Times are rounded to the nearest minute.
• If there is no occultation, the closest approach to the Moon's center is reported instead, along with where on Earth the occultation can be seen, if it happens anywhere.

Forecast table

• One row per occultation, with the local date and time it starts and ends. For planets these are the first and last contacts.
• Each event shows the Moon's altitude and compass direction, the sky condition, and whether it happens on the Moon's bright limb (sunlit edge) or dark limb. Dark-limb events are much easier to watch; a star vanishing at the dark limb seems to blink out.
• "Moon below horizon" means that half of the event can't be seen, but the other half can.
• Moon is the percentage of the Moon's disk that is illuminated.
• Targets marked * (Uranus, Neptune, Pluto) need a telescope.
• Occurring elsewhere lists occultations seen somewhere on Earth but not from LOCATION, with the reason: the occultation's path misses the location, the Moon is below the horizon, or the sky is too bright. When the path reaches the location, the time is when the occultation starts there; otherwise it is the Moon's closest approach to the target as seen from Earth's center.
• Visible from names up to three regions where the occultation can be seen with the Moon up and the Sun below the horizon (or "daylight only" if nowhere better), largest first. Regions are UN subregions such as "Western Europe" or "Eastern Africa", with large countries split up: US regions ("midwestern and southern US"), Alaska, Hawaii, Canada, China, European Russia, Siberia and the Russian Far East. Paths over water name the ocean or sea. Use --map on that date to see the exact area.
• Only the built-in planets and ten bright stars are searched, so fainter-star occultations that dedicated services such as IOTA list are not included.

Map

The 2026-10-06 Jupiter occultation, framed on North America (--region north-america) and across its whole path (no --region):

Color	Meaning
Dark blue	Visible with the Sun more than 12° below the horizon
Light blue	Visible in twilight
Gold	Visible in daylight (bright planets only, with a telescope)
Gray	The occultation happens there, but the Moon is below the horizon

A lighter shade of each color marks where only one contact happens with the Moon above the horizon: only the disappearance where the Moon sets while the target is hidden, or only the reappearance where it rises. Full-strength areas see both.

The title's "global event window" is the span during which the occultation is happening anywhere on Earth.

Google Earth (KMZ)

The KMZ shows translucent polygons in the colors above, including the lighter shades (folder Visibility), and disappearance-time lines labeled in UTC (folder Disappearance times), plus the observer if --mark-location is used. Each folder can be toggled in Google Earth's sidebar. With --region or --extent, the shapes extend somewhat past the requested box; without either, they cover the whole path where the Moon is up.

Accuracy

For the 2026-10-06 Jupiter occultation, computed times agree with published predictions for Atlanta, Boston, Chicago, Miami, New York, and Winnipeg to within about a minute.

• The Moon is treated as a smooth sphere, so lunar mountains and valleys are ignored. This shifts times by only seconds in most places, but near the northern or southern edge of the path (a graze) predictions are less reliable and the target may blink in and out several times.
• Map boundaries use the target's center, so for planets they are accurate to about the planet's apparent radius.
• Atmospheric refraction is not modeled.