Das offizielle TypeScript-SDK

Schnellstart

Ohne apiKey liest der Client OCCULT_API_KEY aus der Umgebung. Erstell einen Schlüssel – er wird nur einmal angezeigt, also kopier ihn, bevor du die Seite verlässt.

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

Die Methoden folgen den URLs

Aus /api/astro/eclipse/next-solar/ wird occult.astro.eclipse.nextSolar(). Sieben Pfade sind gleichzeitig Endpoint und übergeordneter Pfad. Sie sind deshalb aufrufbare Objekte: occult.astro.eclipse() und occult.astro.eclipse.upcoming() funktionieren beide.

Die Feldnamen sind genau die, die die API erwartet – date_time, nicht dateTime. Es gibt keine Übersetzungsschicht: Was du schreibst, wird genau so gesendet.

Ein Credit, egal wie viel du abfragst

Das Wichtigste, was du über die Preise wissen solltest: Sechs Berechnungen in einem Aufruf kosten nur ein Sechstel von sechs einzelnen Aufrufen.

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

Die Namen sind pro Endpoint typisiert. Panchanga kennt 57 davon, und ein einziger falscher Name lässt die gesamte Anfrage scheitern. Das SDK macht daraus deshalb einen Compilerfehler statt eines verschwendeten Aufrufs.

Fehler, auf die dein Code reagieren kann

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

Jeder Fehler ist ein OccultApiError mit einem festen, maschinenlesbaren Code. So reagierst du auf die Ursache, statt einen Satz zu parsen, der sich jederzeit ändern kann. Vorübergehende Fehler werden einmal wiederholt, ein widerrufener Schlüssel nie – denn bei einer API, die nach Nutzung abrechnet, werden aus einem Fehler durch Wiederholen schnell drei.

Du bist nicht auf die generierten Methoden angewiesen

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

Die typisierten Methoden sind nur Hüllen um einen einzigen öffentlichen Aufruf. Ein Endpoint, der nach deiner installierten Version erscheint, ist deshalb sofort nutzbar – ohne auf ein neues SDK-Release zu warten.

Nur auf dem Server

Dein Schlüssel verbraucht echte Credits und darf nie in einem Browser-Bundle landen – dort kann ihn jeder mit den Devtools auslesen. Die API nimmt Aufrufe aus dem Browser zwar an, eine Anfrage aus dem Frontend funktioniert also. Aber damit bekommt jeder Besucher deinen Schlüssel. Ruf das SDK in deinem Backend auf und reich das Ergebnis weiter.

Was wann passt