El SDK oficial para TypeScript

Primeros pasos

Si no pasas apiKey, el cliente lee OCCULT_API_KEY de las variables de entorno. Crea una clave: solo se muestra una vez, así que cópiala antes de salir de la página.

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

Los endpoints siguen la forma de las URL

/api/astro/eclipse/next-solar/ se convierte en occult.astro.eclipse.nextSolar(). Siete rutas son a la vez un endpoint y un nivel padre, así que son objetos invocables: tanto occult.astro.eclipse() como occult.astro.eclipse.upcoming() funcionan.

Los nombres de los campos son exactamente los que espera la API: date_time, no dateTime. No hay ninguna capa de traducción: lo que escribes es lo que se envía.

Un crédito, pidas lo que pidas

Es lo más útil que debes saber sobre los precios. Pedir seis cálculos en una llamada cuesta la sexta parte que hacer seis llamadas.

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

Esos nombres están tipados para cada endpoint. Panchanga admite 57, y un solo nombre incorrecto hace que se rechace la solicitud entera; por eso el SDK lo convierte en un error de compilación en lugar de una llamada desperdiciada.

Errores que tu código puede distinguir

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

Cada fallo es un OccultApiError con un código estable pensado para máquinas, así que decides según la causa en lugar de analizar una frase que puede cambiar de redacción. Los fallos transitorios se reintentan una vez; una clave revocada, nunca, porque reintentar en una API que cobra por uso convierte un fallo en tres.

Los métodos generados no te limitan

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

Los métodos tipados envuelven una única llamada pública, así que puedes usar al instante un endpoint publicado después de tu versión instalada, sin esperar a una nueva versión del SDK.

Solo en el servidor

Tu clave gasta créditos reales y nunca debe acabar en el bundle del navegador, donde cualquiera puede leerla abriendo las herramientas de desarrollo. La API sí acepta llamadas desde el navegador, así que una solicitud desde el front-end funcionará, y le entregará tu clave a cada visitante. Llama al SDK desde tu backend y pasa el resultado al cliente.

Cuándo usar cada uno