Le SDK TypeScript officiel

Démarrage rapide

Sans apiKey, le client lit OCCULT_API_KEY dans l’environnement. Créez une clé : elle ne s’affiche qu’une fois, copiez-la avant de quitter la page.

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

Les endpoints suivent les URL

/api/astro/eclipse/next-solar/ devient occult.astro.eclipse.nextSolar(). Sept chemins sont à la fois un endpoint et un parent : ce sont donc des objets appelables, et occult.astro.eclipse() comme occult.astro.eclipse.upcoming() fonctionnent.

Les noms de champs sont exactement ceux qu’attend l’API : date_time, pas dateTime. Il n’y a aucune couche de conversion : ce que vous écrivez est ce qui part sur le réseau.

Un crédit, quel que soit le volume demandé

C’est la chose la plus utile à savoir sur les tarifs. Demander six calculs en un appel coûte six fois moins cher que six appels.

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

Ces noms sont typés pour chaque endpoint. Panchanga en accepte 57, et un seul nom erroné fait rejeter toute la requête : le SDK en fait donc une erreur de compilation plutôt qu’un appel gâché.

Des erreurs exploitables dans votre code

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

Chaque échec est une OccultApiError avec un code machine stable : vous réagissez selon la cause, sans analyser une phrase dont la formulation peut changer. Les échecs passagers sont relancés une fois ; une clé révoquée ne l’est jamais, car relancer sur une API facturée à l’usage transforme un échec en trois.

Rien n’est verrouillé derrière les méthodes générées

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

Les méthodes typées enveloppent un seul appel public : un endpoint sorti après votre version installée est donc accessible tout de suite, sans attendre une nouvelle version du SDK.

Côté serveur uniquement

Votre clé dépense de vrais crédits et ne doit jamais se retrouver dans un bundle navigateur, où n’importe qui peut la lire en ouvrant les outils de développement. L’API accepte les appels depuis un navigateur : une requête front-end fonctionnera donc, et donnera votre clé à chaque visiteur. Appelez le SDK depuis votre back-end et transmettez le résultat au client.

Quand l’utiliser