O SDK oficial em TypeScript

Primeiros passos

Sem apiKey, o cliente lê OCCULT_API_KEY das variáveis de ambiente. Crie uma chave: ela aparece uma única vez, então copie antes de sair da 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);

Os endpoints seguem as URLs

/api/astro/eclipse/next-solar/ vira occult.astro.eclipse.nextSolar(). Sete caminhos são, ao mesmo tempo, endpoint e nó pai, por isso são objetos chamáveis: tanto occult.astro.eclipse() quanto occult.astro.eclipse.upcoming() funcionam.

Os nomes dos campos são exatamente os que a API espera: date_time, e não dateTime. Não há camada de conversão, então o que você escreve é o que vai pela rede.

Um crédito, não importa quanto você peça

O mais importante para saber sobre os preços: pedir seis cálculos em uma chamada custa um sexto do que custariam seis chamadas.

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

Esses nomes têm tipos próprios em cada endpoint. O Panchanga aceita 57, e um único nome errado faz a requisição inteira ser recusada. Por isso o SDK transforma esse erro em erro de compilação, e não em uma chamada desperdiçada.

Erros que você consegue tratar

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

Toda falha é um OccultApiError com um código estável para máquinas, então o seu código decide pela causa, sem interpretar uma frase que pode mudar. Falhas passageiras são repetidas uma vez; uma chave revogada nunca é, porque repetir chamadas em uma API cobrada por uso transforma uma falha em três.

Nada fica preso aos métodos gerados

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

Os métodos com tipos são wrappers de uma única chamada pública. Assim, um endpoint lançado depois da versão que você instalou já fica acessível na hora, sem esperar uma nova versão do SDK.

Só no servidor

A sua chave gasta créditos de verdade e nunca pode ir para um bundle do navegador, onde qualquer pessoa que abrir o devtools consegue lê-la. A API aceita chamadas feitas pelo navegador, então uma requisição do frontend vai funcionar, e vai entregar a sua chave a cada visitante. Chame o SDK no backend e repasse o resultado para o frontend.

Qual usar