Resmî TypeScript SDK'sı

Hızlı başlangıç

apiKey verilmezse istemci OCCULT_API_KEY değerini ortam değişkenlerinden okur. Bir anahtar oluşturun; anahtar yalnızca bir kez gösterilir, sayfadan ayrılmadan önce kopyalayın.

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);

Endpoint'ler URL'lerin aynısı

/api/astro/eclipse/next-solar/ yolu occult.astro.eclipse.nextSolar() olarak çağrılır. Yedi yol hem bir endpoint hem de üst yol olduğu için bunlar çağrılabilir nesnelerdir: occult.astro.eclipse() da occult.astro.eclipse.upcoming() da çalışır.

Alan adları tam olarak API'nin beklediği gibidir: dateTime değil, date_time. Arada bir çeviri katmanı yoktur; ne yazarsanız istekte o gider.

Ne kadar isterseniz isteyin, tek kredi

Fiyatlandırma hakkında bilinmesi gereken en faydalı bilgi bu. Altı hesaplamayı tek çağrıda istemek, altı ayrı çağrının altıda birine mal olur.

// 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"],
});

Bu adlar her endpoint için ayrı tiplenmiştir. Panchanga 57 ad kabul eder ve tek bir yanlış ad isteğin tamamını reddettirir. SDK bunu boşa giden bir çağrı yerine derleme hatasına çevirir.

Koda dökebileceğiniz hatalar

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
  }
}

Her hata, sabit ve makinece okunabilir bir koda sahip bir OccultApiError nesnesidir. Böylece ifadesi değişebilecek bir cümleyi ayrıştırmak yerine doğrudan nedene göre dallanırsınız. Geçici hatalar bir kez yeniden denenir; iptal edilmiş bir anahtar ise asla yeniden denenmez, çünkü ücretli bir API'de yeniden denemek tek hatayı üç hataya çevirir.

Üretilen metotların dışında kalan hiçbir şey yok

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

Tipli metotlar, herkese açık tek bir çağrının sarmalayıcılarıdır. Bu yüzden kurduğunuz sürümden sonra yayınlanan bir endpoint'e de SDK'nın yeni sürümünü beklemeden hemen erişebilirsiniz.

Yalnızca sunucu tarafında

Anahtarınız gerçek kredi harcar ve asla tarayıcı paketine girmemelidir; orada geliştirici araçlarını açan herkes onu okuyabilir. API tarayıcıdan gelen çağrıları kabul eder, yani ön yüzden yapılan bir istek çalışır ama anahtarınızı her ziyaretçiye teslim eder. SDK'yı backend'inizden çağırın, sonucu ön yüze iletin.

Nerede kullanılır