This is the full developer documentation for AstroWay API
# Огляд
> Що таке AstroWay API, для кого він, які задачі розв'язує.
import { siteMeta } from '../../data/site-meta';
import GetApiKeyBlock from '../../components/redesign/GetApiKeyBlock.astro';
**AstroWay API** — це професійний backend для астрологічних обчислень як сервіс.
{siteMeta.endpoints} ендпоінтів на базі Swiss Ephemeris (WASM), з покриттям технік, яких немає у жодного конкурента: гармоніки, драконічні карти, CCG, сектори Гоклена, повний Human Design, ректифікація.
## Для кого це
1. **Розробники астрологічних застосунків** (web, mobile), яким потрібні точні й різноманітні розрахунки без власної обчислювальної інфраструктури.
2. **AI-компанії**, що вбудовують астрологічні функції — є нативний MCP-сервер для Claude, ChatGPT та інших агентів.
3. **Професійні астрологи**, які будують власні інструменти або скрипти для клієнтів.
4. **Дослідники**, яким потрібен програмний доступ до обчислень для статистичних досліджень.
5. **Контент-платформи**, що додають астрологічні фічі поверх існуючого продукту.
## Для кого це **не**
- Горокопні віджети «рак на сьогодні» без контролю — AI-інтерпретації та гороскопи є (`/interpret/*`, `/horoscope/*`), але вони спроектовані як API для розробників, не як готовий віджет.
- Ведична астрологія як основна спеціалізація — для Vedic-first проєктів (Dasha-системи, Panchang, KP) Prokerala та VedicAstroAPI сильніші. Для західної астрології + Human Design + рідкісних технік (ректифікація, гармоніки, CCG) AstroWay — beats them. Дивись /compare/.
- Таро/нумерологія — тільки астрологія і Human Design. I-Ching є як бонусний ендпоінт.
## Що робить AstroWay унікальним
### 1. Рідкісні техніки в API-форматі
| Техніка | Навіщо |
|---|---|
| **Гармонійні карти** (H2–H180) | Дослідницька астрологія (метод Джона Аддея) |
| **Драконічна карта** | Кармічна/душевна астрологія |
| **CCG (Cyclo-Carto-Graphy)** | Прогресована астрокартографія — преміум-техніка Джима Льюїса |
| **Сектори Гоклена** | Статистична астрологія, академічне використання |
| **Третинні прогресії** | Третій тип прогресій — нішева, але цінується |
| **Антисції / контр-антисції** | Класична елліністична техніка — відродження традиційних шкіл |
| **Паралельні аспекти** | Аспекти по декалінації — просунуті практики |
| **Ректифікація через API** | Корекція часу народження — надвисока цінність |
| **Планетарні цикли** (кон'юнкції) | Мундайн-астрологія — світові події |
| **Циклічний індекс Барбо** | Мундайн-астрологія |
| **Мінімум Алголь** | Часи нерухомих зір — електіональна астрологія |
| **Лінії локального простору** | Феншуй-подібна напрямна астрологія |
| **Ланцюжки диспозиції** | Графи керування — класична техніка |
| **Альмутен figuris** | Середньовічна техніка — традиційне відродження |
### 2. Точність Swiss Ephemeris — той самий движок, що в Solar Fire ($495), Kepler ($995), Astro Gold
Той самий Swiss Ephemeris (LGPL), яким користуються професійні астрологи в Solar Fire, Kepler, Astro Gold і Janus уже 30+ років — тільки в WASM-збірці й як REST API, без посередницької націнки. Точність:
- Планетарні позиції: ±1 кутова секунда vs NASA JPL ephemeris
- Куспіди будинків: ±1 кутова мінута
- Валідація проти Zet 9, Solar Fire (proprietary ephemeris), Astrodienst swetest CGI (Astro.com), Kepler, Astro Gold — розбіжностей у межах похибки методу (≤0.1″).
### 3. {siteMeta.endpoints} ендпоінтів — глибоке покриття західних технік
{siteMeta.westernCount} обчислювальних ендпоінтів західної астрології (4 школи Hellenistic, modern psychological, evolutionary, cosmobiology) + AI-інтерпретації + повний Human Design. Глибина замість розпорошування по десятках напрямків.
## Архітектура
```
Твій застосунок
↓ HTTPS + X-Api-Key
api.astroway.info/v1/*
↓
Node.js + Express + Swiss Ephemeris (WASM)
↓
Розрахунок і повернення JSON
```
- Розрахунки виконуються **на сервері** — ніяких WASM-блобів на фронтенді твого застосунку, ніяких ліцензійних питань Swiss Ephemeris.
- Стан на стороні сервера не зберігається — кожен запит самодостатній. Ніякого витоку даних про клієнтів.
- Ключі API прив'язані до плану, rate limit і денного балансу кредитів. Моніторинг через dashboard.
## Далі
- [Швидкий старт](/getting-started/) — перший запит за 5 хвилин
- [Автентифікація](/authentication/) — як отримати і зберігати ключ
- [Кредити та ліміти](/rate-limits-credits/) — як працює білінг
- [Документація API](/docs/api/) — усі ендпоінти з інтерактивним playground
# Швидкий старт
> Створи ключ, постав SDK і зроби перший запит до AstroWay API за п'ять хвилин.
import { siteMeta } from '../../data/site-meta';
import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
import GetApiKeyBlock from '../../components/redesign/GetApiKeyBlock.astro';
П'ять хвилин від реєстрації до повної натальної карти в JSON. Покриває install SDK, перший запит, заголовки відповіді, автентифікацію та обробку помилок.
1. ### Згенеруй API ключ
Зайди в [dashboard](https://api.astroway.info/dashboard/sign-up) і натисни **Generate key**. Безкоштовний тариф дає **10 000 кредитів/міс назавжди** — без введення картки. Ключі починаються з:
- `aw_live_*` — production, реальні чарджі
- `aw_test_*` — sandbox, без списання кредитів, детермінована відповідь
2. ### Постав SDK
API — звичайний REST + JSON, тож SDK не обов'язковий. **MCP сервер** (`@astroway/mcp`) вже зрелізений для AI-агентських інтеграцій. **TypeScript і Python SDK** у roadmap (auto-gen з OpenAPI 3.1) — поки що native HTTP.
```bash frame="terminal"
# SDK не потрібен — лише curl та ключ:
export AW_KEY="aw_test_demo_replaceme"
```
```bash frame="terminal"
# native fetch — Node 18+ або браузер. SDK у roadmap.
# Альтернатива: openapi-typescript-codegen з нашого OpenAPI 3.1
export AW_KEY="aw_test_demo_replaceme"
```
```bash frame="terminal"
pip install requests # або httpx — SDK у roadmap
export AW_KEY="aw_test_demo_replaceme"
```
```bash frame="terminal"
composer require guzzlehttp/guzzle
# SDK у roadmap, поки що — Guzzle + raw HTTP
```
```bash frame="terminal"
# Для AI-агентів — Claude Desktop, Cursor IDE, Windsurf,
# VS Code (llm CLI), GPT з MCP через OpenAI Realtime API,
# або будь-який MCP-сумісний клієнт:
npx -y @astroway/mcp # 700+ tools, OpenAPI auto-sync
```
3. ### Зроби перший запит
Розрахунок натальної карти для **24 серпня 1991, 16:30 EEST, Київ**:
```bash frame="terminal" title="first-request.sh"
curl -X POST https://api.astroway.info/v1/chart \
-H "X-Api-Key: $AW_KEY" \
-H "Content-Type: application/json" \
-d '{
"birthDate": "1991-08-24T16:30:00+03:00",
"latitude": 50.4501,
"longitude": 30.5234,
"houseSystem": "placidus"
}'
```
```ts title="first-request.ts"
// native fetch — Node 18+ / Bun / Deno / browser. TS SDK у roadmap.
const r = await fetch('https://api.astroway.info/v1/chart', {
method: 'POST',
headers: {
'X-Api-Key': process.env.AW_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
birthDate: '1991-08-24T16:30:00+03:00',
latitude: 50.4501,
longitude: 30.5234,
houseSystem: 'placidus',
}),
});
const { data: chart } = await r.json();
console.log(chart.planets[0]); // { id: 0, name: 'Sun', longitude: 151.12, ... }
```
```python title="first_request.py"
# requests або httpx — SDK у roadmap.
import os, requests
r = requests.post(
'https://api.astroway.info/v1/chart',
headers={'X-Api-Key': os.environ['AW_KEY']},
json={
'birthDate': '1991-08-24T16:30:00+03:00',
'latitude': 50.4501,
'longitude': 30.5234,
'houseSystem': 'placidus',
},
)
chart = r.json()['data']
print(chart['planets'][0])
```
```php title="first-request.php"
'https://api.astroway.info/v1/']);
$r = $aw->post('chart', [
'headers' => ['X-Api-Key' => getenv('AW_KEY')],
'json' => [
'birthDate' => '1991-08-24T16:30:00+03:00',
'latitude' => 50.4501,
'longitude' => 30.5234,
'houseSystem' => 'placidus',
],
]);
$chart = json_decode($r->getBody(), true);
echo $chart['planets']['sun']['sign'];
```
4. ### Розбери відповідь
Кожна відповідь — JSON з планетами, будинками, аспектами та `meta`-блоком (cache hit, credits, engine version).
```json title="response.json"
{
"planets": {
"sun": { "sign": "virgo", "longitude": 1.123847, "house": 9 },
"moon": { "sign": "libra", "longitude": 14.892731, "house": 10 },
"asc": { "sign": "capricorn", "longitude": 7.402891 },
"mc": { "sign": "libra", "longitude": 28.117203 }
},
"houses": [ /* 12 cusps */ ],
"aspects": [ /* 24 items, computed orbs */ ],
"meta": {
"engine": "swisseph",
"precision": "sub-arcsecond",
"credits_used": 20,
"cache": "MISS"
}
}
```
```http
HTTP/2 200
content-type: application/json
x-credits-used: 20
x-credits-remaining: 9980
x-credits-reset: 2026-06-01T00:00:00Z
x-ratelimit-limit: 600
x-ratelimit-remaining: 599
x-request-id: req_01HZ4M2N8K3PQRTV
x-cache: MISS
```
5. ### Перевір баланс
Dashboard показує usage в реальному часі: [api.astroway.info/dashboard](https://api.astroway.info/dashboard). Або через API:
```bash frame="terminal"
curl https://api.astroway.info/v1/usage \
-H "X-Api-Key: $AW_KEY"
```
## Authentication
AstroWay API автентифікує запити через заголовок **`X-Api-Key`**. Bearer-токени та query-string ключі не підтримуються.
```bash frame="terminal"
curl -H "X-Api-Key: aw_live_..." https://api.astroway.info/v1/health
```
| Тип ключа | Префікс | Поведінка |
|---|---|---|
| Production | `aw_live_*` | Виставляє реальні кредити з акаунту |
| Sandbox | `aw_test_*` | Детермінована мокова відповідь, без charge |
| Restricted (Pro+) | `aw_live_*` з обмеженням | Обмежений на конкретні endpoints / IP / RPS |
Ключі обертаються без downtime — старий ключ продовжує працювати **24 години** після генерації нового. Деталі: [/authentication/](/authentication/).
## Errors
Усі помилки повертаються з JSON-тілом і HTTP-статусом. Поле `error.code` стабільне для скриптів, `error.message` локалізоване.
```json title="error-response.json"
{
"error": {
"code": "invalid_birth_time",
"message": "birthDate must be ISO-8601 with timezone offset",
"field": "birthDate",
"docs_url": "https://api.astroway.info/errors/#invalid_birth_time"
}
}
```
Найчастіші коди:
- `invalid_birth_time` (400) — дата не в ISO-8601 з offset
- `place_required` (400) — широта/довгота відсутні або поза межами
- `insufficient_credits` (402) — місячний баланс вичерпано
- `rate_limited` (429) — повертається з заголовком `Retry-After: `
- `internal_calc_error` (500) — помилка ефемерид; авто-retry на стороні SDK
Повний список і semantic: [/errors/](/errors/).
## Rate limits
| Тариф | Quota |
|---|---|
| Free | 10 req/min |
| Indie | 30 req/min |
| Starter | 120 req/min |
| Pro | 400 req/min |
| Business | 1 000 req/min |
| Enterprise | custom |
Перевищення → `429` з `Retry-After` (sec). Офіційні SDK мають exponential-backoff retries за замовчуванням. Деталі: [/rate-limits-credits/](/rate-limits-credits/).
## Далі
- [Автентифікація](/authentication/) — best practices, ротація ключів, sandbox mode
- [Кредити та ліміти](/rate-limits-credits/) — таблиця вартості, rate limiting, overage
- [Приклади: натальна карта](/examples/natal/) — детальний розбір `/v1/chart`
- [Повна API reference](/docs/api/) — усі {siteMeta.endpoints} ендпоінтів з playground
# Автентифікація
> Як створювати, зберігати і ротувати API-ключі AstroWay. Best practices і типові помилки.
import { siteMeta } from '../../data/site-meta';
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import GetApiKeyBlock from '../../components/redesign/GetApiKeyBlock.astro';
Майже всі запити до AstroWay API автентифікуються через header `X-Api-Key`. Винятки: 14 ендпоінтів `/v1/reference/*` (signs, planets, houses, aspects, …) працюють публічно без ключа з обмеженням 30 запитів / годину на IP.
Для всіх **обчислювальних ендпоінтів `/v1/*`** (chart, synastry, transits, /reports, /tarot тощо) — лише `X-Api-Key`. Для **користувацьких операцій `/v1/me/*`** (`GET /me`, `DELETE /me/account`) — Bearer JWT, виданий через `/v1/auth/login`. OAuth/session-cookies на публічному API не використовуються. **Reference-словники `/v1/reference/*`** — без ключа, безкоштовно (канонічні lookup-таблиці).
## Формат ключа
```
aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
```
- `aw_live_` — production, списує кредити з балансу
- `aw_test_` — sandbox, запити повертають стабовий відгук (або мінімальний реальний розрахунок), **не списують кредити**, відмічені в dashboard окремо
- Після префікса — 32 символи base62, криптографічно випадкові
- Ключ показується в чистому вигляді **лише один раз** при створенні. Далі в dashboard — тільки перші й останні 4 символи.
## Заголовок запиту
```http
POST /v1/chart HTTP/1.1
Host: api.astroway.info
X-Api-Key: aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
Content-Type: application/json
```
## Postman collection
Якщо для тебе зручніше Postman, ніж curl/SDK — є готова collection з усіма {siteMeta.endpoints} endpoints, перерозбита по 55 теках за OpenAPI tags, з підставленими прикладами запитів. Auth налаштований на collection-рівні: вставляєш ключ в `apiKey` variable один раз, всі запити підхоплюють.
- **Published docs:** [documenter.getpostman.com/view/54689779/2sBXqNmy3n](https://documenter.getpostman.com/view/54689779/2sBXqNmy3n)
- **Public workspace:** [postman.com/astroway-info/astroway-api](https://www.postman.com/astroway-info/astroway-api)
- **Скачати JSON:** [astroway-api.json](/postman/astroway-api.json) (≈ 5 MB)
- **Run in Postman:** [](https://god.gw.postman.com/run-collection/54689779-2sBXqNmy3n?action=collection/fork&source=rip_markdown)
Collection auto-generated з [OpenAPI spec](https://api.astroway.info/v1/openapi.json) — оновлюється з кожним деплоєм.
## Створення і керування ключами
Через dashboard:
- [api.astroway.info/dashboard/keys](https://api.astroway.info/dashboard/keys)
- Можна мати до **10 активних ключів** на акаунт одночасно
- Кожен ключ має label (наприклад `production-backend`, `ci-tests`, `local-dev`)
Через API (для self-service інтеграцій):
```bash frame="terminal"
curl -X POST https://api.astroway.info/v1/keys \
-H "X-Api-Key: aw_live_master_key" \
-H "Content-Type: application/json" \
-d '{"label": "ci-tests", "mode": "test"}'
```
```ts
// Equivalent через @astroway/sdk: aw.client.POST('/keys', { body: { label, mode } })
const r = await fetch('https://api.astroway.info/v1/keys', {
method: 'POST',
headers: {
'X-Api-Key': process.env.ASTROWAY_MASTER_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({ label: 'ci-tests', mode: 'test' }),
});
const { data: created } = await r.json();
console.log(created.key); // shown once — store it now
```
```python
# Equivalent через `astroway` (PyPI): aw.post('/keys', body={'label': ..., 'mode': ...})
import os, requests
r = requests.post(
'https://api.astroway.info/v1/keys',
headers={'X-Api-Key': os.environ['ASTROWAY_MASTER_KEY']},
json={'label': 'ci-tests', 'mode': 'test'},
)
created = r.json()['data']
print(created['key']) # shown once — store it now
```
```php
'https://api.astroway.info/v1/']);
$r = $aw->post('keys', [
'headers' => ['X-Api-Key' => getenv('ASTROWAY_MASTER_KEY')],
'json' => ['label' => 'ci-tests', 'mode' => 'test'],
]);
$created = json_decode($r->getBody(), true);
echo $created['key']; // shown once — store it now
```
## Best practices
### 1. Ніколи не клади ключ у фронтенд
Ключ — секрет backend-рівня. Якщо він потрапляє в JS, що виконується в браузері користувача — його видно в DevTools і він витече.
**Правильно:** свій backend тримає ключ, фронтенд б'ється в твій backend, твій backend — в AstroWay API.
**Неправильно:**
```ts
// ❌ НЕ РОБИ ТАК
fetch('https://api.astroway.info/v1/chart', {
headers: { 'X-Api-Key': 'aw_live_...' }, // видно в браузері
});
```
### 2. Environment variables, не hardcode
```bash
# .env (в .gitignore)
ASTROWAY_API_KEY=aw_live_...
```
```ts
// у коді
const key = process.env.ASTROWAY_API_KEY;
if (!key) throw new Error('ASTROWAY_API_KEY is not set');
```
### 3. Окремі ключі на різні середовища
- `production-backend` — продакшен
- `staging-backend` — staging
- `ci-tests` — CI/CD pipeline
- `local-dev-maksym` — локальна розробка кожного розробника
Якщо один ключ скомпрометовано — revoke саме його, інші продовжують працювати.
### 4. Ротація
Рекомендована частота — **раз на 90 днів**. Або негайно, якщо є підозра на витік.
Ротація без downtime:
1. Створи новий ключ з тим самим label + `-v2`
2. Розгорни його в прод (паралельно зі старим)
3. Переконайся, що usage тече на новий ключ (dashboard)
4. Revoke старий
### 5. Моніторинг usage
Dashboard показує запити по ключах окремо. Якщо раптом один ключ почав робити в 10× більше запитів, ніж зазвичай — це сигнал перевірити.
Можна поставити alert: `Settings → Notifications → Alert when daily credits > X`.
## Помилки автентифікації
| Код | Значення |
|---|---|
| `401 Unauthorized` | Header `X-Api-Key` відсутній або ключ невалідний |
| `403 Forbidden` | Ключ валідний, але не має scope для цієї дії (наприклад, звичайний ключ намагається керувати іншими ключами) |
| `402 Payment Required` | Кредити закінчились (на Free) або передплата неактивна |
| `429 Too Many Requests` | Перевищено rate limit (10/60/300 req/min залежно від плану) |
Приклад `401`:
```json
{
"error": {
"code": "invalid_api_key",
"message": "The API key provided is invalid or has been revoked.",
"request_id": "01HXY2A7ZM..."
}
}
```
## Sandbox mode
Ключі з префіксом `aw_test_` працюють у sandbox:
- Не списують кредити
- Повертають стабовий або мінімальний реальний відгук
- Не впливають на статистику production
- Доступні ендпоінти — ті ж самі
Корисно для CI/CD, e2e тестів і локальної розробки. Створюється через dashboard одним кліком.
## Далі
- [Кредити та ліміти](/rate-limits-credits/) — як працює білінг і rate limiting
- [Помилки](/errors/) — повний перелік error-кодів
# Сторінку не знайдено
> Здається, ця зірка згасла — сторінки за цією адресою немає.
import { siteMeta } from '../../data/site-meta';
import { LinkCard, CardGrid } from '@astrojs/starlight/components'
404
Здається, ця зірка згасла — сторінки за цією адресою немає. Можливо, посилання застаріло або URL містить друкарську помилку.
# Точність розрахунків
> AstroWay API — верифікована точність до 0.1 кутової секунди проти еталону Swiss Ephemeris. Триангуляція проти swetest CGI, Kerykeion і Prokerala. Regression-набір із {siteMeta.snapshotCount} snapshot-ів.
import { siteMeta } from '../../data/site-meta';
import { Aside, Badge } from '@astrojs/starlight/components';
## TL;DR
AstroWay API використовує **Swiss Ephemeris** (офіційний C-код від Astrodienst,
творців astro.com) — той самий движок, на якому професійні астрологи 30+ років
працюють у **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/міс) і Janus**.
Ми зібрали його у WebAssembly і виставили REST API-шаром, без посередницької
націнки. Кожен із базових розрахункових ендпоінтів покритий regression
snapshot-тестами; точність двигуна верифікована через **triangulation** з трьома
незалежними джерелами + проти **NASA 5-Millennium Eclipse Catalog**:
- **Планетні позиції**: `< 0.1 arcsec` vs офіційного swetest CGI Astrodienst
- **Куспиди домів Placidus**: `0.000"` exact match
- **Затемнення**: `< 1 хвилина` vs NASA Eclipse Catalog
- **ACG лінії**: `< 1.5 км` на екваторі vs swetest
- **Sunrise/sunset**: `< 10 секунд` vs timeanddate.com
- **Moon VOC, ingresses, planet conjunctions**: точність до частки секунди
## Двигун
| Компонент | Значення |
|-----------|----------|
| Бібліотека | Swiss Ephemeris C code (aloistr/swisseph) |
| Версія | upstream Astrodienst C code |
| Bindings | swisseph-wasm (WebAssembly у Node.js) |
| Ephemeris | DE431 JPL ephemeris (через .se1 файли) |
| Fallback | Moshier analytical (для дат поза 1800-2399) |
| Code sharing | Shared `@/core` із app.astroway.info — один двигун, два транспорти |
## Методика
Точність перевіряється через **триангуляцію** — порівняння з трьома
незалежними джерелами:
### 1. swetest CGI (еталон)
Офіційний reference-implementation Swiss Ephemeris від самих Astrodienst —
команди, що створили **Astro.com** і обслуговує мільйони астрологів по всьому
світу. Найавторитетніше публічне джерело. Наш двигун **ідентичний**
(0.00–0.07 кутової секунди дрифту).
### 2. Kerykeion (Python)
Незалежна Python-бібліотека використовує `pyswisseph`-bindings замість нашого
WASM. Підтверджує, що наш WASM-шар не спотворює дані.
### 3. Prokerala API
Віддалений Swiss Ephemeris API (sidereal Lahiri). Systemic drift 8–17 кутових
секунд пов'язаний з різними версіями формули Lahiri ayanamsa, а **не** з
точністю двигуна.
## Результати триангуляції
| Карта | проти swetest (Astrodienst) | проти Kerykeion (Python) | проти Prokerala API |
|-------|------------------------------|---------------------------|---------------------|
| Monroe 1926 | **0.00"** | 0.19" | 16.95" (systemic) |
| Diana 1961 | **0.00"** | 0.69" | 8.18" (systemic) |
| Einstein 1879 | 0.07" | LMT-артефакт Kerykeion | 14.96" (systemic) |
## Regression-набір на рівні ендпоінтів
Кожен із базових обчислювальних ендпоінтів покритий замороженими snapshot-тестами
на 3 референсних картах (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount} snapshot-ів**.
Snapshot-suite ловить:
- **Баги мапінгу вхідних даних** — неправильний id планети, UT, система будинків
- **Пост-обробку** — округлення, конвертація одиниць, втрата знаку
- **Розбіжність дефолтів** — mean vs true node, geocentric vs topocentric
- **Schema drift** — валідація пропустила неправильну форму
- **Застарілий деплой** — prod dist не відповідає коду
Tolerance: `5e-5°` (≈0.18 кутової секунди) за замовчуванням для всіх числових полів.
## Детальні бенчмарки
### Позиції планет (тропік, проти swetest)
| Карта | Дата | Максимум drift |
|-------|------|-----------------|
| Marilyn Monroe | 1926-06-01 | **0.00"** |
| Princess Diana | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07" |
### Куспіди домів Placidus (проти swetest)
| Карта | drift ASC | drift MC | Максимум drift куспіда |
|-------|-----------|----------|-------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana | 0.000" | 0.000" | 0.000" |
### Затемнення (проти NASA 5-Millennium Catalog)
| Подія | Максимум NASA | Наш максимум | Drift |
|-------|----------------|--------------|-------|
| 2025-03-14 Lunar Total | 06:58 UT | 06:58 UT | 0.8 хв |
| 2025-03-29 Solar Partial | 10:47 UT | 10:47 UT | 0.5 хв |
| 2025-09-07 Lunar Total | 18:11 UT | 18:11 UT | 0.8 хв |
| 2025-09-21 Solar Partial | 19:41 UT | 19:42 UT | 1.0 хв |
### Астрокартографія (проти формули RA з swetest)
Усі лінії MC/IC/ASC/DSC використовують правильну формулу `longitude = RA − GMST`
(стандарт Kenneth Bowser). Drift від еталона: **< 1.5 км** на екваторі для
всіх планет.
### Схід / Захід Сонця (проти timeanddate.com)
| Локація | Дата | Параметр | Drift |
|---------|------|----------|-------|
| London | 2026-04-15 | Sunrise | 0.6 с |
| London | 2026-04-15 | Sunset | 9 с |
**Полярні локації** (|lat| > 66.5°) автоматично повертають `polarState` +
warning, що звичайні planetary hours не визначені.
### Орбіси аспектів
AstroWay використовує **змінні орбіси** per-planet (правило MIN двох планет),
як у ZET9 та astro.com. Орбіси за замовчуванням (для натальної карти):
| Аспект | Sun | Moon | Inner | Jupiter | Outer |
|--------|-----|------|-------|---------|-------|
| Conjunction | 12° | 10° | 5° | 8° | 5° |
| Sextile | 6.5° | 6° | 5° | 5° | 5° |
| Square | 10° | 8° | 5° | 7° | 5° |
| Trine | 12° | 8° | 5° | 5° | 5° |
| Opposition | 12° | 10° | 5° | 8° | 5° |
Мінорні аспекти (36°, 40°, 45°, 72°, 108°, 135°, 144°) **за замовчуванням
вимкнені**. Вмикаються явно через `ALL_ASPECTS`.
## Полярні широти
Для |lat| > 66.5° системи Placidus / Koch / Regiomontanus математично не
визначені. У таких випадках Swiss Ephemeris автоматично повертає Porphyry,
і наш API додає warning:
```json
{
"system": "P",
"warning": "Система Placidus не визначена для lat=68.96° (> 66.5°). Swiss Ephemeris підставив Porphyry..."
}
```
## Безперервна перевірка
Regression перевіряється **на кожен PR** через CI:
- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshot-ів проти референсних карт (Monroe / Diana / Einstein) + synastry / composite / davison
- `.github/workflows/api-accuracy.yml` — автозапуск на PR
- Триангуляція проти swetest CGI + Kerykeion — щотижня
- Моніторинг upstream Swiss Ephemeris через Dependabot
## Відомі обмеження
- **Дати поза діапазоном** (до 1800 і після 2399): використовується Moshier
analytical, точність ~0.1" (проти < 0.01" для SWIEPH з файлами DE431)
- **True Lilith (id=13) vs Mean Lilith (id=12)**: різниця до 12° — за дефолтом
Mean Lilith (стабільна поведінка), True Lilith доступний через
`planetIds: [13]`
- **Topocentric vs geocentric**: за замовчуванням geocentric
## Посилання
- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- Каталог затемнень NASA: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/
## Контакти
Про питання точності: пиши на support@astroway.info з даними карти
й очікуваним еталоном (astro.com або інше авторитетне джерело).
# Швидкий старт API астрології: TypeScript і Python за 5 хвилин
import { siteMeta } from '../../../data/site-meta';
> **🕓 Запис від 2026-04-14, оновлено 2026-05-09.** TS / Python / PHP SDK тепер живуть на public registries — `@astroway/sdk` (npm), `astroway` (PyPI), `astroway/sdk` (Packagist). Деталі в [changelog](/changelog/).
Ти хочеш порахувати натальну карту з коду. Ось найкоротший шлях — за 5 хвилин від нуля до робочого JSON.
## Крок 1: Отримай API-ключ (30 секунд)
Зареєструйся на [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up). Безкоштовний план: 10 000 кредитів / місяць. Без картки.
У [dashboard](https://api.astroway.info/dashboard/keys) натисни «Create key» → «Production» → скопіюй. Ключі мають вигляд `aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR`.
**Підказка:** є також sandbox-ключі з префіксом `aw_test_` — вони не списують кредити. Використовуй їх під час розробки.
## Крок 2: Встанови SDK
### TypeScript
```bash
npm install @astroway/sdk
```
### Python
```bash
pip install astroway
```
Обидва SDK покривають усі {siteMeta.endpoints} ендпоінт із типізованими запитами й відповідями.
## Крок 3: Перша натальна карта
### TypeScript
```ts
import { Astroway } from '@astroway/sdk';
const client = new Astroway({
apiKey: process.env.ASTROWAY_API_KEY!,
});
const chart = await client.chart({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3, // UTC+3, літо в Києві
latitude: 50.4501,
longitude: 30.5234,
houseSystem: 'P', // Placidus
});
console.log(`Sun: ${chart.planets[0].sign} at ${chart.planets[0].longitude}°`);
console.log(`ASC: ${chart.houses.ascendant}°`);
console.log(`Aspects: ${chart.aspects.length}`);
```
Запусти:
```bash
ASTROWAY_API_KEY=aw_live_... npx tsx chart.ts
```
### Python
```python
from astroway import Astroway
client = Astroway(api_key="aw_live_your_key_here")
chart = client.chart(
date="1990-07-14",
time="14:30:00",
timezone_offset=3,
latitude=50.4501,
longitude=30.5234,
house_system="P",
)
print(f"Sun: {chart['planets'][0]['sign']} at {chart['planets'][0]['longitude']}°")
print(f"ASC: {chart['houses']['ascendant']}°")
print(f"Aspects: {len(chart['aspects'])}")
```
Запусти:
```bash
ASTROWAY_API_KEY=aw_live_... python3 chart.py
```
## Що повертає API
Назад приходить JSON-об'єкт із чотирма основними частинами:
### planets
Масив із 12 об'єктів (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, Chiron):
```json
{
"name": "Sun",
"longitude": 111.87, // еклiптична довгота у градусах
"latitude": 0.0,
"speed": 0.955, // градусів на день (від'ємне = ретроград)
"sign": "cancer",
"signIndex": 3,
"house": 10,
"retrograde": false
}
```
### houses
Куспіди домів (12 штук), а також asc і MC:
```json
{
"system": "P",
"cusps": [12.34, 43.21, ...], // 12 значень
"ascendant": 12.34,
"mc": 280.12
}
```
### aspects
Масив аспектів між планетами:
```json
{
"planet1": "Sun",
"planet2": "Moon",
"type": "sextile", // conjunction, opposition, trine, square, sextile, quincunx
"orb": 1.36, // відхилення від точного у градусах
"applying": true
}
```
### chartSect
`"diurnal"` (Сонце над горизонтом у момент народження) або `"nocturnal"` (під горизонтом). Використовується в класичній астрології.
## Що далі
Що ще спробувати:
**Синастрія** — сумісність двох людей:
```ts
const synastry = await client.synastry({
chart1: { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
chart2: { date: '1992-03-22', time: '09:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
});
console.log(`Compatibility score: ${synastry.compatibility.score}/100`);
```
**Поточні транзити на натальну карту:**
```ts
const transits = await client.transits({
// дані народження
date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
latitude: 50.4501, longitude: 30.5234,
// дата транзиту
transitDate: '2026-04-14',
});
```
**Щоденний гороскоп із реальних транзитів:**
```ts
const horoscope = await client.horoscopeDaily({
date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
latitude: 50.4501, longitude: 30.5234,
});
console.log(horoscope.text);
```
**Повна Human Design карта:**
```ts
const hd = await client.humanDesign({
date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
latitude: 50.4501, longitude: 30.5234,
});
console.log(`${hd.type} — ${hd.strategy} — Profile ${hd.profile}`);
```
## Вартість у кредитах
- Натальна карта (`/chart`): 20 кредитів
- Синастрія: 50 кредитів
- Транзити: 50 кредитів
- Щоденний гороскоп: 20 кредитів
- Human Design: 50 кредитів
Безкоштовний план: 10 000 кредитів / місяць = 500 натальних карт, або 200 синастрій, або змішане навантаження.
## Обробка помилок
Кожна відповідь містить заголовки з кредитами:
```
X-Credits-Used: 20
X-Credits-Remaining: 4980
X-Credits-Reset: 2026-05-01T00:00:00Z
```
Коли кредити закінчуються — отримаєш `402 Payment Required`. Коли вдариш по rate-limit'у (Free: 10 запитів / хв) — `429 Too Many Requests` із заголовком `Retry-After`.
SDK кидає типізовані помилки, які можна ловити:
```ts
try {
const chart = await client.chart({ ... });
} catch (err) {
if (err.code === 'credits_exhausted') {
console.log('Upgrade plan or wait for reset');
} else if (err.code === 'rate_limit_exceeded') {
console.log(`Retry in ${err.retryAfter} seconds`);
}
}
```
## І на цьому все
Тепер у тебе є:
- Робочий API-ключ
- Встановлений SDK
- Перша натальна карта
- Достатньо прикладів, щоб додати синастрію, транзити, гороскопи
Читати далі:
- [Повний путівник «з чого почати»](/getting-started/) — більше деталей
- [Приклад: натальна карта](/examples/natal/) — глибший walkthrough
- [API reference](/docs/api/) — усі {siteMeta.endpoints} ендпоінт
# Найкращі API астрології у 2026: порівняння для розробників
import { siteMeta } from '../../../data/site-meta';
Будуєш астрологічний застосунок у 2026? Ринок уже дозрів — від саморобних обчислень ефемерид перейшли до жменьки комерційних API. Ось що варто знати до вибору.
Це не маркетинг. Це те, що хотів би побачити розробник: кількість ендпоінтів, реальні ціни, якість SDK, заяви про точність, сильні та слабкі сторони кожного API.
## Що насправді важливо в API астрології
П'ять речей мають значення під час інтеграції:
1. **Покриття** — скільки технік підтримується? Натальна карта — базова умова; мінімум потрібні синастрія, транзити, прогресії. Преміальні фічі на кшталт ректифікації чи Human Design — це вже диференціатори.
2. **Точність** — ±1 кутова секунда — стандарт Swiss Ephemeris. Гірше — і отримаєш скарги від користувачів, які перевіряють на Astrodienst.
3. **Модель тарифікації** — per-request, credit-based чи плоска місячна? Credit-based краще масштабується на змішаному навантаженні.
4. **Якість SDK** — типізовані TypeScript і Python SDK економлять години. MCP-підтримка критична, якщо будуєш AI-агентів.
5. **Документація** — OpenAPI 3.1 spec — мінімум. Інтерактивний playground — величезна економія часу.
## Основні гравці
Кілька комерційних API астрології змагаються за увагу розробників. Ландшафт приблизно ділиться на три рівні:
- **Комплексні західні + ведичні**: API, що намагаються покрити все, зазвичай із ширшим покриттям ведичної астрології, ніж західної. Сильні в nakshatras, dashas та ведичних divisional-картах, але часто слабші в сучасних західних техніках.
- **Сфокусовані західні**: API, орієнтовані на західну астрологію плюс «фірмова» фіча (Human Design, ректифікація, AI-інтерпретації). Зазвичай глибші у вузькій ніші.
- **AI-first**: API, що обгортають LLM (зазвичай GPT-4, Claude 3.5 чи Llama 3.3) навколо базових обчислень і позиціонуються як «ChatGPT для астрології». Прості у використанні, але обчислення під капотом часто поверхневі — реальної ефемериди немає, AI галюцинує дати на ±15 діб.
Де в цьому [AstroWay API](/overview/)? Сфокусована західна + Human Design + AI-інтерпретації. {siteMeta.endpoints} ендпоінт, точність Swiss Ephemeris, 12 HD-ендпоінтів, credit-based ціни.
## Порівняння віч-на-віч
| Функція | AstroWay | Типовий vedic-first | Типовий AI-first |
|---|---|---|---|
| Ендпоінти | {siteMeta.endpoints} | 40–60 | 10–20 |
| Точність | ±1" (Swiss Ephemeris) | варіативна | варіативна |
| Натальна карта | так | так | так |
| Синастрія | так (0–100 score) | часто | іноді |
| Прогресії | так (secondary + tertiary + minor) | рідко | рідко |
| Ректифікація | так (алгоритм + Trutine) | ні | ні |
| Human Design | 12 ендпоінтів | іноді базовий | рідко |
| AI-інтерпретації | 10 ендпоінтів із safety-guardrails | іноді | так |
| MCP-сервер | так (25 інструментів) | ні | іноді |
| TypeScript SDK | так (типізований) | іноді | іноді |
| Python SDK | так (context manager) | іноді | іноді |
| OpenAPI 3.1 spec | так | іноді | рідко |
| Безкоштовний тариф | 10 000 кредитів / міс | обмежений | тільки trial |
## Рідкісні техніки як диференціатор
Якщо потрібні harmonic-карти, antiscia, Gauquelin sectors або Barbault cyclic index — більшість API їх не підтримують. Це ніша, але дуже цінна для дослідницьких застосунків, традиційної астрології та академічних робіт.
AstroWay цілеспрямовано працює в цій ніші:
- **Harmonic-карти** (H2–H180) — метод дослідження за Джоном Адді
- **CCG (Cyclo-Carto-Graphy)** — прогресована астрокартографія
- **Ректифікація** — алгоритмічне уточнення часу народження
- **Gauquelin sectors** — статистична астрологія
- **Antiscia** — класична еллінська техніка
- **Disposition chains** — граф-аналіз управління
- **Повний Human Design** — 12 ендпоінтів, включно з Penta й Dream Rave
Якщо твоєму застосунку потрібно щось із цього переліку — вибір різко звужується.
## Ціноутворення на практиці
Більшість комерційних API тарифікують або per-request, або через місячну квоту. Ціна за запит виглядає дешево ($0.01–0.05 за виклик), але погано масштабується — якщо стрибне кількість користувачів, витрати вибухають.
Credit-based ціни (як у AstroWay) списують різну кількість за різну складність ендпоінта:
- 10 кредитів за просту вибірку (позиції планет)
- 20 за повну натальну карту
- 50 за синастрію
- 500 за ректифікацію
Це краще відображає реальну вартість обчислень. Малий застосунок на 1 000 натальних карт на день — близько 20 000 кредитів, Starter ($19/міс) його покриває.
## Якість SDK важить більше, ніж здається
Сирі HTTP-виклики працюють, але типізовані SDK економлять години на:
- Читанні документації, щоб згадати назви параметрів
- Лові неправильних типів до рантайму
- Автокомпліті полів відповіді в IDE
[TypeScript SDK](/getting-started/) від AstroWay покриває всі {siteMeta.endpoints} ендпоінт із повною type inference:
```ts
const chart = await client.chart({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
});
// TypeScript знає, що chart.planets має тип Planet[], а не any
for (const planet of chart.planets) {
console.log(`${planet.name} at ${planet.longitude}°`);
}
```
## MCP для AI-агентів
Якщо будуєш AI-агента (custom tools для Claude Desktop, коучинг-чатбот чи інтеграцію астрології в ChatGPT), **Model Context Protocol (MCP)** — тепер стандарт. MCP-сервер віддає твій API як tool-и, які модель може викликати напряму.
[MCP-сервер](/use-cases/ai-agents/) AstroWay надає 25 інструментів — натальні карти, синастрія, транзити, гороскопи та всі 12 HD-ендпоінтів. Налаштування:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_..."
}
}
}
}
```
Тридцять секунд — і Claude має 25 нових астрологічних інструментів.
## Вердикт
Єдиного «найкращого» API немає — усе залежить від того, що ти будуєш:
- **Застосунок зі стандартним західним функціоналом?** AstroWay або аналогічний сфокусовано-західний API.
- **Головна фіча — ведична?** Дивись на vedic-специалізовані API; у AstroWay є базовий vedic (nakshatras, divisional charts), але він не головний.
- **Будуєш AI-агента?** MCP-підтримка обов'язкова. AstroWay та ще пара API її мають.
- **Потрібні рідкісні техніки (ректифікація, Human Design, harmonics)?** AstroWay — саме для цього.
Протестуй кілька. Кожен API має безкоштовний тариф — напиши той самий ендпоінт проти трьох із них, порівняй точність, затримку й DX. Це єдиний спосіб зрозуміти, що підходить твоєму проєкту.
## Почни з AstroWay
Якщо AstroWay звучить як те, що треба:
- [Швидкий старт](/getting-started/) — перший запит за 5 хвилин
- [Тарифи](/pricing/) — безкоштовний план із 10 000 кредитами / місяць
- [API reference](/docs/api/) — усі {siteMeta.endpoints} ендпоінт із playground
# Як збудувати астрологічний застосунок: повний путівник для розробника
import { siteMeta } from '../../../data/site-meta';
> **🕓 Запис від 2026-04-14, оновлено 2026-05-09.** TS / Python / PHP SDK тепер живуть на public registries — `@astroway/sdk` (npm), `astroway` (PyPI), `astroway/sdk` (Packagist). Деталі в [changelog](/changelog/).
Хочеш зробити астрологічний застосунок. З чого почати? У цьому гайді — рішення та код: від вибору API до деплою робочого продукту.
## Питання архітектури
Перш ніж писати код, визнач: обчислення на клієнті чи на сервері?
**Клієнт** (наприклад, Swiss Ephemeris WASM у браузері):
- Плюси: без вартості за запит, працює офлайн, повний контроль
- Мінуси: ~2 МБ WASM на кожного користувача, складне ліцензування (комерційне використання Swiss Ephemeris має обмеження), ти сам супроводжуєш обчислювальний код
**Серверний API** (AstroWay, Prokerala тощо):
- Плюси: без клієнтських залежностей, малий bundle застосунку, швидко на мобілі, без ліцензійного болю
- Мінуси: вартість у кредитах за запит, затримка на «холодних» запитах
Для більшості застосунків виграє серверний API. Мобільні користувачі не чекатимуть 2 МБ WASM; з ліцензійними нюансами не варто мати справу; а сучасні API безкоштовно кешують ідентичні запити (AstroWay робить 5-хвилинний кеш із заголовком `X-Cache: HIT`).
## Вибір API
Що важить:
- **Точність** — шукай Swiss Ephemeris «під капотом» (±1 кутова секунда). Якщо API прямо цього не каже — запитай.
- **Покриття** — натал + синастрія + транзити — мінімум. Прогресії й повернення — наступний рівень. Рідкісні техніки (ректифікація, Human Design) — це диференціатор.
- **Якість SDK** — типізовані TypeScript і Python SDK економлять години.
- **Модель тарифу** — credit-based масштабується краще, ніж per-request, на змішаному навантаженні.
Для цього туторіалу візьмемо [AstroWay API](/overview/), бо він має все чотири ({siteMeta.endpoints} ендпоінт, Swiss Ephemeris, типізовані SDK, credit-based).
## Крок 1: Підняти backend
Ніколи не клич астрологічний API напряму з браузера — твій API-ключ витече. Завжди ходь через свій backend.
```bash
mkdir my-astrology-app
cd my-astrology-app
npm init -y
npm install express @astroway/sdk zod
npm install -D typescript @types/express @types/node tsx
```
Створи `src/server.ts`:
```ts
import express from 'express';
import { Astroway } from '@astroway/sdk';
import { z } from 'zod';
const app = express();
app.use(express.json());
const client = new Astroway({
apiKey: process.env.ASTROWAY_API_KEY!,
});
const BirthInput = z.object({
date: z.string(),
time: z.string(),
timezoneOffset: z.number(),
latitude: z.number(),
longitude: z.number(),
});
app.post('/api/chart', async (req, res) => {
const parsed = BirthInput.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: parsed.error });
try {
const chart = await client.chart({
...parsed.data,
houseSystem: 'P',
});
res.json(chart);
} catch (err) {
res.status(500).json({ error: String(err) });
}
});
app.listen(3000, () => console.log('http://localhost:3000'));
```
Запусти:
```bash
ASTROWAY_API_KEY=aw_test_... npx tsx src/server.ts
```
Перевірка через curl:
```bash
curl -X POST http://localhost:3000/api/chart \
-H "Content-Type: application/json" \
-d '{"date":"1990-07-14","time":"14:30:00","timezoneOffset":3,"latitude":50.4501,"longitude":30.5234}'
```
Отримуєш повну JSON-натальну карту.
## Крок 2: Frontend
Підійде будь-який фреймворк. Для прикладу — React із простою формою:
```tsx
import { useState } from 'react';
type Chart = {
planets: { name: string; longitude: number; sign: string; house: number }[];
aspects: { planet1: string; planet2: string; type: string; orb: number }[];
};
export function NatalForm() {
const [chart, setChart] = useState(null);
async function handleSubmit(formData: FormData) {
const body = Object.fromEntries(formData.entries());
const res = await fetch('/api/chart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
date: body.date,
time: body.time + ':00',
timezoneOffset: Number(body.tz),
latitude: Number(body.lat),
longitude: Number(body.lng),
}),
});
setChart(await res.json());
}
return (
);
}
```
## Крок 3: Синастрія
Сумісність — наступна очевидна фіча. Додай у `src/server.ts`:
```ts
const SynastryInput = z.object({
chart1: BirthInput,
chart2: BirthInput,
});
app.post('/api/synastry', async (req, res) => {
const parsed = SynastryInput.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: parsed.error });
const result = await client.synastry(parsed.data);
res.json({
score: result.compatibility.score,
label: result.compatibility.label,
aspects: result.crossAspects,
});
});
```
Все. Один ендпоінт, 50 кредитів за виклик, повертає score 0–100 і cross-aspects.
## Крок 4: Щоденні гороскопи
Для контент-engagement'у щоденні гороскопи — must have. AstroWay генерує їх із реальних даних транзитів:
```ts
app.post('/api/horoscope/daily', async (req, res) => {
const parsed = BirthInput.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: parsed.error });
const horoscope = await client.horoscopeDaily(parsed.data);
res.json({
text: horoscope.text,
disclaimer: horoscope.disclaimer, // обов'язково зберегти в UI!
});
});
```
**Важливо**: AI-згенерований контент містить disclaimer, який ти зобов'язаний показати користувачам (за Terms of Service). Не прибирай його.
## Крок 5: Кешування
Щоденні гороскопи однакові для всіх користувачів із одного дня народження та схожими натальними картами. Кешуй агресивно:
```ts
import { LRUCache } from 'lru-cache';
const cache = new LRUCache({ max: 1000, ttl: 86400 * 1000 });
app.post('/api/horoscope/daily', async (req, res) => {
const key = JSON.stringify(req.body);
const cached = cache.get(key);
if (cached) return res.json(cached);
const horoscope = await client.horoscopeDaily(req.body);
cache.set(key, horoscope);
res.json(horoscope);
});
```
У AstroWay також є вбудоване 5-хвилинне серверне кешування (`X-Cache: HIT`), але для довгоживучого контенту потрібен власний кеш.
## Крок 6: Деплой
Підійде будь-яка платформа. Для швидкого старту — Vercel або Railway:
```bash
# vercel.json
{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }
```
У панелі платформи виставляй env `ASTROWAY_API_KEY`.
## Планування бюджету
Якщо дійшов сюди — оціни місячне споживання кредитів перед запуском:
```
credits/month = DAU × (avg_charts_per_user × 20
+ avg_synastries × 50
+ avg_horoscopes × 20) × 30
```
Для 100 DAU з 1 картою + 1 гороскопом + 0.3 синастріями на користувача на день:
```
100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 кредитів / місяць
```
Це [план Starter](/pricing/) за $19/міс (200K кредитів).
## Що далі
Прокачані фічі, які варто додати зі зростанням:
- **Overlay транзитів** — `/v1/transits` показує поточні позиції планет на натальній карті
- **Прогресії** — `/v1/progressions` для дуг психологічного розвитку
- **Solar return** — `/v1/solar-return` на «прогноз на рік з дня народження»
- **Human Design** — [Human Design API](/products/human-design-api/) відкриває цілий новий функціональний домен
- **Астрокартографія** — `/v1/acg` мапить, де користувачеві варто жити
Кожна фіча важка в реалізації з нуля, але — один виклик API з AstroWay.
## Старт
- [Отримай безкоштовний API-ключ](/getting-started/) — 10 000 кредитів / місяць
- [Повний API reference](/docs/api/) — усі {siteMeta.endpoints} ендпоінт
- [Birth Chart API](/products/birth-chart-api/) — детальна документація ендпоінта карти
# Human Design API: будуй HD-застосунки на 12 ендпоінтах
> **🕓 Запис від 2026-04-14, оновлено 2026-05-09.** TS / Python / PHP SDK тепер живуть на public registries — `@astroway/sdk` (npm), `astroway` (PyPI), `astroway/sdk` (Packagist). Деталі в [changelog](/changelog/).
Human Design виріс із нішевої езотеричної системи 1990-х до мейнстрімної рамки особистого розвитку. Застосунки з мільйонами користувачів його нормалізували — і розробники ставлять питання: як порахувати Human Design-карту програмно?
У цьому пості — технічний бік: що таке HD-обчислення, які API їх підтримують і як вмонтувати HD-фічу у твій застосунок.
## Що таке Human Design технічно
Human Design побудований на трьох класичних системах:
- **Західна астрологія** — позиції планет у момент народження
- **I Ching** — 64 гексаграми, замаплені на 64 «ворота»
- **Чакрова система** — дев'ять «центрів» (енергетичних вузлів)
Обчислення бере дані народження і видає **bodygraph** — візуальну карту з:
- **Type** (Manifestor, Generator, Manifesting Generator, Projector, Reflector) — енергетичний сигнатур
- **Strategy** — як приймати рішення
- **Authority** — якому центру довіряти при рішеннях (Sacral, Emotional, Splenic тощо)
- **Profile** — комбінація ліній (1/3, 4/6 тощо)
- **Channels** — зв'язки між центрами, що формують особистість
- **Incarnation Cross** — призначення життя, похідне від чотирьох ключових позицій
Під капотом кожні з 64 воріт відповідають діапазону еклiптичної довготи. Довгота твоїх планет при народженні мапиться на конкретні ворота (і рядки всередині них). Розрахунок «Design» — для зсуву Сонця на 88° до народження — приблизно 3 місяці раніше.
## Дві карти: Personality та Design
Human Design використовує дві точки народження:
1. **Personality** — реальний час народження. Це «свідомий» бік.
2. **Design** — коли Сонце було на 88° до позиції народження. Це «несвідомий» бік.
Кожна активація воріт належить до одного з них. Повна карта має 13 + 13 = 26 активацій.
Саме це робить HD-обчислення важчим за стандартну астрологічну карту — ти фактично рахуєш дві карти.
## API з підтримкою Human Design
Більшість API астрології або взагалі не підтримують HD, або мають поверхневу підтримку (тільки type + strategy). Повна реалізація HD потребує:
- Мапінгу 64 воріт (lookup table)
- 6 ліній на кожні ворота (384 клітинок)
- 9 центрів із логікою defined/open
- 36 каналів (кожен з'єднує два центри)
- Обчислення Incarnation Cross
- Виведення Profile з лінії воріт Сонця + лінії воріт Землі (Personality і Design)
API, які вміють усе це, — велика рідкість. [AstroWay API](/products/human-design-api/) має 12 HD-ендпоінтів — найглибше покриття, яке ми бачили в комерційному API.
## 12 HD-ендпоінтів AstroWay
| Ендпоінт | Кредити | Що повертає |
|---|---|---|
| `/v1/human-design` | 50 | Повна HD-карта |
| `/v1/human-design/transits` | 50 | HD-транзити на задану дату |
| `/v1/human-design/compatibility` | 100 | Сумісність двох HD-карт |
| `/v1/hd/incarnation-cross` | 50 | Incarnation Cross |
| `/v1/hd/dream-rave` | 50 | Dream Rave-карта |
| `/v1/hd/hologenetic` | 50 | Hologenetic Profile |
| `/v1/hd/sensitivity` | 50 | Аналіз чутливості до часу |
| `/v1/hd/circuitry` | 20 | Аналіз контурів |
| `/v1/hd/penta` | 100 | Penta — групова динаміка 3–5 осіб |
| `/v1/hd/group-overlay` | 100 | Group overlay |
| `/v1/hd/design-date` | 10 | Розрахунок Design-дати |
| `/v1/hd/rave-new-years` | 10 | Дати Rave New Year |
## Як додати HD-фічу
Уяви, що додаєш HD у вже наявний астрологічний застосунок. Починай із головного ендпоінта:
```ts
import { Astroway } from '@astroway/sdk';
const client = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });
const hd = await client.humanDesign({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
});
console.log(`Type: ${hd.type}`); // наприклад, "Generator"
console.log(`Strategy: ${hd.strategy}`); // наприклад, "To Respond"
console.log(`Authority: ${hd.authority}`); // наприклад, "Sacral"
console.log(`Profile: ${hd.profile}`); // наприклад, "1/3"
console.log(`Defined channels: ${hd.channels.length}`);
```
Форма відповіді:
```json
{
"type": "Generator",
"strategy": "To Respond",
"notSelfTheme": "Frustration",
"authority": "Sacral",
"profile": "1/3",
"definition": "single",
"cross": {
"name": "Right Angle Cross of the Sphinx",
"quarter": "Civilization",
"gates": [1, 2, 7, 13]
},
"centers": [
{ "name": "Sacral", "defined": true },
...
],
"channels": [
{ "gate1": 34, "gate2": 20, "name": "Channel of Charisma", "type": "Generated" }
],
"personalityActivations": [...],
"designActivations": [...]
}
```
## Групова динаміка через Penta
Penta — техніка розуміння динаміки команди у групах 3–5 осіб. Це рідкість — більшість HD-калькуляторів її не пропонує. Але це золото для HR-tech, коучинг-платформ і тімбілдинг-застосунків.
```ts
const penta = await client.hdPenta({
members: [
{ date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
{ date: '1988-03-10', time: '08:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
{ date: '1985-11-22', time: '18:00:00', timezoneOffset: -5, latitude: 40.71, longitude: -74.00 },
],
});
console.log(`Penta type: ${penta.type}`);
console.log(`Defined channels in group: ${penta.definedChannels.length}`);
```
## Sensitivity — критично для точності
HD-карти чутливі до часу народження. Помилка в 10 хвилин може змінити Profile (наприклад, 1/3 → 1/4). Для користувачів, які не знають точного часу, запускай sensitivity-аналіз:
```ts
const sensitivity = await client.hdSensitivity({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
});
// sensitivity покаже, які поля зміняться при зсуві часу на ±5/15/30 хв
```
Використовуй це, щоб попереджати користувача: «На цій точності твій profile може зсунутись. Розглянь ректифікацію».
## Тарифи для HD-застосунків
Якщо будуєш HD-focused застосунок:
- Базовий користувач: 1 HD-карта при реєстрації, кешована назавжди = 50 кредитів одноразово
- Активний користувач: періодичні транзити + compatibility = ~200 кредитів/міс
- 100 DAU з помірним використанням HD: ~110 000 кредитів/міс → **Starter ($19/міс)** легко покриває
- 1 000 DAU: ~150 000 кредитів/міс → **Pro ($59/міс)**
Compatibility-запити найважчі (100 кредитів). Кешуй результати для кожної пари користувачів назавжди (вони незмінні).
## Візуалізація
Рендеринг bodygraph традиційно роблять через SVG. API повертає дані про центри й канали; ти рендериш візуал. Приклад:
```tsx
function Bodygraph({ hd }: { hd: HDChart }) {
return (
);
}
```
Координати — фіксований шаблон (кожний bodygraph має ті самі 9 центрів і 64 ворота на тих самих позиціях).
## Починай будувати HD-фічі
- [Human Design API](/products/human-design-api/) — продуктова сторінка з повним списком ендпоінтів
- [Приклад: Human Design](/examples/human-design/) — детальний walkthrough `/v1/human-design`
- [Швидкий старт](/getting-started/) — отримай безкоштовний API-ключ (до 200 HD-карт/міс на Free)
# Запуск AstroWay API: {siteMeta.endpoints} ендпоінт астрології, точність Swiss Ephemeris
import { siteMeta } from '../../../data/site-meta';
Сьогодні ми оголошуємо **AstroWay API** — обчислювальний backend для розробників, які створюють астрологічні застосунки, гороскопні продукти, функції сумісності для дейтингу та AI-агентів, які мають міркувати про карти народження.
У цій статті — що насправді всередині API, які нетипові рішення ми прийняли, що свідомо залишили за дужками і як ми сюди прийшли. Без води.
> **🕓 Запис від 2026-04-22, оновлено 2026-05-09.** Деякі цифри застаріли. Актуальний стан: {siteMeta.endpoints} ендпоінтів (а не 87 на момент launch), {siteMeta.snapshotCount} CI snapshot-тестів (а не 183), **MCP-сервер `@astroway/mcp` + TypeScript SDK `@astroway/sdk` + Python SDK `astroway` + PHP SDK `astroway/sdk` тепер усі живуть на public registries**. Свіжий статус — у [/faq](/faq/) і [changelog](/changelog/).
## Що це таке
REST API на базі [Swiss Ephemeris](https://www.astro.com/swisseph/) (LGPL), скомпільованого в WASM і розгорнутого як Node.js-сервіс — тепер ще й з AI-інтерпретаціями (failover-ланцюг GPT-4 / Claude / Llama 3.3 / Gemini / DeepSeek / Mistral) поверх реальних обчислень. Той самий двигун, яким професійні астрологи 30+ років користуються у Solar Fire, Kepler, Astro Gold і Janus — точність до частки кутової секунди, звірена з ефемеридою NASA JPL і офіційним swetest reference від Astrodienst (Astro.com).
**Цифри:**
- **{siteMeta.endpoints} ендпоінт** — західна натальна астрологія, синастрія, транзити, прогресії, дирекції, повернення, гармоніки, фіксовані зорі, арабські точки, астрокартографія плюс повний набір Human Design
- **183 snapshot-тести** у CI проти реального виводу `swetest` CGI і каталогу затемнень NASA — ганяються на кожному PR
- **p50 < 100 мс, p95 < 500 мс** для типових обчислювальних ендпоінтів
- **MCP-сервер** [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) + три SDK на public registries: [`@astroway/sdk`](https://www.npmjs.com/package/@astroway/sdk) (npm), [`astroway`](https://pypi.org/project/astroway/) (PyPI), [`astroway/sdk`](https://packagist.org/packages/astroway/sdk) (Packagist) — той самий API в трьох мовах
- **MCP-сервер**: [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — віддає API як tool-и для Claude, GPT, Cursor та інших LLM-агентів
- **Credit-based тарифи**: безкоштовний план (10 000 кредитів / місяць, без картки), платні — від $5 / місяць
Повна довідка: [api.astroway.info/docs/api/](/docs/api/). Живий статус: [api.astroway.info/status](/status/).
## Чому ми це зробили
Три роки тому ми почали будувати споживчі астрологічні застосунки. Обчислювальний шар виявився найскладнішою частиною — значно складнішою за UI чи контент. Існуючі сервіси або:
1. Мали поверхневе покриття (10–30 ендпоінтів, переважно лише натал)
2. Були дорогими на масштабі ($0.02–$0.10 за запит без оптових знижок)
3. Використовували закриті двигуни, точність яких неможливо перевірити
4. Орієнтувалися на ведичну астрологію, а західну подавали як другорядну
Тож ми вендорили Swiss Ephemeris самостійно й написали власний обчислювальний шар — спершу для споживчого продукту [app.astroway.info](https://app.astroway.info), потім для Marketing-сайту [astroway.info](https://astroway.info), який видає щоденні гороскопи сотням тисяч відвідувачів на місяць.
За три роки роботи цього коду в продакшні ми дійшли двох висновків:
1. Той самий обчислювальний двигун має бути доступний іншим розробникам — не тому, що вони не зможуть написати його самостійно, а тому, що стек **бібліотека + WASM + кешування + CI на точність** — це пів року роботи, яку нікому не варто повторювати.
2. Наше покриття **Human Design** (12 ендпоінтів — карта, тип, авторитет, профіль, ворота, канали, контури, планетарні активації, incarnation cross, definition) — справді унікальне. Жоден конкурент не пропонує повний HD-стек через API.
Оце і є запуск.
## Компроміси, на які ми пішли
### Спершу західна, ведична відкладена
У нас є `/nakshatras`, `/ashtakavarga` та ендпоінти для divisional-карт, але **немає Dasha, Panchang, Ashtakoota, KP**. Причина: у ведичній астрології є невирішені розбіжності між школами (війни аянамш, суперечки про куспіди KP, вибір школи даш). Наспіх зроблена ведична частина проти Prokerala й VedicAstroAPI просто отримала би критику.
Рішення зафіксоване: ведичний пакет — окрема фаза 3, після того, як буде стабільний попит на західну й буде час валідуватись проти Jagannatha Hora та Parashara's Light. Краще не запускати зовсім, ніж запустити погано.
### Credit-based ціни, не per-request
Один виклик `/chart` коштує в ~50 разів менше обчислень, ніж 365-денний `/forecast-calendar`. Плоска ціна за запит або відсікала б легких користувачів, або субсидувала важких. Кредити маплять вартість до реальної роботи — див. таблицю по ендпоінтах на [сторінці тарифів](/pricing/).
### Водяний знак на безкоштовному тарифі
Відповіді на безкоштовному плані містять поле `_footer`:
```json
{
"data": { ... },
"_footer": "Powered by astroway.api — get your own key at api.astroway.info"
}
```
Нам це нічого не коштує, а безкоштовним користувачам дає невеликий привід оновитись. На плані Hobby+ прибирається в налаштуваннях ключа. Патерн позичили в Zapier і RevenueCat.
### Ректифікація — тільки платні тарифи
`/rectification` (підбір часу народження за подіями життя через likelihood-grid пошук) — обчислювально дорогий: один виклик триває 10–60 секунд і робить десятки тисяч проміжних обчислень Swiss Ephemeris. Ми обмежили його планом Pro ($59 / місяць) і виставили велику кредитну ціну, бо зловживання поклало б спільну інфраструктуру для всіх інших.
### Без закритої AI-інтерпретації
Ендпоінти `/interpret/*` маршрутизуються через наш приватний AI-gateway, що поверх best-of-breed моделей ринку (Google Gemini → Groq → OpenRouter → Cerebras → SambaNova → Mistral) з автоматичним failover. Ми не замикаємо тебе у своїх промптах — кожна відповідь з інтерпретацією містить вихідні обчислення, тож можеш перепрошитись власною LLM, якщо наш голос тобі не підходить. Повні промпти й виводи ми логуємо в audit-таблицю для B2B-комплаєнсу (зберігання 90 днів).
## Чого немає в цьому запуску
- **Ведичний пакет** — фаза 3, після перших підтверджень попиту (див. вище)
- **Webhook-и на досягнення порогів** — реалізовані, але UI сирий; доопрацьовуємо
- **Публічні віджети** (`