# Swiss Ephemeris API

Swiss Ephemeris is the de-facto standard for astronomical calculation in astrology: Astrodienst (astro.com), Solar Fire, Kerykeion and most serious software are built on it. It reads **NASA JPL's DE431 ephemeris** and delivers sub-arcsecond accuracy. AstroWay API gives you direct HTTP access to it — no C library to compile, no `.se1` files to download, no memory management. One POST request, JSON back.

## Why Swiss Ephemeris over an API

Self-hosting Swiss Ephemeris means: build the C library (or a WASM bundle), host a few hundred megabytes of `.se1` files, keep them current, and implement house cusps, aspects and phases yourself. Over an API all of that is someone else's problem:

- **Zero infrastructure** — no binaries, no ephemeris files, no cold starts. Calculation runs server-side on the same engine Astrodienst uses.
- **Sub-arcsecond accuracy** — `< 0.1″` against Astrodienst's reference `swetest` CGI, verified on {siteMeta.snapshotCount} frozen snapshot tests on every deploy.
- **Full date range** — DE431 covers **13201 BCE – 17191 CE**, so historical and far-future charts compute without precision loss.
- **More than positions** — on top of the ephemeris you immediately get house cusps (15 systems), aspects, eclipses, transits and progressions — the parts you'd have to write yourself when self-hosting.

<Aside type="tip">
Engine accuracy is triangulated against three independent sources (swetest CGI, Kerykeion, Prokerala) plus the **NASA 5-Millennium Eclipse Catalog**. Numbers and method on the <a href="/en/accuracy/">Accuracy</a> page.
</Aside>

## What runs on Swiss Ephemeris

| Endpoint | Credits | Returns |
|---|---|---|
| `/v1/chart` | 20 | Full chart: planets + houses + aspects |
| `/v1/planets` | 10 | Geocentric planet positions (longitude, latitude, speed, retrograde) |
| `/v1/houses` | 10 | House cusps — 15 systems (Placidus, Koch, Whole Sign, Equal…) |
| `/v1/transits` | 50 | Transits to a natal chart for a given date |
| `/v1/progressions` | 50 | Secondary progressions (day = year) |
| `/v1/eclipses` | 20 | Solar & lunar eclipses (verified vs NASA Catalog) |
| `/v1/moon-phase` | 10 | Moon phase, illumination, next quarters |
| `/v1/fixed-stars` | 20 | Planet conjunctions with fixed stars |

This is part of {siteMeta.endpoints} platform endpoints — full list in the <a href="/docs/api/">API reference</a>.

## Example

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/planets \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "date": "1990-07-14",
        "time": "14:30:00",
        "timezoneOffset": 3,
        "latitude": 50.4501,
        "longitude": 30.5234
      }'
    ```
  </TabItem>
  <TabItem label="Node.js">
    ```ts
    const r = await fetch('https://api.astroway.info/v1/planets', {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.ASTROWAY_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        date: '1990-07-14',
        time: '14:30:00',
        timezoneOffset: 3,
        latitude: 50.4501,
        longitude: 30.5234,
      }),
    });
    const { data } = await r.json();
    console.log(`Sun: ${data.planets.sun.sign} ${data.planets.sun.degree.toFixed(4)}°`);
    ```
  </TabItem>
  <TabItem label="Python">
    ```python

    r = requests.post(
        'https://api.astroway.info/v1/planets',
        headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY'], 'Content-Type': 'application/json'},
        json={
            'date': '1990-07-14',
            'time': '14:30:00',
            'timezoneOffset': 3,
            'latitude': 50.4501,
            'longitude': 30.5234,
        },
    )
    data = r.json()['data']
    print(f"Sun: {data['planets']['sun']['sign']} {data['planets']['sun']['degree']:.4f}°")
    ```
  </TabItem>
</Tabs>

## Who uses it

- **Astrology-app developers** — sub-arcsecond positions without self-hosting the C library
- **AI agents** — accurate ephemeris as grounding for LLMs (via the MCP server)
- **Researchers** — bulk calculation across the full DE431 historical range
- **Migrating off self-host** — drop-in replacement for a local `swisseph` build over HTTP, same precision

## Pricing

Planet positions (`/v1/planets`) — **10 credits**, full chart (`/v1/chart`) — **20**. The Free tier ({siteMeta.endpoints}+ endpoints, 10,000 credits/mo) covers roughly 1,000 planet requests a month, no card required.

<CardGrid>
  <LinkCard title="Accuracy →" href="/en/accuracy/" description="Triangulation, NASA validation, snapshot tests" />
  <LinkCard title="Quick start" href="/en/getting-started/" description="First request in 5 minutes" />
  <LinkCard title="Pricing" href="/en/pricing/" description="From free to Enterprise" />
</CardGrid>