int = PlanetsNearOn(nDate, nSunDataSourceIndex, nPlanet1, nPlanet2)
This macro function identifies a “near” event by finding when two bodies have the same geocentric ecliptic longitude on nDate. This aligns their longitudes as seen from the centre of the Earth. It does not search for their minimum angular separation or impose a maximum separation. For alignment in right ascension instead, use PlanetsNearOnRA.
•If an alignment on nDate passes the observing-condition checks below, the result packs two integers: the absolute geocentric declination difference, rounded to tenths of a degree, multiplied by 1000000, plus the local time in millionths of a day (0 to 999999). The time component is truncated, not rounded.
•If there is no qualifying alignment on nDate, or it fails the observing-condition checks, the result is -1. Test the complete result for >= 0 before decoding it: 0 is a valid packed result.
•One millionth of a day represents 0.0864 seconds in the time encoding; this specifies the units, not a guarantee of subsecond calculation accuracy.
Specify two different bodies using the astronomical body indices: Moon and planets 1–9, or supported stars 10–29. At most one body may be a star, in either argument. The Sun (0) is excluded. Named constants such as n_MOON and n_MERCURY can be used for the Moon and planets.
Decode a successful result as follows. The angle is a declination difference, measuring the difference in north–south coordinates relative to the celestial equator. At equal ecliptic longitude, it generally differs from the full angular separation on the sky.
if nResult >= 0
nDeclinationDifferenceTenths = nResult div 1000000
nTimeTimesMillion = nResult mod 1000000
endif
The alignment is geocentric, but it is returned only if the following observing conditions hold at the location of the selected Sun data source:
•Both bodies must be more than 4° from the Sun, using topocentric angular separations.
•The Sun's true altitude must be strictly below 0°.
•Both bodies must pass a topocentric apparent-altitude test: strictly greater than 8 arc-minutes (about 0.1333°) for the Moon, and strictly greater than 0° for every other body. Topocentric means as seen from the observer's location; apparent altitude includes atmospheric refraction.
These geometric checks do not guarantee visual detection through actual weather, haze or obstructions.
You will get an error message in the following cases:
•nPlanet1 is the same as nPlanet2
•Either of the planets is the Sun, as nearness with respect to the Sun is not defined (use the function HeliacalEventOnDate instead).
•Either body index is outside the supported range 1–29.
•One body may be a supported star, in either argument; two stars are rejected.
This example lists qualifying equal-longitude events between the Moon and planets through Saturn. It displays the declination difference explicitly, without labeling it as the full sky separation.
sResult = ''
for nPl1 = n_MOON to (n_SATURN-1) step 1
for nPl2 = (nPl1+1) to n_SATURN step 1
nComboResult = PlanetsNearOn(n_TokenDate,1,nPl1,nPl2)
if nComboResult >= 0
nCurTime = nComboResult mod 1000000
nDeclinationDifferenceTenths = nComboResult div 1000000
sBuffer = PlanetName(nPl1) + ' and ' + PlanetName(nPl2)
sBuffer = sBuffer + ': equal longitude at ' + FormatTime('hh:nn',nCurTime,true)
sBuffer = sBuffer + '; declination difference '
sBuffer = sBuffer + IntToStr(nDeclinationDifferenceTenths div 10)
sBuffer = sBuffer + '.' + IntToStr(nDeclinationDifferenceTenths mod 10) + ' degrees'
if sResult <> ''
sResult = sResult + chr(13)
endif
sResult = sResult + sBuffer
endif
endfor
endfor
Use a calculated Sun data source, selected by nSunDataSourceIndex. Dates and returned times use that source's local-time settings. The source's location determines whether the observing-condition filter passes; it does not change the geocentric alignment instant. This macro does not provide an option to disable that filter.
See also: planetary macro functions.
Topic 177565, last updated on 12-Oct-2026
