Build a Hindu calendar feature in TypeScript

Today's panchang, the month's festivals and the next Ekadashis for any city, with the Node SDK, plus a month grid in HTML.

This tutorial builds a small Hindu calendar for any city: today's panchang with the time each element ends, the month's festivals with the window that decided each date, and the next Ekadashis with their parana window. The complete program is on GitHub: examples/hindu-calendar. It costs about 80 credits per run, well inside the free tier.

1. Install and authenticate

npm install lifeastroapi
export LIFEASTRO_API_KEY=dv_live_...   # free key: lifeastroapi.com/signup

Keep the key on a server or in your terminal. Never ship it inside a browser or mobile bundle.

2. Make the calls

import { LifeAstro } from 'lifeastroapi';

const astro = new LifeAstro({ apiKey: process.env.LIFEASTRO_API_KEY });

// 1. City -> latitude, longitude, IANA timezone (free endpoint).
const { results } = await astro.geo.search({ q: 'Toronto', limit: 1 });
const loc = { lat: results[0].latitude, lon: results[0].longitude, tz: results[0].timezone };

// Today's date as the city sees it.
const today = new Intl.DateTimeFormat('en-CA', { timeZone: loc.tz }).format(new Date());
const [year, month] = today.split('-').map(Number);

// 2. Three calls in parallel.
const [panchang, monthRes, ekadashis] = await Promise.all([
  astro.panchang.advanced({ ...loc, date: today, time: '06:00' }),       // 30 credits
  astro.festivals.month({ ...loc, year, month, monthSystem: 'purnimanta' }), // 20 credits
  astro.festivals.vrat({ ...loc, year, type: 'ekadashi' }),              // 30 credits
]);

Always pass the city's own latitude, longitude and IANA timezone. Festival dates depend on local sunrise, moonrise and evening twilight, so the same festival can fall on a different day in Toronto and New Delhi.

3. Read the response

Each festival comes with the windows that decided it. Karwa Chauth in Toronto, decided at moonrise:

{
  "date": "2026-10-28",
  "name_en": "Karwa Chauth",
  "importance": "major",
  "windows": [
    { "label": "moonrise", "start": "19:38" },
    { "label": "tithi", "start": "…", "end": "…" }
  ]
}

// The window that decided the date: pradosh kaal, moonrise, aparahna …
const deciding = (f) => f.windows?.find((w) => w.label !== 'tithi');

// Each Ekadashi carries its parana (fast-breaking) window for the next morning.
const parana = (f) => f.windows?.find((w) => w.label === 'parana');

Use monthSystem: 'amanta' for South, West and East Indian month names, and read the panchang's hindu_month.name_amanta or name_purnimanta to match.

4. Handle errors

import { LifeAstroError } from 'lifeastroapi';

try {
  await astro.festivals.month({ ...loc, year, month });
} catch (e) {
  if (e instanceof LifeAstroError) {
    // e.status: HTTP status; e.code: e.g. 'insufficient_credits', 'unauthorized'
    console.error(e.status, e.code, e.message);
  }
}

5. The result

Toronto, Ontario, CA  ·  America/Toronto  ·  Sat, 10 Oct 2026

Today
  Saturday, Ashwin Krishna paksha (purnimanta)
  Sunrise 07:25   Sunset 18:42   Moonrise 07:27
  Tithi      Amavasya until 11:50
  Nakshatra  Hasta until 12:12
  Yoga       Indra until 12:32
  Rahu Kaal  10:14–11:39

Run npm run html -- --city "New Delhi" --locale hi in the example to also get a month grid as a single HTML file, with Hindi names next to English.