A lightweight, type-safe TypeScript library for positional astronomy: where things are in the sky, and when.
It has no runtime dependencies, works with plain JavaScript Date objects, and runs anywhere JavaScript does.
Note: astrometry is pre-1.0. The API may change between minor versions.
- Positions of stars, the Sun, the Moon and the planets, for any observer and time.
- Corrections for proper motion, parallax, aberration, precession, nutation and refraction.
- Rise, transit and set times for any target, plus sunrise, solar noon and sunset.
- Twilight bands and the start and end of the night.
- Moon phase, illumination, distance and angular size.
- Planning tools that score how good a target is to observe at any moment.
- Satellites from two-line elements, propagated with SGP4.
- Extras for constellations, eclipses, conjunctions, optics and World Coordinate System (WCS) images.
npm install @observerly/astrometryOr with your package manager of choice:
pnpm add @observerly/astrometryyarn add @observerly/astrometrybun add @observerly/astrometrynub add @observerly/astrometryWhere is Betelgeuse in the sky above Mauna Kea, Hawaii, at 10pm local time on 28th January 2025?
import {
convertEquatorialToHorizontal,
type EquatorialCoordinate,
type GeographicCoordinate
} from '@observerly/astrometry'
// The date and time of the observation, i.e., 10pm HST on 28th January 2025:
const datetime = new Date('2025-01-29T08:00:00Z')
// The observer, i.e., Mauna Kea, Hawaii (in degrees):
const observer: GeographicCoordinate = { latitude: 19.820611, longitude: -155.468094 }
// The target, i.e., Betelgeuse (in degrees, J2000):
const betelgeuse: EquatorialCoordinate = { ra: 88.7929583, dec: 7.4070639 }
const position = convertEquatorialToHorizontal(datetime, observer, betelgeuse)
// { alt: 76.8207, az: 200.2558 }Betelgeuse is 77° above the horizon, just west of due south.
- Angles are in degrees.
- Equatorial coordinates are in the ICRS, at the standard epoch J2000.
- Distances are in metres, and velocities in metres per second.
Every function takes a JavaScript Date. A Date is an instant in time, so your time zone never changes a result.
Functions that work on a whole day, e.g., sunrise, sunset, night and twilight, read that day in UTC.
An observer is a latitude and longitude in degrees, east positive. An optional elevation, in metres above sea level, lowers the observer's horizon for rise and set times.
A few functions take a generic spherical coordinate. These follow ISO 80000-2, with one astronomical twist: θ is measured from the horizon or equator, not from the zenith.
| Angle | Symbol | Range | For example |
|---|---|---|---|
| Polar | θ | [-90, 90] | altitude, declination, latitude |
| Azimuthal | φ | [0, 360) | azimuth, right ascension, longitude |
Both are number, so swapping them is silent. Double-check the order:
import { getAngularSeparation } from '@observerly/astrometry'
const rigel = { ra: 78.6344671, dec: -8.2016383 }
const separation = getAngularSeparation(
{ θ: betelgeuse.dec, φ: betelgeuse.ra },
{ θ: rigel.dec, φ: rigel.ra }
)
// 18.6060Every example below reuses datetime, observer, betelgeuse and position from Quick Start. Results are rounded for readability.
A catalogue position is where a star sat at J2000. To find where it appears tonight, apply three corrections in order:
import {
getApparentEquatorialCoordinate,
getCorrectionToEquatorialForNutation,
getCorrectionToEquatorialForPrecessionOfEquinoxes
} from '@observerly/astrometry'
// 1. Proper motion, parallax and annual aberration, still in the frame of J2000:
const displaced = getApparentEquatorialCoordinate(datetime, betelgeuse)
// 2. Precession carries it to the mean equator and equinox of the date:
const precession = getCorrectionToEquatorialForPrecessionOfEquinoxes(datetime, displaced)
const mean = { ra: displaced.ra + precession.ra, dec: displaced.dec + precession.dec }
// 3. Nutation carries it to the true equator and equinox of the date:
const nutation = getCorrectionToEquatorialForNutation(datetime, mean)
const apparent = { ra: mean.ra + nutation.ra, dec: mean.dec + nutation.dec }
// { ra: 89.1373, dec: 7.4111 }
convertEquatorialToHorizontal(datetime, observer, apparent)
// { alt: 76.9329, az: 198.8351 }Pass a proper motion, in arcseconds per year, as the third argument of getApparentEquatorialCoordinate for fast-moving stars.
The atmosphere bends starlight, lifting targets slightly. Airmass measures how much air you are looking through, where 1 is straight up:
import { getAirmass, getCorrectionToHorizontalForRefraction } from '@observerly/astrometry'
getCorrectionToHorizontalForRefraction(position)
// { alt: 76.8246, az: 200.2558 }
getAirmass(position)
// 1.0267Refraction assumes standard conditions by default. Pass a temperature (K) and pressure (Pa) to refine it.
When does a target next rise and set?
import { getBodyNextRise, getBodyNextSet, isBodyCircumpolar } from '@observerly/astrometry'
getBodyNextSet(datetime, observer, betelgeuse)
// { datetime: 2025-01-29T13:51:31Z, az: 277.88, … }
getBodyNextRise(datetime, observer, betelgeuse)
// { datetime: 2025-01-30T01:28:08Z, az: 82.12, … }
isBodyCircumpolar(observer, betelgeuse)
// falseBoth return false for a target that never rises or never sets.
import { getSolarNoon, getSunrise, getSunset } from '@observerly/astrometry'
getSunrise(datetime, observer)
// 2025-01-29T16:57:46Z
getSolarNoon(datetime, observer)
// 2025-01-29T22:35:05Z
getSunset(datetime, observer)
// 2025-01-30T04:12:36ZThe times are for the solar noon on the UTC date of datetime, with sunrise before it and sunset after it. They follow the almanac convention: the Sun's upper limb touching the horizon.
Sunrise and sunset return null during a polar day or polar night.
import { getNight, getTwilightBandsForDay, isNight, Twilight } from '@observerly/astrometry'
isNight(datetime, observer)
// true
// The night after the solar day of `datetime`, with the Sun 12° below the horizon:
getNight(datetime, observer)
// { start: 2025-01-30T05:02:08Z, end: 2025-01-30T16:08:01Z }
// Every band of the UTC day, i.e., Day, Civil, Nautical, Astronomical and Night:
const bands = getTwilightBandsForDay(datetime, observer)
bands.find(({ name }) => name === Twilight.Night)
// { name: 'Night', interval: { from: 2025-01-29T05:28:00Z, to: 2025-01-29T15:42:00Z } }Pass a horizon, e.g., getNight(datetime, observer, -18), for astronomical night.
import { getLunarIllumination, getLunarPhase } from '@observerly/astrometry'
getLunarPhase(datetime)
// 'New'
getLunarIllumination(datetime)
// 0.19 (%)The moon module also covers the Moon's position, distance, angular size and age, and finds the next full and new Moon.
import { getPlanetaryPositions } from '@observerly/astrometry'
const planets = getPlanetaryPositions(datetime, observer)
// Each planet carries its ecliptic, equatorial and horizontal coordinates:
planets.filter(({ alt }) => alt > 0).map(({ name }) => name)
// ['Mars', 'Jupiter', 'Uranus']import { getConstellation } from '@observerly/astrometry'
getConstellation(betelgeuse)?.name
// 'Orion'Every IAU constellation is also exported by name, e.g., orion, with its abbreviation, meaning and a GeoJSON feature.
How good is it to observe Betelgeuse right now?
import { getObservationalQuality } from '@observerly/astrometry'
const { quality, observable } = getObservationalQuality(datetime, observer, betelgeuse)
// quality: 0.56, observable: trueQuality runs from -1, unobservable, to 1, ideal. By default it weighs the target's altitude, the Sun's altitude and the Moon's separation.
Pass your own constraints as the fourth argument, e.g., AirmassConstraint, MoonIlluminationConstraint or SunAvoidanceConstraint.
Propagate a satellite from its two-line element set (TLE) with SGP4:
import { parseTwoLineElement, SatelliteRecord } from '@observerly/astrometry'
// The International Space Station, on 20th September 2008:
const tle = parseTwoLineElement(
'1 25544U 98067A 08264.51782528 -.00002182 00000-0 -11606-4 0 2927',
'2 25544 51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537'
)
const iss = new SatelliteRecord(tle)
iss.getStateVector(new Date('2008-09-20T13:00:00Z'))
// position: { x: -1345306.9, y: 5181620.4, z: -4088075.7 } (m)
// velocity: { x: -5080.8, y: -4325.1, z: -3821.7 } (m/s)State vectors are in the True Equator, Mean Equinox (TEME) frame. Near-Earth orbits, with a period under 225 minutes, are supported. Deep-space orbits throw an SGP4Error for now.
import { formatDegreeToDMSHumanized, formatDegreeToHMSHumanized } from '@observerly/astrometry'
formatDegreeToHMSHumanized(betelgeuse.ra)
// '05ʰ 55ᵐ 10.310ˢ'
formatDegreeToDMSHumanized(betelgeuse.dec)
// '+07° 24\' 25.430"'Everything is exported from the package root. Each module also has its own entry point, so you can import only what you need:
import { getSunrise } from '@observerly/astrometry/sun'Results are checked against trusted references by the conformance suite, which runs with every test run:
- Sun: positions use the full VSOP87 planetary theory, and agree with the NREL Solar Position Algorithm to within 0.22 arcseconds. Sunrise, solar noon and sunset agree to within 0.1 seconds.
- Earth: precession, nutation, sidereal time, aberration, light deflection and parallax agree with ERFA, the open implementation of the IAU's SOFA.
- Satellites: SGP4 agrees with the reference implementation of Vallado et al. (2006) to well below a micrometre.
- No runtime dependencies.
- Ships ES modules, CommonJS and TypeScript types.
- Side-effect free, so bundlers can tree-shake what you don't use.
- Tested on Node.js 22, 24 and 26, and written for Deno, Bun and the browser.
Contributions are welcome. Please read the contributing guide and our code of conduct first.
Before opening an issue or pull request, please check whether a similar one already exists.
To work on the library locally:
pnpm installpnpm testpnpm lintpnpm formatpnpm build@observerly/astrometry is released under the MIT License.
