:::note
**TL;DR**
- The Swiss Ephemeris is a C library from Astrodienst AG that computes planetary positions to sub-milliarcsecond precision, derived from NASA JPL Development Ephemeris data.
- Three calculation modes: raw JPL files (~3 GB), compressed Swiss (~30 MB, default), or Moshier semi-analytical (no files, ~1 arc second).
- Licensing is the trap: AGPL forces open-sourcing your full SaaS application unless you buy a commercial license from Astrodienst.
- For most builders, calling an astrology API is the right answer. Roxy Ephemeris is the in-house engine behind Roxy, verified against NASA JPL Horizons with no AGPL restrictions.
:::

Every astrology app you have ever used, from the birth chart generator on your phone to the professional Jyotish software your astrologer runs, depends on one fundamental problem being solved correctly: where exactly was each planet at a specific moment in time?

This is not a trivial calculation. The Moon moves roughly 13 degrees per day. Mercury shifts between direct and retrograde motion. Pluto takes 248 years to orbit the Sun. Getting these positions right to within a fraction of an arc second requires modeling orbital mechanics, gravitational perturbations between planets, relativistic light-bending near the Sun, and the slow wobble of the Earth on its axis.

The Swiss Ephemeris is the open-source library that solves this problem. Developed by Astrodienst AG in Zurich and maintained since 1997 by Dieter Koch and Dr. Alois Treindl, it is the most widely used astronomical calculation engine in astrological software worldwide. If you are building anything that involves planetary positions, you need to understand what it does, how it works, and what its limitations are.

:::note
**RoxyAPI does not use Swiss Ephemeris.** Two reasons drive that decision, both covered in detail at [/methodology](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against"):

1. **Licensing footgun for commercial APIs.** Swiss Ephemeris is AGPLv3. Any service that exposes Swiss-backed calculations over a network propagates the AGPL copyleft requirement to every downstream user of that service. Roxy is a commercial API with paying SaaS customers shipping closed-source iOS apps, Android apps, WordPress plugins, and matrimonial platforms. We do not pass an AGPL obligation through to a customer who bought a Starter plan to add daily horoscopes to their app. Astrodienst sells a commercial license, but reselling that liability instead of routing around it would still leave every API customer reasoning about a copyleft license they did not choose.

2. **Architecture from a different era.** Swiss Ephemeris was released in 1997, designed around desktop astrology software running on one user PC. The architecture reflects that origin: a C library with global state, binary ephemeris files (~30 MB for planets, up to ~29 GB for the full asteroid catalog) read from local disk on every coordinate query, multi-step setup calls (`swe_set_ephe_path`, `swe_set_sid_mode`, `swe_set_topo`) before each computation. None of that maps cleanly to stateless serverless functions, edge runtimes, multi-tenant API servers, or AI agents firing bursty concurrent requests through MCP. A modern API engine has to be cold-start friendly, hold no per-request state, and answer in low-double-digit milliseconds without touching a file. Roxy Ephemeris was built that way from day one.

The rest of this article is a fair, technical walkthrough of Swiss Ephemeris itself: what it computes, how it works, where it shines, and where it costs you. If you are evaluating engines for your own integration, that context matters more than any vendor pitch.
:::

## What Is an Ephemeris?

An ephemeris (plural: ephemerides) is a table of positions for astronomical objects at specific times. The word comes from the Greek "ephemeris" meaning "diary" or "journal." NASA defines it as "a tabulation of computed positions and velocities of an orbiting body at specific times."

Historically, ephemerides were printed books. Astronomers and navigators would look up planetary positions for a given date. Modern ephemerides are computed on demand by software libraries that model the physics of planetary motion.

There are two fundamental approaches to computing an ephemeris:

**Numerical integration** starts from precisely measured positions and velocities of celestial bodies, then steps forward (or backward) through time using Newtonian mechanics and general relativity corrections. NASA JPL uses this approach for their Development Ephemeris series. It is extremely accurate but produces massive data files.

**Semi-analytical methods** use mathematical formulas (series expansions) that approximate planetary orbits. These are less accurate but require no external data files. The Moshier ephemeris uses this approach.

The Swiss Ephemeris supports both, plus a compressed version of the numerical integration approach that is essentially as accurate as the original but much smaller.

## The Three Calculation Modes

The Swiss Ephemeris offers three distinct calculation backends, each with different trade-offs between precision, speed, and file size:

### 1. JPL Ephemeris (Highest Precision)

This mode reads directly from NASA JPL Development Ephemeris data files. The current standard is DE431, which covers 13,000 years (from 13,200 BCE to 17,191 CE). DE441 is also supported for even more recent data.

- **Precision**: Sub-milliarcsecond for modern dates (better than 0.001 arc seconds)
- **File size**: Approximately 3 GB for the full date range
- **Use case**: Research-grade astronomical calculations, maximum precision requirements

JPL computed these ephemerides by numerically integrating the equations of motion for all major solar system bodies simultaneously, accounting for gravitational interactions, relativistic effects, and observational constraints from spacecraft tracking data.

### 2. Swiss Ephemeris (Compressed JPL)

The default mode. Astrodienst compressed the JPL data using Chebyshev polynomial interpolation, reducing file sizes by roughly 100x while preserving essentially all the original precision.

- **Precision**: Matches JPL to within 0.001 arc seconds (1 milliarcsecond)
- **File size**: Approximately 30 MB for standard planetary files
- **Use case**: Production astrological software, the sweet spot of precision and practicality

For any astrological application, this mode is indistinguishable from the raw JPL ephemeris. The compression error (< 0.001 arc seconds) is far below the precision needed for any astrological technique.

### 3. Moshier Ephemeris (No Files Required)

A semi-analytical ephemeris compiled directly into the library code. Based on Steve Moshier analytical ephemeris, it requires no external data files at all.

- **Precision**: About 1 arc second for planets, a few arc seconds for the Moon
- **File size**: Zero (built into the library binary)
- **Use case**: Lightweight applications, embedded systems, situations where file distribution is impractical

One arc second of precision is more than sufficient for most astrological purposes. Consider that a 1 arc second error in planetary longitude translates to about 4 seconds of time in the fastest-moving body (the Moon). No astrologer works with birth times accurate to 4 seconds.

### Precision Comparison Table

| Ephemeris Mode | Planetary Precision | Moon Precision | File Size | Date Range |
|---------------|-------------------|----------------|-----------|------------|
| JPL DE431 | < 0.001 arc sec | < 0.001 arc sec | ~3 GB | 13,200 BCE - 17,191 CE |
| Swiss Ephemeris | < 0.001 arc sec | < 0.001 arc sec | ~30 MB | 13,200 BCE - 17,191 CE |
| Moshier | ~1 arc sec | ~3 arc sec | 0 (built-in) | 3,000 BCE - 3,000 CE |

For context: 1 arc second is 1/3600th of a degree. The full zodiac is 360 degrees. Even the least precise mode (Moshier) places planets within a tiny fraction of a zodiac degree.

## What the Swiss Ephemeris Actually Computes

The library is far more than a planetary position lookup. Here is what the API surface covers:

### Planetary Positions

The core function `swe_calc()` computes positions for:

- **Sun, Moon, and planets** (Mercury through Pluto)
- **Lunar nodes** (both mean and true/osculating)
- **Lunar apogee** (Black Moon Lilith in astrological terms)
- **Over 620,000 numbered asteroids** (Ceres, Pallas, Juno, Vesta, Chiron, Pholus, and hundreds of thousands more)
- **Fixed stars** (full catalog with proper motion corrections)
- **Hypothetical bodies** (Uranian planets: Cupido, Hades, Zeus, Kronos, Apollon, Admetos, Vulkanus, Poseidon)

Each calculation returns six values: longitude, latitude, distance, and speed in all three dimensions.

### Coordinate Systems and Corrections

Every position can be computed in multiple reference frames:

- **Geocentric** (default): as seen from Earth center
- **Topocentric**: as seen from a specific location on Earth surface
- **Heliocentric**: as seen from the Sun
- **Barycentric**: relative to the solar system center of mass

And with configurable corrections:

- **Precession**: the 26,000-year wobble of Earth axis
- **Nutation**: short-period oscillations of the axis
- **Aberration**: apparent shift due to Earth orbital velocity
- **Gravitational deflection**: light bending near the Sun (general relativity)
- **True vs. apparent positions**: with or without atmospheric and geometric corrections

### House Systems

The library implements 25+ house systems, each with different mathematical projections of the ecliptic onto the local horizon:

Placidus, Koch, Regiomontanus, Campanus, Equal, Whole Sign, Porphyry, Morinus, Alcabitius, Topocentric (Polich-Page), Axial Rotation, Sunshine, Krusinski-Pisa-Goelzer, APC, Gauquelin sectors, and more. Each system returns 12 house cusps plus special points (Ascendant, MC, Vertex, East Point, Equatorial Ascendant).

### Sidereal Calculations (Vedic Astrology)

For Jyotish practitioners, the library provides 40+ predefined ayanamsha systems including:

- **Lahiri** (official Indian government standard)
- **Krishnamurti** (KP system)
- **Raman**
- **Fagan-Bradley** (Western sidereal)
- **Suryasiddhanta** variants
- **Aryabhata**
- **True Citra** and **True Revati** (based on actual star positions)
- **User-defined** ayanamsha (custom epoch and rate)

Each ayanamsha shifts all planetary positions by a different angular amount, and the values change slowly over centuries. The library handles all the precession math internally.

### Eclipses and Phenomena

Beyond position calculations, the Swiss Ephemeris computes:

- **Solar and lunar eclipses**: global and local visibility, timing, magnitude
- **Occultations**: Moon passing in front of planets or stars
- **Rising, setting, and meridian transits** for any body
- **Heliacal risings and settings** (first/last visibility of planets and stars)
- **Planetary phenomena**: phase angles, elongation, apparent diameter, magnitude

### Time Systems

Astronomical time is surprisingly complex. The library handles:

- **Julian Day Number** conversion to and from calendar dates
- **Delta T**: the difference between uniform atomic time (TT) and Earth rotation time (UT), which varies unpredictably over centuries
- **UTC to Julian Day** conversions with leap second handling
- **Local Mean Time to Local Apparent Time** conversions
- **Gregorian and Julian calendar** support (the switchover date differs by country)

## Why Implementation Is Harder Than It Looks

Reading the API documentation, the Swiss Ephemeris might seem straightforward: call a function, get back coordinates. In practice, building a production astrology backend on top of it involves several non-obvious challenges:

### The C Library Problem

The Swiss Ephemeris is written in C. If your application is in Python, JavaScript, Go, or any other language, you need either:

- A **native binding** (FFI/WASM wrapper) that compiles the C code for your platform
- A **port** to your language (which must be verified against the original for accuracy)
- A **WebAssembly build** for browser or serverless environments

Each option introduces build complexity, platform-specific bugs, and maintenance burden when the upstream library updates.

### State Management

The library uses global state. Functions like `swe_set_ephe_path()`, `swe_set_sid_mode()`, and `swe_set_topo()` modify global configuration. In a multi-tenant server handling concurrent requests (different users wanting different ayanamshas or house systems), you need careful synchronization or process isolation.

### Edge Cases at Extreme Latitudes

Placidus and Koch house systems become mathematically undefined at latitudes beyond the Arctic and Antarctic circles. The library handles this differently depending on the version, and the behavior at the boundaries can produce unexpected results. Production software needs fallback logic for users born at extreme latitudes.

### Historical Date Accuracy

Delta T (the difference between uniform time and Earth rotation time) is poorly known for dates before telescopic observations began around 1600 CE. For ancient dates, Delta T uncertainty grows to hours, which directly affects Moon position calculations. The library provides multiple Delta T models, but the developer must choose which one to use and communicate the uncertainty to users.

### Ephemeris File Distribution

If using the Swiss Ephemeris or JPL modes (not Moshier), you need to distribute and manage data files. The standard planetary files are ~30 MB, but asteroid files for all 620,000+ numbered asteroids total approximately 29 GB. Your deployment strategy needs to handle file paths, missing file errors, and updates.

## The Licensing Reality

The Swiss Ephemeris uses dual licensing that trips up many developers:

**AGPL (GNU Affero General Public License)**: Free to use, but with a significant catch. If you use Swiss Ephemeris in software that is accessible over a network (which includes any web API or SaaS product), you must release your entire source code under AGPL or a compatible license. This means open-sourcing your full application, not just the ephemeris integration code.

**Commercial License**: Available from Astrodienst AG. Pricing is not public and requires direct negotiation. This license allows you to use the Swiss Ephemeris in proprietary software without open-sourcing your code.

For hobby projects and open-source tools, AGPL is fine. For commercial astrology apps, SaaS platforms, or API products, you need the commercial license or an alternative approach entirely.

## Alternatives to Swiss Ephemeris

Swiss Ephemeris is the most widely used option, but it is not the only one. Developers who cannot accept AGPL or do not want C dependencies have alternatives.

**VSOP87** (Variations Seculaires des Orbites Planetaires): An analytical planetary theory from the Bureau des Longitudes in Paris. Computes positions from mathematical formulas directly with no data files. Accuracy within 1 arcminute for modern dates, which exceeds what any astrological application requires. Open implementations exist in multiple languages under permissive licenses.

**Moshier standalone**: The semi-analytical ephemeris used as the Swiss Ephemeris fallback mode can be extracted and used independently without the AGPL-licensed wrapper code.

**Roxy Ephemeris**: The in-house engine powering [RoxyAPI](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against"), verified against NASA JPL Horizons. Designed for concurrent API workloads with stateless computation, zero file I/O, and no AGPL restrictions. Sub-arcminute accuracy verified with 2,300+ automated tests, including 828 gold standard tests against authoritative sources.

:::tip
The key insight: for astrological applications, sub-arcminute accuracy is indistinguishable from sub-milliarcsecond accuracy. Birth time uncertainty (typically 1 to 15 minutes) introduces far larger position errors than the difference between any of these engines.
:::

## The Alternative: Using an API

For most developers building astrology features, the Swiss Ephemeris is the engine they need but not the engine they should maintain. The complexity of C bindings, global state management, file distribution, edge case handling, accuracy verification, and licensing compliance adds up fast.

This is exactly why astrology APIs exist. Instead of integrating the ephemeris library directly, you call an HTTP endpoint and get back precisely calculated planetary positions, house cusps, aspects, and interpretive data.

[RoxyAPI](/products "RoxyAPI product catalogue across astrology, tarot, numerology, I-Ching, dreams, crystals, and angel numbers") provides production-grade astronomical calculations through [Roxy Ephemeris](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against"), its own in-house calculation engine verified against [NASA JPL Horizons](https://www.jpl.nasa.gov/). RoxyAPI does not use Swiss Ephemeris. You get:

- **Astrology (Western, Vedic, KP)** plus tarot, numerology, I-Ching, dreams, crystals, and angel numbers. 12 domains, 145+ endpoints, one API key
- **15+ house systems** and **10+ ayanamsha options** preconfigured
- **Planetary positions, aspects, houses, nakshatras, dashas, yogas**, and more
- **Remote MCP servers, one per domain** (Streamable HTTP, no local setup). Point Claude Code, Cursor, VS Code, or Windsurf at the URL and you are running in seconds
- **OpenAPI documentation** with interactive examples

No C compilation, no ephemeris files, no AGPL concerns. A single HTTP call replaces hundreds of lines of ephemeris integration code.

:::note
**Roxy Ephemeris** is an independent calculation engine that uses pure analytical computation with zero file-based ephemeris reads, and ships with no AGPL restrictions. Planetary positions are verified against NASA JPL Horizons, with cross-references against DrikPanchang, onlinejyotish.com, Astrologify.com, and timeanddate.com for the Vedic, KP, Western, and lunar layers respectively. 2,300+ automated tests, including 828 gold standard tests against authoritative sources, run on every deployment. Full methodology at [roxyapi.com/methodology](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against").
:::

```bash
# Planetary positions with one API call
curl -X POST "https://roxyapi.com/api/v2/astrology/planets" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "1990-06-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.0060, "timezone": -5}'
```

Check the [Western Astrology API reference](/api-reference#tag/western-astrology "full Western Astrology API endpoint reference with request and response schemas") for the full list of available calculations, or view [pricing](/pricing "RoxyAPI pricing and plan tiers") to get started.

## When to Use the Swiss Ephemeris Directly

Despite the complexity, there are valid reasons to integrate the Swiss Ephemeris directly:

- **You are building the calculation engine itself** (an astrology library or API product)
- **You need offline calculations** without network dependency
- **You require exotic calculations** not available in any API (specific asteroid ephemerides, custom ayanamshas, research-grade computations)
- **Your application is open-source** and AGPL licensing is not a constraint
- **You need calculations for dates beyond standard API coverage** (deep historical or far future dates)

For building end-user astrology apps, horoscope features, compatibility tools, or AI-powered astrology chatbots, an API delivers the same underlying precision with far less engineering overhead.

## Key Concepts Every Developer Should Know

Whether you use the Swiss Ephemeris directly or through an API, understanding these concepts helps you build better astrology software:

**Tropical vs. Sidereal zodiac**: The Western tropical zodiac is fixed to the equinoxes (0 degrees Aries = spring equinox). The Vedic sidereal zodiac is fixed to the stars. They currently differ by about 24 degrees (the ayanamsha), and the gap grows by about 1 degree every 72 years due to precession.

**House system choice matters**: Different house systems can place the same planet in different houses. Placidus is the most popular in Western astrology, Whole Sign in Hellenistic and some Vedic traditions. Your application should let users choose their preferred system.

**Aspect orbs are configurable**: Whether two planets are "in aspect" depends on the orb (tolerance) used. A 10-degree orb for conjunctions is traditional but loose. A 1-degree orb is tight but precise. There is no universal standard, so expose this as a configuration option.

**Precision beyond arc seconds is meaningless for astrology**: While the Swiss Ephemeris can compute positions to sub-milliarcsecond precision, birth time uncertainty (typically 1-15 minutes) introduces far larger position errors. The Moon moves about 0.5 degrees in 1 minute of time. Do not let precision theater drive architectural decisions.

## Conclusion

The Swiss Ephemeris is the gold standard for astronomical position calculations in astrological software. Built on NASA JPL data, maintained for over 25 years, and used by most professional astrology programs worldwide, it solves the hard problem of "where was this planet at this exact moment" with extraordinary precision.

For developers, the key takeaway is understanding the trade-off: the Swiss Ephemeris gives you maximum control and precision, but at the cost of C library integration, file management, state handling, edge case coverage, accuracy testing, and AGPL licensing compliance.

**Key takeaways**:

- The Swiss Ephemeris provides three precision levels: JPL (sub-milliarcsecond), compressed Swiss (equivalent precision), and Moshier (1 arc second, no files)
- It computes far more than planet positions: 25+ house systems, 40+ ayanamshas, eclipses, asteroids, fixed stars, and coordinate transformations
- AGPL licensing requires open-sourcing your entire application for network services (SaaS), or purchasing a commercial license
- Implementation challenges include C bindings, global state, extreme latitude edge cases, and Delta T uncertainty for historical dates
- For most application developers, an astrology API delivers the same calculation precision without the integration burden

Building astrology features into your app? [RoxyAPI](/products "RoxyAPI product catalogue across astrology, tarot, numerology, I-Ching, dreams, crystals, and angel numbers") provides production-ready astrology (Western, Vedic, KP), tarot, numerology, I-Ching, dreams, crystals, and angel numbers. That is 12 domains and 145+ endpoints behind one API key, with remote MCP servers per domain. Explore the [documentation](/docs "RoxyAPI developer documentation, guides, and SDK references") or check [pricing](/pricing "RoxyAPI pricing and plan tiers") to start building.

## Frequently Asked Questions

**Q: What is the Swiss Ephemeris and why do developers use it?**
A: The Swiss Ephemeris is an open-source astronomical calculation library developed by Astrodienst AG in Zurich. It computes planetary positions, house cusps, eclipses, and other astronomical data with sub-milliarcsecond precision. Developers use it because it is the most accurate and comprehensive ephemeris library available, built on NASA JPL planetary data spanning 13,000 years.

**Q: How accurate is the Swiss Ephemeris compared to NASA data?**
A: In its default compressed mode, the Swiss Ephemeris matches NASA JPL Development Ephemeris (DE431) to within 0.001 arc seconds (1 milliarcsecond). When reading JPL files directly, the precision is identical. The built-in Moshier mode is less precise at about 1 arc second for planets, but this is still far more accurate than needed for any astrological application.

**Q: Is the Swiss Ephemeris free to use in commercial software?**
A: Not without conditions. The Swiss Ephemeris is dual-licensed under AGPL and a commercial license. AGPL requires you to open-source your entire application if it is accessible over a network (any web app or API). For commercial or proprietary software, you need to purchase a commercial license from Astrodienst AG. Many developers discover this requirement after building their product.

**Q: What programming languages can use the Swiss Ephemeris?**
A: The Swiss Ephemeris is written in C, but ports and bindings exist for Python (pyswisseph), Java (Thomas Mack port), PHP, Perl, and JavaScript/WebAssembly. The quality and maintenance status of these bindings varies. Each binding introduces its own build complexity and potential for platform-specific issues.

**Q: Does RoxyAPI use Swiss Ephemeris?**
A: No. RoxyAPI uses Roxy Ephemeris, an independent in-house calculation engine verified against NASA JPL Horizons with sub-arcminute accuracy and no AGPL restrictions. It uses pure analytical computation with zero file-based ephemeris reads, designed for concurrent API workloads. Full methodology documentation is available at [roxyapi.com/methodology](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against").

**Q: What is the difference between tropical and sidereal calculations in the Swiss Ephemeris?**
A: Tropical positions (Western astrology) are relative to the spring equinox. Sidereal positions (Vedic/Jyotish astrology) are relative to the fixed stars. The Swiss Ephemeris supports both, with 40+ predefined ayanamsha systems (Lahiri, Krishnamurti, Raman, Fagan-Bradley, and many more) that define the exact offset between the two zodiacs. You set the sidereal mode before calculations using `swe_set_sid_mode()`.

**Q: How many house systems does the Swiss Ephemeris support?**
A: The Swiss Ephemeris supports 25+ house systems including Placidus, Koch, Regiomontanus, Campanus, Equal, Whole Sign, Porphyry, Morinus, Alcabitius, Topocentric (Polich-Page), and many more. Each system uses different mathematical projections to divide the sky into 12 houses. Placidus and Koch are undefined at extreme latitudes (beyond the Arctic/Antarctic circles), which requires fallback handling in production software.

**Q: Can I use the Swiss Ephemeris for Vedic astrology features like nakshatras and dashas?**
A: The Swiss Ephemeris provides the foundational planetary positions in sidereal coordinates, but it does not directly compute higher-level Vedic astrology concepts like nakshatras, Vimshottari dasha periods, yogas, or divisional charts. You need to build that logic on top of the sidereal positions the library returns. This is a significant additional development effort beyond integrating the ephemeris itself.

**Q: What is Delta T and why does it matter for astrology calculations?**
A: Delta T is the difference between uniform atomic time (Terrestrial Time) and Earth rotation time (Universal Time). Earth rotation is irregular, so the two diverge over time. For modern dates, Delta T is well-known (about 69 seconds in 2024). For historical dates before 1600 CE, Delta T uncertainty grows to minutes or even hours, which directly affects Moon position calculations. The Swiss Ephemeris provides multiple Delta T models, but developers must understand that ancient chart calculations carry inherent uncertainty.

**Q: Should I integrate the Swiss Ephemeris directly or use an astrology API?**
A: For most application developers, an API is the better choice. Direct integration requires C compilation, ephemeris file management, global state handling, edge case coverage, accuracy testing, and AGPL license compliance. RoxyAPI uses [Roxy Ephemeris](/methodology "RoxyAPI calculation methodology, gold-standard tests, and sources we verify against"), its own independent calculation engine (not Swiss Ephemeris), verified against NASA JPL Horizons. It abstracts ephemeris complexity behind HTTP endpoints, letting you get precise planetary positions, house cusps, aspects, and Vedic calculations with a single request.