Офіційний TypeScript SDK

Швидкий старт

Якщо apiKey не задано, клієнт бере OCCULT_API_KEY зі змінних середовища. Створіть ключ — його показують лише раз, тож скопіюйте його, перш ніж піти зі сторінки.

import { OccultApi } from "occult-api";

const occult = new OccultApi({ apiKey: process.env.OCCULT_API_KEY });

const sun = await occult.astro.sunrise({
  date_time: "2026-09-01T06:00:00+05:30",
  latitude: 26.9124,
  longitude: 75.7873,
  timezone_as_float: 5.5,
});

console.log(sun.sunrise, sun.sunset);

Методи повторюють URL

/api/astro/eclipse/next-solar/ — це occult.astro.eclipse.nextSolar(). Сім шляхів є водночас і ендпоінтом, і батьківським вузлом, тому їх можна викликати як функції: працюють і occult.astro.eclipse(), і occult.astro.eclipse.upcoming().

Назви полів точно такі, як очікує API: date_time, а не dateTime. Шару перетворення немає, тож що ви пишете, те й надсилається.

Один кредит — незалежно від обсягу

Найкорисніше, що варто знати про ціни: шість розрахунків в одному виклику коштують у шість разів менше, ніж шість окремих викликів.

// Six calculations, ONE credit. A call costs the same whether you
// ask for one key or twenty, so batch what the screen needs.
const panchang = await occult.astro.panchanga({
  ...place,
  keys: ["tithi", "nakshatra_segments", "yogam", "karana", "choghadiya", "rahu_kaalam"],
});

Ці назви типізовано для кожного ендпоінта. Панчанга приймає 57 таких назв, і одна помилкова відхиляє весь запит. Тож SDK перетворює це на помилку компіляції, а не на змарнований виклик.

Помилки, які легко обробляти

import { OccultApiError } from "occult-api";

try {
  await occult.astro.panchanga({ ...place, keys: ["tithi"] });
} catch (error) {
  if (error instanceof OccultApiError) {
    if (error.code === "insufficient_credits") await upgradePlan();
    if (error.code === "validation_error") console.log(error.fields);
    // error.retryable is false for anything a retry cannot fix
  }
}

Кожна помилка — це OccultApiError зі сталим машинним кодом, тож ви обробляєте причину, а не розбираєте речення, яке можуть переформулювати. Тимчасові збої повторюються один раз; запит із відкликаним ключем — ніколи, бо повтори в API з оплатою за виклик перетворюють одну помилку на три.

Згенеровані методи нічого не обмежують

// Released after this SDK version? Call it anyway.
await occult.call("/api/astro/some-new-endpoint/", { date_time });

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

Лише на сервері

Ваш ключ витрачає справжні кредити, і він ніколи не має потрапити в браузерний бандл, де його прочитає будь-хто, хто відкриє інструменти розробника. API приймає виклики з браузера, тож запит із фронтенду спрацює — і віддасть ваш ключ кожному відвідувачеві. Викликайте SDK зі свого бекенда й передавайте на клієнт лише результат.

Коли що обирати