# Swiss Ephemeris API

Swiss Ephemeris — де-факто стандарт астрономічних розрахунків в астрології: на ньому тримаються Astrodienst (astro.com), Solar Fire, Kerykeion та більшість серйозного софту. Він читає ефемериди **DE431 від NASA JPL** і дає субсекундну точність. AstroWay API дає до нього прямий HTTP-доступ — без компіляції C-бібліотеки, без завантаження `.se1` файлів, без керування пам'яттю. Один POST-запит, JSON у відповідь.

## Навіщо Swiss Ephemeris через API

Self-host Swiss Ephemeris означає: зібрати C-бібліотеку (або WASM-білд), розмістити кількасот мегабайт `.se1` файлів, тримати їх в актуальному стані й самому реалізувати куспіди будинків, аспекти, фази. Через API все це — чужий клопіт:

- **Нуль інфраструктури** — жодних бінарників, файлів ефемерид чи cold-start затримок. Розрахунок виконується server-side на тому самому движку, що й Astrodienst.
- **Субсекундна точність** — `< 0.1″` проти еталонного `swetest` CGI від Astrodienst, верифіковано на {siteMeta.snapshotCount} заморожених snapshot-тестах при кожному деплої.
- **Повний діапазон дат** — DE431 покриває **13201 BCE – 17191 CE**, тож історичні й далекі майбутні карти рахуються без втрати точності.
- **Не лише позиції** — поверх ефемерид одразу доступні куспіди будинків (15 систем), аспекти, затемнення, транзити, прогресії — те, що при self-host довелося б писати самому.

<Aside type="tip">
Точність двигуна триангульована проти трьох незалежних джерел (swetest CGI, Kerykeion, Prokerala) + проти **NASA 5-Millennium Eclipse Catalog**. Деталі й цифри — на сторінці <a href="/accuracy/">Точність розрахунків</a>.
</Aside>

## Що рахується на Swiss Ephemeris

| Ендпоінт | Кредити | Що повертає |
|---|---|---|
| `/v1/chart` | 20 | Повна карта: планети + будинки + аспекти |
| `/v1/planets` | 10 | Геоцентричні позиції планет (довгота, широта, швидкість, ретроградність) |
| `/v1/houses` | 10 | Куспіди будинків — 15 систем (Placidus, Koch, Whole Sign, Equal…) |
| `/v1/transits` | 50 | Транзити до натальної карти на задану дату |
| `/v1/progressions` | 50 | Вторинні прогресії (день = рік) |
| `/v1/eclipses` | 20 | Сонячні й місячні затемнення (verified vs NASA Catalog) |
| `/v1/moon-phase` | 10 | Фаза Місяця, освітленість, наступні квартилі |
| `/v1/fixed-stars` | 20 | Кон'юнкції планет із нерухомими зорями |

Це частина {siteMeta.endpoints} ендпоінтів платформи — повний перелік у <a href="/docs/api/">API-довіднику</a>.

## Приклад

<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>

## Хто використовує

- **Розробники астрозастосунків** — субсекундні позиції без self-host C-бібліотеки
- **AI-агенти** — точні ефемериди як grounding для LLM (через MCP-сервер)
- **Дослідники** — масові розрахунки на історичному діапазоні DE431
- **Міграція з self-host** — заміна локального `swisseph` на HTTP без втрати точності

## Вартість

Позиції планет (`/v1/planets`) — **10 кредитів**, повна карта (`/v1/chart`) — **20**. На Free тарифі ({siteMeta.endpoints}+ ендпоінтів, 10 000 кредитів/міс) — близько 1000 запитів планет на місяць безкоштовно, без картки.

<CardGrid>
  <LinkCard title="Точність розрахунків →" href="/accuracy/" description="Триангуляція, NASA-валідація, snapshot-тести" />
  <LinkCard title="Швидкий старт" href="/getting-started/" description="Перший запит за 5 хвилин" />
  <LinkCard title="Тарифи" href="/pricing/" description="Від безкоштовного до Enterprise" />
</CardGrid>