Запуск AstroWay API: повний стек астрологічних розрахунків з точністю Swiss Ephemeris

Сьогодні ми оголошуємо AstroWay API - обчислювальний backend для розробників, які створюють астрологічні застосунки, гороскопні продукти, функції сумісності для дейтингу та AI-агентів, які мають міркувати про карти народження.

У цій статті - що насправді всередині API, які нетипові рішення ми прийняли, що свідомо залишили за дужками і як ми сюди прийшли. Без води.

🕓 Запис від 2026-04-22, оновлено 2026-05-09. Деякі цифри застаріли. Актуальний стан: 758 ендпоінтів (а не 87 на момент launch), 873 CI snapshot-тестів (а не 183), MCP-сервер @astroway/mcp + TypeScript SDK @astroway/sdk + Python SDK astroway + PHP SDK astroway/sdk тепер усі живуть на public registries. Свіжий статус - у /faq і changelog.

REST API на базі Swiss Ephemeris (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).

Цифри:

• 758 ендпоінт: західна натальна астрологія, синастрія, транзити, прогресії, дирекції, повернення, гармоніки, фіксовані зорі, арабські точки, астрокартографія плюс повний набір Human Design
• 183 snapshot-тести у CI проти реального виводу swetest CGI і каталогу затемнень NASA - ганяються на кожному PR
• p50 < 100 мс, p95 < 500 мс для типових обчислювальних ендпоінтів
• MCP-сервер @astroway/mcp + три SDK на public registries: @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) - той самий API в трьох мовах
• MCP-сервер: @astroway/mcp - віддає API як tool-и для Claude, GPT, Cursor та інших LLM-агентів
• Credit-based тарифи: безкоштовний план (10 000 кредитів / місяць, без картки), платні - від $5 / місяць

Повна довідка: api.astroway.info/docs/api/. Живий статус: api.astroway.info/status.

Три роки тому ми почали будувати споживчі астрологічні застосунки. Обчислювальний шар виявився найскладнішою частиною - значно складнішою за UI чи контент. Існуючі сервіси або:

1. Мали поверхневе покриття (10–30 ендпоінтів, переважно лише натал)
2. Були дорогими на масштабі ($0.02–$0.10 за запит без оптових знижок)
3. Використовували закриті двигуни, точність яких неможливо перевірити
4. Орієнтувалися на ведичну астрологію, а західну подавали як другорядну

Тож ми вендорили Swiss Ephemeris самостійно й написали власний обчислювальний шар - спершу для споживчого продукту app.astroway.info, потім для Marketing-сайту 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. Краще не запускати зовсім, ніж запустити погано.

Один виклик /chart коштує в ~50 разів менше обчислень, ніж 365-денний /forecast-calendar. Плоска ціна за запит або відсікала б легких користувачів, або субсидувала важких. Кредити маплять вартість до реальної роботи - див. таблицю по ендпоінтах на сторінці тарифів.

Відповіді на безкоштовному плані містять поле _footer:

{
  "data": { ... },
  "_footer": "Powered by astroway.api - get your own key at https://api.astroway.info"
}

Нам це нічого не коштує, а безкоштовним користувачам дає невеликий привід оновитись. На плані Hobby+ прибирається в налаштуваннях ключа. Патерн позичили в Zapier і RevenueCat.

/rectification (підбір часу народження за подіями життя через likelihood-grid пошук) - обчислювально дорогий: один виклик триває 10–60 секунд і робить десятки тисяч проміжних обчислень Swiss Ephemeris. Ми обмежили його планом Pro ($59 / місяць) і виставили велику кредитну ціну, бо зловживання поклало б спільну інфраструктуру для всіх інших.

Ендпоінти /interpret/* маршрутизуються через наш приватний AI-gateway, що поверх best-of-breed моделей ринку (Google Gemini → Groq → OpenRouter → Cerebras → SambaNova → Mistral) з автоматичним failover. Ми не замикаємо тебе у своїх промптах - кожна відповідь з інтерпретацією містить вихідні обчислення, тож можеш перепрошитись власною LLM, якщо наш голос тобі не підходить. Повні промпти й виводи ми логуємо в audit-таблицю для B2B-комплаєнсу (зберігання 90 днів).

• Ведичний пакет: фаза 3, після перших підтверджень попиту (див. вище)
• Webhook-и на досягнення порогів: реалізовані, але UI сирий; доопрацьовуємо
• Публічні віджети (<script src="api.astroway.info/widget/natal.js">) - фаза 7
• Плагін для основного Marketing-сайту: окремий проєкт, планується в рамках екосистеми astroway.info

1. Прочитай документацію якщо хочеш зрозуміти «чому»: api.astroway.info/overview
2. Швидкий старт за 5 хвилин з кодом: Astrology API Quick Start
3. Тарифи, включно з таблицею кредитів на ендпоінт: api.astroway.info/pricing
4. Зареєструйся: безкоштовно, без картки: api.astroway.info/dashboard/sign-up

Якщо збудуєш щось на API - або зловиш баг, або захочеш ендпоінт, якого в нас ще немає - напиши нам. Нам краще почути сто розробників, які чогось просять, ніж запускати фічі, якими ніхто не користується.

Питання, запити, дивні edge-кейси: hello@astroway.info.

Roadmap публічний - PRODUCT-PLAN.md - що зроблено, що наступне, що відкладено і чому.

Ласкаво просимо.