Choose the right integration.
Developer tools have different release states. Public sky files, hosted embeds and the compute API are available now; the compute API answers only while its per-address rate limit is in place. The local engine below is a release candidate, distributed as a digest-pinned archive and not on npm.
Local engine · vendored candidate
The engine page is the shorter route: what it computes, what it costs to bundle, how far it agrees with Swiss Ephemeris, and an install that verifies the digest before npm sees the file. This section is the reference behind it.
This revision vendors the 0.1.1-rc.17 archive below, a release candidate that is not on npm. Its bytes match the engine repository carrier, and it passed clean-consumer checks on Node 22 and 24. This archive identifies the local package; hosted data and widgets are separate deployments.
The verified registry read of 2026-10-06 records 0.1.1-rc.16 under next and 0.1.1-rc.15 under latest. npm install @zodiacs/engine@0.1.1-rc.16 installs 0.1.1-rc.16, the version before this candidate, which refuses the sidereal zodiac in @zodiacs/engine/calc. It was published from the release.yml workflow of the engine repository with SLSA provenance, which names that repository, the workflow and the commit the package was built from; npm audit signatures verifies it. Provenance shows where the package was built. It does not show that its results are correct.
Download engine 0.1.1-rc.17 (.tgz). Verify its SHA-256 before installing the local file; follow the candidate README and examples.
SHA-256: 9cd24c788863424ef614aaadec580db5a0dfc529303d385274db48a092a5299a
Run the starter project for complete local natal, transit, and publisher widget examples.
Use the public @zodiacs/engine and optional @zodiacs/engine/geo and @zodiacs/engine/receipt entry points. The /internal entry points are site compatibility boundaries. Use the current candidate API guide, draft receipt specification (written for rc.3 to rc.6), and candidate changelog. The 0.1.1-rc.17 API reference documents every public entry point of the archive this revision vendors; the archived rc.1 API reference describes the earlier candidate.
| Capability | Current support |
|---|---|
| Language and runtime | ESM JavaScript with TypeScript declarations. The manifest declares Node.js ^20.19.0 || >=22.7.0: astronomy-engine ships ES modules in a package without "type": "module", which plain Node loads as ES modules only from 20.19.0 and 22.7.0. There is no CommonJS export. Browser integrations need an ESM-aware bundler or equivalent dependency setup; bundlers are not affected by the Node range. |
| Recorded runtime checks | The linked reports record this candidate’s tested runtimes, package consumers and TypeScript declarations. They identify the exact artifact and validation scope; they do not certify every browser or all Node versions allowed by the manifest. |
| Zodiac and positions | Tropical ecliptic of date; apparent geocentric positions in degrees. Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, and true North/South Moon nodes. The sidereal zodiac is in the separate @zodiacs/engine/vedic and @zodiacs/engine/calc entry points. The core has no topocentric parallax; @zodiacs/engine/calc offers a topocentric center. |
| Calculations | Positions, natal charts, transit snapshots, synastry, Moon phase, Saturn-return seasons, secondary progressions, chart points, aspects under a configurable policy, and declinations with parallels. Separate imports add Hellenistic timing (@zodiacs/engine/timing) and sidereal and Jyotish techniques (@zodiacs/engine/vedic). The same public API supplies calculation metadata; interpretation is separate from astronomical accuracy. |
| Houses and unknown time | Thirteen house systems, each as Swiss Ephemeris defines it: whole sign, Placidus, Koch, Porphyry, Regiomontanus, Campanus, Topocentric, Alcabitius, Equal (Ascendant), Equal-MC, Vehlow, Meridian and Morinus. Known time and coordinates are required for angles/houses. timeKnown: false sets both to null and adds no-time. Placidus and Koch fall back to whole sign inside the polar circle, where the absolute latitude is 90° minus the obliquity or more, and Placidus also on nonconvergence, with polar-fallback. The other eleven systems are defined wherever the angles are. Exact geographic poles and degenerate horizon intersections are outside verified angle scope. |
| Resolved instant input | A valid Date, finite epoch milliseconds, or validated ISO date/time. Date-times require Z or an explicit numeric offset; date-only YYYY-MM-DD means midnight UTC. Invalid ISO calendar dates, unresolved local date-times, leap seconds, and more than three fractional-second digits are rejected. A Date already normalized by its caller cannot reveal that earlier rollover. Outputs normalize to Date and do not preserve the original offset or local timezone. The instant is read as UTC: from 1972 to 2027-10-02 through the IERS leap seconds and UT1 − UTC, otherwise as UT1 with the ΔT model, and the chart reports which (timeScale). A timeScale of "ut1" or "tt" reads it on that scale instead; any other value, and a birth-input key that differs from a field only in letter case, throws a RangeError. |
| Portable natal records | Optional @zodiacs/engine/receipt validates a Zodiacs draft envelope from a fresh full public Chart, preserving requested/actual houses and captured time provenance. Validation does not authenticate imported claims or recalculate positions. The site saved-chart/account format is unchanged; the standalone starter uses its separately pinned candidate. |
| Local-time resolution | Optional @zodiacs/engine/geo accepts a local YYYY-MM-DD date, HH:mm time, and explicit IANA timezone. Folds select the earlier instant; gaps shift forward, with flags. Before 1970 it reads the IANA time zone history 2025c with backzone, which it ships in 16 files: prepareLocalTime(date, timeZone) must load a zone’s history first, or the call throws. From 1970 the host Intl/ICU data answers. A longitude reads a time within a zone’s local mean time era on the birthplace’s own mean time, and the lmt flag means that such a clock read it; calendar: "julian" takes an Old Style date. Unknown options and form keys throw a RangeError. No place records are bundled. |
| Date coverage and accuracy | Every calculation throws a RangeError for an instant outside EPHEMERIS_SPAN, Terrestrial Time 0001-04-30 to 3998-09-03, the years astronomy-engine tabulates. That span is where the ephemeris evaluates at all, not a numerical accuracy interval. Tests cover finite modern, historical, early-year, and polar cases; broader range and numerical scope review remain open. The mini-chart widget’s form limits are a separate UI contract. |
| Computation and privacy | The synchronous core computes in the caller’s browser or Node.js process, with no network requests, account, or wallet. The optional GeoNames client fetches separately hosted index/shard assets; the data host can observe those requests. Your integration controls any storage or network transfer around the calculation. |
| License | The package is licensed MIT AND CC-BY-4.0: its code and its astronomy-engine dependency are MIT, and the 32 ΔT values of Stephenson, Morrison & Hohenkerk’s Table S15 in its ΔT module are CC BY 4.0. It also carries the IANA time zone history before 1970 and the IERS leap-second list, both public domain, a UT1 − UTC table derived from IERS series, and catalogue values for the stars of the Vedic ayanamsas: NOTICE names each source, and LICENSING.md gives their terms and three questions about them that are still open. Retain the packaged LICENSE, LICENSING.md and NOTICE. Hosting or redistributing GeoNames-derived place data also requires its CC BY 4.0 attribution. |
A longitude-crossing search has no sample budget unless you give it one:searchLongitudeCrossings takes an optional budget and refuses the whole search, rather than throwing, when it would be exceeded. Sampling can miss events between steps, and direction at a window endpoint uses one-sided evidence. This is not a guarantee of complete event discovery.
The candidate evidence ledger records commands, runtimes, reference conventions, and limits. Read the Node 22 comparison, Node 24 comparison, and public-download consumer check. These are finite test results and internal reviews, not human practitioner certification or evidence that astrological interpretation is scientifically validated.
For accuracy specifically, the consolidated validation report gathers positions, angles and houses, local time, event search and runtime support into one page: the measured residual for each, the Swiss and JPL oracles behind it, and what each result does not establish — including one event-search contract that is still failing.
Shared sky data · available
Public JSON and Markdown files work with any HTTP client, without a key or account. They contain shared-sky data, not personalized charts or houses. The daily positions cover the Sun, Moon, and eight planets in the tropical, geocentric system; positions are computed for 12:00 UTC on the edition date rather than updated continuously.
Check the payload’s UTC edition and snapshot, and read the live coverage index for available years. Event windows can be clipped at coverage boundaries. Data is CC BY 4.0 with Zodiacs.org attribution. Start with the validated quick start and cache contract, OpenAPI reference, or agent guide.
Hosted widgets · available
The widget builder supplies Moon phase, daily sky, and mini birth-chart iframes. An optional script mounts the same sandboxed documents. No npm package or framework is required; the@zodiacs/widgets package is not a released installation path. Dark/light themes and an adjusted accent work inside the frame; keep its width within the host layout and its “Powered by Zodiacs.org” credit intact.
The mini chart computes Sun, Moon, and rising inside its iframe after submission. Its form accepts 1800–2199 and requires a date, time, and selected birthplace. That form range is not a complete numerical accuracy claim. It loads code and place-index assets; it does not send entered birth details to a chart API or include the main site’s analytics. An embed still makes ordinary requests to Zodiacs.org; it is not an offline or network-free integration.
Hosted computation · available
The compute API runs the same engine on our server: seven POST endpoints for a chart, positions, houses, events in a window, local time, sky facts and the stretches of a window in which chosen conditions hold, with no key. Birth data goes in the request body; the function writes nothing from a request to a log, a file or a database, and no response is cached, though the host's request logs keep each request's web address and IP address. Requests from one address are rate limited, and the endpoints answer only while that limit is in place: until it is, and whenever it cannot be checked, every endpoint answers 503. Each endpoint has published limits past which a request is refused rather than computed. The public shared-sky files still take no birth inputs.
Optional ownership SDK · separate integration
The ownership SDK supports official registry verification, public ownership reads, and identity helpers. Its core is React-free and read-only; React/UI and other adapters require explicit optional imports. The SDK reference documents its supported networks. It does not request private keys, sign messages, or submit transactions. Public balance reads use the configured RPC provider. None of the chart, sky-data, or widget paths requires this SDK or wallet ownership.
Report a discrepancy
Engine issues belong in the SDK repository; use site issues for data files or embeds. Include the version or payload URL, runtime, settings, expected result, and actual result. Prefer a synthetic input that reproduces the problem; public issues should not contain someone’s name or private birth details. There is no published long-term support or response-time guarantee for this candidate.