moon-sighting/README.md

moon-sighting

High-accuracy lunar crescent visibility and moon sighting calculations for Node.js and browsers. Uses the JPL DE442S ephemeris with full IERS Earth orientation for sub-arcsecond topocentric Moon and Sun positions. Implements the Yallop (NAO TN 69) and Odeh (Experimental Astronomy 2006) criteria.

Installation

npm install moon-sighting

Then download the JPL kernel (31 MB, one-time):

npx moon-sighting download-kernels

Quick Start

import { initKernels, getMoonSightingReport } from 'moon-sighting'

await initKernels()

const report = await getMoonSightingReport(new Date('2025-03-29'), {
  lat: 51.5074, lon: -0.1278, elevation: 10
})

console.log(report.yallop.category)   // 'A' — easily visible to the naked eye
console.log(report.odeh.zone)         // 'A' — visible with naked eye
console.log(report.guidance)

Five functions work without any kernel (Meeus approximation, ~0.3° accuracy):

import { getMoonPhase, getMoonPosition, getMoonIllumination,
         getMoonVisibilityEstimate, getMoon } from 'moon-sighting'

const phase = getMoonPhase()
console.log(phase.phaseName)      // 'Waxing Crescent'
console.log(phase.illumination)   // 14.3 (percent)

Documentation

Full documentation on the GitHub Wiki:

• Getting Started
• API Reference
• Architecture
• Crescent Visibility Criteria
• Ephemeris and Kernel Setup

Related

• nrel-spa: Pure JS solar position algorithm
• pray-calc: Islamic prayer times with dynamic angle algorithm

License

MIT. See LICENSE.