R Bindings to the Astronomy Engine C Library • astronomyengine

The astronomyengine R package provides R bindings to the Astronomy Engine. It bundles an up-to-date copy of the Astronomy Engine C library by Don Cross as a single-file header + source pair. This provides low-level access to the C library so that other R packages can link against it via LinkingTo without bundling their own copy.

Astronomy Engine is an open-source library for calculating positions of the Sun, Moon, and planets, and for predicting astronomical events such as rise/set times, lunar phases, equinoxes, solstices, eclipses, and transits. It is based on the VSOP87 planetary model and is accurate to within approximately ±1 arcminute.

Installation

You can install the released version of astronomyengine from CRAN with:

install.packages("astronomyengine")

And the development version from GitHub with:

# install.packages("pak")
pak::pak("mitchelloharawild/astronomyengine")

Usage

library(astronomyengine)
# All functions accept a `POSIXct` time as input.
# Here we use a reference time of 2025-02-19 12:00 UTC for all examples.
now <- as.POSIXct("2025-02-19 12:00:00", tz = "UTC")

The R functions and documentation are designed to be as similar as possible to the C API. Therefore the most comprehensive resource for learning how to use the package is the Astronomy Engine C API documentation. If you need support for how to use the package, I suggest that you also search for information about the underlying C library.

Next sunrise

Find the next sunrise at a given location — here, Sydney Observatory (latitude −33.87°, longitude 151.21°):

astro_search_rise_set(
  astro_body[["SUN"]], now,
  latitude = -33.8688, longitude = 151.2093
)
#> [1] "2025-02-19 19:34:50 UTC"

Current moon phase

astro_moon_phase() returns the Moon’s phase as an angle in degrees: 0° = new moon, 90° = first quarter, 180° = full moon, 270° = third quarter.

astro_moon_phase(now)
#> [1] 256.4968

Next full moon

Search for the next time the Moon reaches a specific phase angle. Use 180° for a full moon:

astro_search_moon_phase(180, now, limit_days = 30)
#> [1] "2025-03-14 06:55:19 UTC"

Solar eclipse

Find the next solar eclipse visible anywhere on Earth:

eclipse <- search_global_solar_eclipse(now)
eclipse
#> $status
#> [1] 0
#> 
#> $kind
#> [1] 2
#> 
#> $peak
#> [1] "2025-03-29 10:47:25 UTC"
#> 
#> $distance
#> [1] 6637.035
#> 
#> $latitude
#> [1] NaN
#> 
#> $longitude
#> [1] NaN

The kind field indicates the eclipse type: 0 = partial, 1 = annular, 2 = total. This total solar eclipse peaks on 2025-03-29.

Note: latitude and longitude in the eclipse result indicate the point of greatest eclipse on Earth’s surface. These are only populated for annular eclipses; for total eclipses they will be NaN.

Transit of Mercury

A transit occurs when Mercury passes directly between the Earth and the Sun. These are rare — the next one after February 2025 is in November 2032:

astro_search_transit(astro_body[["MERCURY"]], now)
#> $start
#> [1] "2032-11-13 06:41:48 UTC"
#> 
#> $peak
#> [1] "2032-11-13 08:54:14 UTC"
#> 
#> $finish
#> [1] "2032-11-13 11:06:53 UTC"
#> 
#> $separation
#> [1] 9.594123

Equinoxes and solstices

astro_seasons() returns all four seasonal turning points for a given year:

astro_seasons(2025)
#> $mar_equinox
#> [1] "2025-03-20 09:01:26 UTC"
#> 
#> $jun_solstice
#> [1] "2025-06-21 02:42:17 UTC"
#> 
#> $sep_equinox
#> [1] "2025-09-22 18:19:34 UTC"
#> 
#> $dec_solstice
#> [1] "2025-12-21 15:03:03 UTC"

Using the C library from another package

To use the Astronomy Engine C API from another R package:

Add astronomyengine to both Imports and LinkingTo in your DESCRIPTION:
```
Imports: astronomyengine
LinkingTo: astronomyengine
```
Include the header in your C or C++ source files:
```
#include <astronomy/astronomy.h>
```

For detailed documentation of the C API, including key types, functions, supported bodies, and coordinate frame rotations, see the Astronomy Engine C API documentation.