Методологія

Положення планет розраховуються за ефемеридами NASA JPL — за повним набором даних на 105 МБ, а не скороченим, де є 735 нерухомих зір, на проміжку 500–2999 рр. н. е. Ніщо не інтерполюється з таблиці готових значень альманаху, і кешованих результатів немає: кожну відповідь розраховано для точного моменту й координат із запиту.

Цей діапазон важливий у двох реальних випадках: для історичних карт і для довгих сканувань даш і транзитів, що сягають на десятиліття вперед. Бібліотека, обмежена сучасною епохою, на краях діапазону непомітно втрачає точність.

Той самий рушій розрахунків працює в Yoga Panchang, нашому безкоштовному сайті про панчанг і джйотиш, тож цифри, які його читачі бачать щодня, походять із коду, описаного тут.

Найбільше розбіжностей між двома ведичними розрахунками дає не арифметика, а аянамша. Індійські традиції справді розходяться в ній, а різниця в градус переносить планету в іншу накшатру.

Тому ми пропонуємо 48 з них — родину Сур’я-сіддханти, істинну Чітру, істинну Реваті, істинну Пуш’ю, Рамана, KP, Юктешвара та інші — і дозволяємо скоригувати будь-яку з точністю до градуса, мінути й секунди. Ми не обираємо одну й не оголошуємо її єдино правильною. Якщо наш результат не збігається з іншим джерелом, спершу перевірте, чи ви обидва використовуєте ту саму аянамшу.

Саме цим не може похвалитися більшість документацій API. Наш довідник не пишеться вручну: його генерує з самих серіалізаторів build_api_catalogue, а потім verify_api_catalogue перевіряє його на робочому сервері — надсилає кожен задокументований приклад запиту й перевіряє, що відповідь має код 2xx.

У результаті маємо те, що справді цінно: 255 з 299 сторінок ендпоінтів показують справжню записану відповідь, а не вигадану, а решту позначено як ще не перевірені, а не видано за робочі. Поле не може тихо зникнути з документації, як це буває в таблиці, яку ведуть вручну. Якщо серіалізатор змінився, а документацію не перегенерували, перевірка не проходить — і неправда не потрапляє в публікацію.

З того самого каталогу генеруються специфікація OpenAPI, колекція Postman і llms.txt, тож усі чотири за самою побудовою описують один і той самий API.

Бекенд має 1 783 тестові функції у 87 модулях. Найретельніше вони покривають облік списань, бо саме там помилка коштує комусь грошей. Тести перевіряють, що успішний виклик списує рівно стільки, скільки коштує ендпоінт; що 4xx і 5xx не списують нічого; що одночасна боротьба за останній кредит не може зробити баланс від’ємним; і що журнал операцій сходиться з балансом після випадкової послідовності нарахувань і списань.

Ми публікуємо медіану 62 мс і 76% відповідей менш ніж за 100 мс. Ці цифри отримано так: 22 жовтня 2026 р. ми викликали 254 опубліковані приклади, кожен із власним зразком запиту, на локально запущеному API — спершу один раз для розігріву, потім один раз із заміром часу. Ми не заміряли швидкий ендпоінт і не округлювали результат. ШІ-чат не враховано: його час — це час мовної моделі.

Тому ми й кажемо прямо: кілька ендпоінтів працюють набагато повільніше, і в документації це зазначено. Повний прохід варшапхалу чи рік раші-даші займає секунди, а не мілісекунди, бо це сканування, а не пошук у таблиці. Медіана таке приховує, а опублікований поруч розподіл — ні.

медіана   62 мс      половина ендпоінтів відповідає швидше
<100 мс   76%        більшість звичайних запитів
повільні  секунди    глибокі сканування — позначені в довіднику

Дві речі, які ми хотіли б опублікувати, але поки не опублікували. Кажемо про це прямо, а не залишаємо вам здогадуватися:

• Незалежне порівняння положень. Ми рахуємо за ефемеридами JPL, але ще не опублікували порівняння наших результатів із JPL Horizons на різних датах і тілах — з відхиленнями й кодом для відтворення. Доки цього немає, сприймайте заяву про точність як «розраховано за цим джерелом», а не «перевірено з такою похибкою».
• Довгострокова доступність. Доступність публікується на сторінці статусу лише з жовтня 2026 року, тож довгої історії, на яку можна послатися, поки немає. Що ми зобов’язуємося забезпечувати, описано на сторінці прозорості.

Обидва пункти в планах. Жоден не складний; обидва ми хочемо зробити як слід, а не абияк.

Playground робить справжні виклики з вашим ключем, а невдалий виклик нічого не коштує. Тож ви можете порівняти наші результати з будь-яким джерелом, якому вже довіряєте. Якщо знайдете розбіжність, яку не пояснює аянамша, — нам дуже цікаво про неї дізнатися.