What is nearby, and when bodies come close

/nearest answers three questions about the Sun, the planets, the dwarf planets and the moons: what is next to this one on a date?, when do these two come closest? and how far apart are these two, and how far apart do they get? It is good for a game ("which planet is the Moon beside tonight?"), a calendar of conjunctions, or a label on a chart. It runs anywhere, with no browser, on the package's own positions.

import { closestApproach, conjunctions, distance, distanceRange, nearest, within } from "@johnmorrisdotca/wakusei-planets/nearest";

const date = Date.UTC(2026, 11, 27, 16);
console.log(nearest("moon", { kind: "planet", count: 2, date }).map((row) => `${row.id} ${row.angle.toFixed(2)} degrees`).join(", "));
console.log(within("jupiter", 1.5, { date }).map((row) => row.id).join(", "));
console.log(nearest("earth", { by: "space", kind: "planet", count: 1, date })[0]?.distanceAu.toFixed(2), "au");

const great = closestApproach("jupiter", "saturn", { from: Date.UTC(2020, 11, 1), to: Date.UTC(2021, 0, 1) });
console.log(great.time.toISOString(), great.angle?.toFixed(2), "degrees");
console.log(distance("earth", "mars", date).distanceAu.toFixed(2), "au now apart");
console.log(distanceRange("earth", "mars", { from: Date.UTC(1900, 0, 1), to: Date.UTC(2100, 0, 1) }).max.distanceAu.toFixed(2), "au at most");
console.log(conjunctions({ from: Date.UTC(2023, 0, 1), to: Date.UTC(2024, 0, 1), bodies: ["venus", "jupiter"], within: 2 }).length, "close approaches");

jupiter 1.41 degrees, mars 13.46 degrees
io, europa, ganymede, callisto, moon
0.62 au
2020-12-21T18:25:35.939Z 0.10 degrees
0.95 au now apart
2.68 au at most
1 close approaches

The six functions

A body is a name such as "mars", "moon" or "io", the same names as the rest of the package. The Sun, the planets, the dwarf planets and the moons are all searched. Stars are in /stars; a star is not a target here.

The options

The same options mean the same in every function, and are the names the other packages of the family use for the same things.

Stars have a magnitude filter in /stars; this package has no brightness for a body, so there is no magnitude option here.

In the sky

by: "sky" is the angle between the directions to the two bodies, in degrees from 0 to 180, as the observer sees them. It is worked out with an arc tangent of the cross and dot products, so it is as exact near 0 (a conjunction) and 180 (opposition) as it is at 90. The directions are astrometric, the way JPL Horizons' RA and DEC are: each body is where it was when its light left it (a little over a second ago for the Moon, hours for Neptune), seen from where the observer is now. Aberration and light bending are not added: they move two bodies that are near each other almost together.

The Moon is close enough that where you stand changes the answer by up to a degree, so give a place for it. On 27 December 2026 Ganymede is 2.3 degrees from the Moon seen from Vancouver, and 1.4 seen from the Earth's centre.

import { nearest } from "@johnmorrisdotca/wakusei-planets/nearest";

const date = Date.UTC(2026, 11, 27, 16);
const centre = nearest("moon", { bodies: ["ganymede"], date })[0];
const vancouver = nearest("moon", { bodies: ["ganymede"], date, observer: { latitude: 49.28, longitude: -123.12 } })[0];
console.log(centre?.angle.toFixed(2), vancouver?.angle.toFixed(2));
console.log(nearest("earth", { observer: "mars", count: 1, date })[0]?.id, "is next to the Earth in the sky of Mars");

1.40 2.30
moon is next to the Earth in the sky of Mars

A body is never in its own sky: the target is left out, so is the body the sky is seen from (the Earth, for an observer on it), and a sky target that is the observer's own body throws a RangeError.

In space

by: "space" is the straight-line distance between the two centres at the date, in kilometres (distanceKm) and astronomical units (distanceAu). There is no light time in it: it is the geometry of one instant. The observer does not matter and is ignored.

Closest approach and conjunctions

closestApproach and conjunctions look at the separation as it changes with time. They scan the span in coarse steps: the step is the fastest body's period over forty, and never more than two days (Io goes round in 1.8 days, so a search with Io steps about every hour; Mars and Jupiter step every two days). Where a separation falls and then rises they narrow the minimum with a golden-section search to about a second of time (the search stops when the bracket is under half a second).

closestApproach(a, b, { from, to }) returns the smallest separation in the span. If the separation only falls or only rises through the span, the smaller end is returned and atEdge is true. conjunctions returns every minimum of every pair of bodies that is within within (5 degrees by default for the sky, all of them for space), soonest first. The default bodies are the Sun and Mercury to Neptune, less the body the sky is seen from. A minimum is of the separation of the two centres, so a pair that passes in front of each other (a transit, an occultation) is a minimum of a fraction of a degree, not zero.

import { conjunctions } from "@johnmorrisdotca/wakusei-planets/nearest";

const found = conjunctions({ from: Date.UTC(2026, 0, 1), to: Date.UTC(2027, 0, 1), within: 1 });
for (const one of found.slice(0, 5)) console.log(one.a, one.b, one.time.toISOString().slice(0, 16), one.angle?.toFixed(2));

sun venus 2026-01-06T06:24 0.70
venus mars 2026-01-08T03:12 0.17
sun mars 2026-01-09T09:36 0.94
mercury mars 2026-01-18T06:33 0.96
mercury venus 2026-01-29T13:55 0.68

Distance, and how far apart two bodies get

distance(a, b, date) is by: "space" for any two bodies, one call: { a, b, time, distanceKm, distanceAu, uncertaintyKm }. The date is a Date or milliseconds, and now when left out. distanceRange(a, b, { from, to }) scans the span as closestApproach does and returns { a, b, min, max }, each { time, distanceKm, distanceAu, uncertaintyKm, atEdge }. Each turning point is narrowed to about a second of time by the same golden-section search; the greatest is the least of the negated distance. If the distance only falls or only rises through the span, the end that is the extreme is returned with atEdge: true.

import { distance, distanceRange } from "@johnmorrisdotca/wakusei-planets/nearest";

const { min, max } = distanceRange("earth", "mars", { from: Date.UTC(1900, 0, 1), to: Date.UTC(2100, 0, 1) });
console.log(min.time.toISOString().slice(0, 10), min.distanceAu.toFixed(3), "au;", max.time.toISOString().slice(0, 10), max.distanceAu.toFixed(3), "au");
console.log(Math.round(distance("jupiter", "io", Date.UTC(2026, 10, 8)).distanceKm), "km from Jupiter to Io");

2003-08-27 0.373 au; 2066-08-25 2.676 au
422312 km from Jupiter to Io

The planets, from 1900 to 2100

The least and the greatest distance of each pair of planets over the 200 years (node scripts/distance-table.ts prints it), in astronomical units, and the year of each. A star after a year marks an extreme at the end of the span, not a turning point inside it. Earth and Mars come to 0.373 au on 27 August 2003 and go to 2.676 au in 2066.

Each distance is good to about the uncertainty in the result: a few thousand kilometres for the inner planets and tens of thousands for Jupiter and beyond. Against JPL Horizons on three pairs (the Earth and Mars, Venus and the Earth, Jupiter and Saturn), test/nearest.test.ts takes the table Horizons gives for each pair's least and greatest distance in 1900 to 2100 (geometric vectors from one planet's centre to the other's, ten days at six-hour steps either side of the turning point; scripts/fetch-horizons-distance.py records the queries in test/data/horizons-distance.json) and fits a parabola to find the extreme:

The distance is within the claimed uncertainty every time (a third to a tenth of it). The time is minutes to an hour or two for a distance that is at its flat turning point, where it changes by a few kilometres in an hour: the same small difference in position puts the vertex a little earlier or later.

What a result holds

A sky result is { id, kind, angle, uncertaintyArcseconds } and a space result { id, kind, distanceKm, distanceAu, uncertaintyKm }. A close approach is { a, b, time, atEdge, uncertaintySeconds } with the angle and uncertaintyArcseconds, or the distances and uncertaintyKm. time is a Date.

The uncertainty is what to expect from the theories, not a bound: it is the limits the accuracy tests hold each body to (a planet's direction from the Sun, a moon's from its planet), turned into kilometres at the body's distance and combined. A part of the error that two bodies share cancels: a moon and its planet share the planet's, so Jupiter and Io come out good to a fraction of an arc-second, though Jupiter's own place is good to 3.6 arc-seconds; the Earth's own error, seen from the Earth, cancels between two bodies that are near each other in the sky. uncertaintySeconds is the angle's uncertainty over how fast the two move past each other, so two bodies that crawl past each other (Jupiter and Saturn at 0.01 arc-second a second) have minutes in it and the Moon and a planet have seconds. Without tables, the moons of Jupiter and Saturn are the fitted orbits, and their uncertainty says so.

Against JPL Horizons

test/nearest.test.ts compares every event with Horizons' own table, fetched once (scripts/fetch-horizons-approach.py records each query in test/data/horizons-approach.json; no network in the test). Horizons' RA and DEC are astrometric, from the Earth's centre, at one-minute steps (five for Venus and Jupiter); the minimum of its separation is the vertex of a parabola fitted to the squared separation about the tabulated minimum. Measured on 8 November 2026:

The angle is within 1.5 arc-seconds everywhere, which is the planets' own accuracy. The time is a few seconds for the Moon, which crosses the sky at half a degree an hour, and 270 s for the great conjunction, where Jupiter and Saturn close at 0.01 arc-second a second, so 0.27 arc-seconds is 270 seconds. The test holds each to a limit a little above these, and checks that the claimed uncertainty covers the difference. A place on the Earth is checked too: the Moon and Venus from Vancouver on a table of 25 half-hours is within 0.9 arc-second of Horizons' topocentric table, where the Earth's centre would be 0.85 degree off. The distances are checked against Horizons' vectors on 60 dates from 1800 to 2200: the Earth's distance to each planet is within its claimed uncertainty on every date, and at worst two thirds of it.

The search itself is checked against a brute-force scan of the same separation at one-minute steps (the minimum is within a minute and a hundred-thousandth of a degree), and the list of conjunctions against a six-hourly scan of each pair, which finds the same ones.

How long it takes

node scripts/bench-nearest.ts times each search, the median of five runs on one machine (Node 24, an Apple laptop):

Each body is worked out once for each step, however many pairs it is in, so a longer list of bodies costs in proportion to its length, not its square. The cost is the step: Io's makes a year's search of the Galilean moons a hundred times longer than one of the planets. Give a within that fits the question, a short bodies list and a span of a few years at most for the moons.

Limits

• The accuracy is the package's: a planet to a few arc-seconds, a moon to a degree or two on its orbit (see accuracy), so the angle between two moons is not good to better than that.
• The scan can miss two minima of one pair closer together than its step, which no pair of these bodies has; a pair with a retrograde loop (Mars and Jupiter) is stepped at two days or less.
• A distance has no light time and a sky angle has no aberration or light bending.
• Positions outside 1800 to 2200 get worse, and a dwarf planet outside its table's years is the osculating elements of one epoch; the uncertainty says so (degrees, not arc-seconds).
• A target must be a body of this package. The nearest stars to a planet, or the constellation a planet is in, is for /stars and the packages that carry the constellations.