आधिकारिक 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 संस्करण का इंतज़ार किए बिना।

सिर्फ़ सर्वर पर

आपकी कुंजी असली क्रेडिट खर्च करती है, इसलिए यह कभी ब्राउज़र वाले कोड में नहीं पहुँचनी चाहिए, जहाँ devtools खोलकर कोई भी इसे पढ़ सकता है। API ब्राउज़र से आई कॉल भी स्वीकार करता है, इसलिए फ़्रंटएंड से अनुरोध चल तो जाएगा, पर आपकी कुंजी हर आने वाले के हाथ लग जाएगी। SDK को अपने बैकएंड से कॉल कीजिए और नतीजा आगे भेजिए।

कौन-सा कब