astrology-insights

Comprehensive Vedic astrology engine for Node.js -- Panchang, birth charts, Vimshottari Dasha, divisional charts, dosha analysis, and more.

Overview

astrology-insights is a production-grade Vedic astrology library that computes:

• Daily Panchang with Swiss Ephemeris precision (tithi, nakshatra, yoga, karana, muhurats, kalams)
• Birth Charts (Kundli) with 9 grahas, 12 houses, 3 chart layouts, dignity, combustion
• Vimshottari Dasha with 5-level depth (Maha through Prana)
• 16 Divisional Charts (Shodashvarga) with Varga Viswa scoring
• Dosha Analysis (Manglik, Kaal Sarp, Ganda Moola, Gandanta)
• Planetary Strength (Shad Bala), Tattva balance, aspects, friendships
• Recommendations -- baby name suggestions by nakshatra/pada, gemstone and mantra remedies

Validated against Drik Panchang with 28/29 fields matching exactly.

Built for astrology apps, Kundli generators, calendar services, and research tools.

Features

• Swiss Ephemeris planetary positions (sidereal, Lahiri or KP ayanamsa)
• Full Panchang: tithi, nakshatra, yoga, karana, vara, paksha, ayana, ritu, samvatsar
• 7 auspicious muhurats and 5 inauspicious kalams per day
• Monthly Panchang batch calculation
• Complete birth chart with North Indian, South Indian, and Western layouts
• Whole Sign, Equal, and Placidus house systems
• Planetary dignity (exalted, moolatrikona, own sign, debilitated), combustion detection
• Vimshottari Dasha: Maha, Antar, Pratyantar, Sookshma, Prana levels
• All 16 Shodashvarga divisional charts (D1 through D60)
• Manglik, Kaal Sarp, Ganda Moola, Gandanta dosha detection
• Shad Bala six-fold planetary strength
• Tattva (element) balance analysis
• Planetary aspects with full/partial strength
• Natural, temporal, and compound planetary friendships
• Baby name suggestions based on birth nakshatra syllable
• Gemstone, mantra, charity, and fasting remedies for weak planets
• React Native compatible entry point with API fetch
• Vercel serverless deployment ready
• Backward-compatible legacy APIs (sunrise/sunset, Choghadiya, biorhythms)

Installation

npm install astrology-insights

Requirements: Node.js >= 16

Quick Start

1. Daily Panchang

const { calculateFullPanchang } = require("astrology-insights");

const panchang = calculateFullPanchang("2026-03-21", 28.6139, 77.209, "Asia/Kolkata");

console.log(panchang.tithi[0].name);       // "Shukla Tritiya"
console.log(panchang.nakshatra[0].name);    // "Ashwini"
console.log(panchang.yoga[0].name);         // "Indra"
console.log(panchang.sunrise);              // "06:25"
console.log(panchang.auspiciousMuhurats);   // Brahma, Abhijit, Vijaya, ...

2. Birth Chart (Kundli)

const { calculateBirthChart } = require("astrology-insights");

const chart = calculateBirthChart({
  date: "2000-01-01",
  time: "04:30",
  latitude: 28.6139,
  longitude: 77.209,
  timezone: "Asia/Kolkata",
  name: "Sample",
});

console.log(chart.lagna.signName);           // Ascendant sign
console.log(chart.planets[0].name);          // "Sun"
console.log(chart.planets[0].signName);      // Zodiac sign
console.log(chart.planets[0].dignity);       // "exalted", "own_sign", etc.
console.log(chart.layout.northIndian.boxes); // 12 chart boxes with planets

3. Vimshottari Dasha

const { calculateVimshottariDasha } = require("astrology-insights");

const dasha = calculateVimshottariDasha(
  new Date("2000-01-01T04:30:00Z"),
  "Ashwini",   // Moon's nakshatra at birth
  5.5,         // Moon's degree within nakshatra (0-13.333)
  5            // Depth: 1=Maha only, 5=down to Prana
);

console.log(dasha.currentDasha.maha);       // Current Maha Dasha lord
console.log(dasha.currentDasha.antar);       // Current Antar Dasha lord
console.log(dasha.balanceAtBirth);           // Remaining dasha at birth
console.log(dasha.mahaDashas.length);        // 9 Maha Dasha periods

API Reference

Panchang

calculateFullPanchang(date, latitude, longitude, timezone)

Computes the complete daily Panchang for any date and location.

Parameters:

| Param | Type | Example | |---|---|---| | date | string \| Date | "2026-03-21" | | latitude | number | 28.6139 | | longitude | number | 77.209 | | timezone | string | "Asia/Kolkata" |

Returns: PanchangResult

| Field | Type | Description | |---|---|---| | tithi | TithiResult[] | Lunar day: name, number, paksha, progress % | | nakshatra | NakshatraResult[] | Lunar mansion: name, pada (1-4), lord, deity, progress % | | yoga | YogaResult[] | Sun-Moon conjunction: name, number (1-27), progress % | | karana | KaranaResult[] | Half-tithi: name, number, progress % | | vara | object | Weekday: name and number | | moonSign / sunSign | RashiInfo | Zodiac sign with lord and degree | | moonPhase | object | Phase name and illumination % | | paksha | string | "Shukla" or "Krishna" | | sunrise / sunset | string | "HH:mm" format | | moonrise / moonset | string | "HH:mm" format | | auspiciousMuhurats | array | Brahma, Pratah Sandhya, Abhijit, Vijaya, Godhuli, Sayahna Sandhya, Nishita | | inauspiciousKalams | array | Rahu Kalam, Gulika Kalam, Yamaganda, Varjyam, Dur Muhurtam | | sunNakshatra | object | Sun's nakshatra with pada, lord, deity | | ayana | string | "Uttarayana" or "Dakshinayana" | | ritu | object | { vedic: "Vasanta", english: "Spring" } | | solarMonth | string | Solar month name (Mesha, Vrishabha, etc.) | | dinamana / ratrimana | string | Day/night duration | | madhyahna | string | Solar noon | | samvatsar | string | Name of the 60-year cycle year | | vikramSamvat / shakaSamvat | number | Calendar years |

const result = calculateFullPanchang("2026-03-21", 28.6139, 77.209, "Asia/Kolkata");

console.log(result.tithi[0].name);      // "Shukla Tritiya"
console.log(result.nakshatra[0].name);   // "Ashwini"
console.log(result.yoga[0].name);        // "Indra"
console.log(result.karana[0].name);      // "Taitila"
console.log(result.vara.name);           // "Saturday"
console.log(result.moonSign.name);       // "Aries"
console.log(result.sunSign.name);        // "Pisces"
console.log(result.paksha);              // "Shukla"
console.log(result.sunrise);             // "06:25"
console.log(result.sunset);              // "18:33"
console.log(result.ayana);              // "Uttarayana"
console.log(result.ritu);               // { vedic: "Vasanta", english: "Spring" }
console.log(result.samvatsar);           // "Siddharthi"
console.log(result.vikramSamvat);        // 2083
console.log(result.dinamana);           // "12h 08m"

calculateMonthlyPanchang(year, month, latitude, longitude, timezone)

Compute Panchang for every day in a given month.

Parameters:

| Param | Type | Example | |---|---|---| | year | number | 2026 | | month | number | 3 (March) | | latitude | number | 28.6139 | | longitude | number | 77.209 | | timezone | string | "Asia/Kolkata" |

Returns: { year, month, location, days: PanchangResult[] }

const { calculateMonthlyPanchang } = require("astrology-insights");

const month = calculateMonthlyPanchang(2026, 3, 28.6139, 77.209, "Asia/Kolkata");

month.days.forEach(day => {
  console.log(`${day.date}: ${day.tithi[0].name} | ${day.nakshatra[0].name}`);
});

calculateTithi(sunLongitude, moonLongitude)

Calculate tithi from raw sidereal longitudes.

Returns: { name, number, paksha, progress }

const { calculateTithi } = require("astrology-insights");

const tithi = calculateTithi(335.5, 359.8);
// { name: "Shukla Tritiya", number: 3, paksha: "Shukla", progress: 2.5 }

calculateNakshatraV2(moonLongitude)

Calculate nakshatra from the Moon's sidereal longitude.

Exported as calculateNakshatraV2. Internally this is calculateNakshatra from panchang/src/core/nakshatra.

Returns: { name, number, pada, lord, deity, progress }

const { calculateNakshatraV2 } = require("astrology-insights");

const nakshatra = calculateNakshatraV2(355.0);
// { name: "Revati", number: 27, pada: 3, lord: "Mercury", deity: "Pushan" }

calculateYoga(sunLongitude, moonLongitude)

Calculate yoga from Sun and Moon sidereal longitudes.

Returns: { name, number, progress }

const { calculateYoga } = require("astrology-insights");

const yoga = calculateYoga(335.5, 359.8);
// { name: "Indra", number: 26, progress: 14.8 }

calculateKarana(sunLongitude, moonLongitude)

Calculate karana from Sun and Moon sidereal longitudes.

Returns: { name, number, progress }

const { calculateKarana } = require("astrology-insights");

const karana = calculateKarana(335.5, 359.8);
// { name: "Kaulava", number: 3, progress: 5.0 }

calculateRashi(longitude)

Determine the zodiac sign (rashi) for a given sidereal longitude.

Returns: { name, lord, degree }

const { calculateRashi } = require("astrology-insights");

const rashi = calculateRashi(355.0);
// { name: "Pisces", lord: "Jupiter", degree: 25 }

Birth Chart

calculateBirthChart(birthData, options?)

Calculate a complete Vedic birth chart (Kundli).

Parameters:

| Param | Type | Description | |---|---|---| | birthData | BirthData | Birth details (see below) | | options? | BirthChartOptions | Ayanamsa and house system |

BirthData:

| Field | Type | Required | Example | |---|---|---|---| | date | string | Yes | "2000-01-01" | | time | string | Yes | "04:30" | | latitude | number | Yes | 28.6139 | | longitude | number | Yes | 77.209 | | timezone | string | Yes | "Asia/Kolkata" | | name | string | No | "Adarsh" |

BirthChartOptions:

| Field | Type | Default | Options | |---|---|---|---| | ayanamsa | AyanamsaType | "lahiri" | "lahiri", "kp" | | houseSystem | HouseSystemType | "whole_sign" | "whole_sign", "equal", "placidus" |

Returns: BirthChartResult

| Field | Type | Description | |---|---|---| | birthData | BirthData | Echo of input | | ayanamsa | { type, degree } | Ayanamsa used | | lagna | LagnaInfo | Ascendant: longitude, sign, degree, nakshatra, pada, lord | | planets | GrahaPosition[] | 9 grahas with sign, nakshatra, dignity, combustion, retrograde | | houses | HouseInfo[] | 12 houses with sign, cusp degree, occupying planets | | layout | { northIndian, southIndian, western } | Chart layouts for rendering | | meta | object | Julian day, UTC date, house system, timestamp |

GrahaPosition fields:

| Field | Type | Description | |---|---|---| | name | GrahaName | "Sun", "Moon", "Mars", etc. | | longitude | number | Sidereal longitude (0-360) | | speed | number | Degrees/day (negative = retrograde) | | retrograde | boolean | Whether planet is retrograde | | signName | string | "Aries", "Taurus", etc. | | signNumber | number | 1-12 | | degreeInSign | number | 0-30 | | nakshatra | string | Nakshatra name | | nakshatraPada | number | Pada (1-4) | | nakshatraLord | string | Nakshatra lord | | dignity | Dignity | "exalted", "own_sign", "debilitated", etc. | | isCombust | boolean | Proximity to Sun | | combustOrb | number | Degrees from Sun | | symbol | string | Dignity symbol |

const { calculateBirthChart } = require("astrology-insights");

const chart = calculateBirthChart(
  {
    date: "2000-01-01",
    time: "04:30",
    latitude: 28.6139,
    longitude: 77.209,
    timezone: "Asia/Kolkata",
    name: "Sample",
  },
  { ayanamsa: "lahiri", houseSystem: "whole_sign" }
);

// Lagna (Ascendant)
console.log(chart.lagna.signName);        // e.g. "Scorpio"
console.log(chart.lagna.degreeInSign);    // e.g. 12.45

// Planets
chart.planets.forEach(p => {
  console.log(`${p.name}: ${p.signName} ${p.degreeInSign.toFixed(1)}° [${p.dignity}]`);
});
// Sun: Sagittarius 15.2° [neutral]
// Moon: Virgo 8.7° [neutral]
// Mars: Aquarius 3.1° [neutral]
// ...

// Houses
chart.houses.forEach(h => {
  console.log(`House ${h.number}: ${h.signName} — ${h.planets.join(", ") || "empty"}`);
});

// Chart layout (for rendering)
console.log(chart.layout.northIndian.boxes[0]);
// { houseNumber: 1, signNumber: 8, signName: "Scorpio", planets: ["Mars"] }

Analysis APIs

calculateTattvaBalance(placements)

Analyze the five-element (Tattva) distribution across planetary placements.

Parameters:

| Param | Type | Description | |---|---|---| | placements | TattvaInput[] | Array of { name, signNumber } |

Returns: TattvaBalance -- counts and percentages for Fire, Earth, Air, Water elements.

const { calculateTattvaBalance } = require("astrology-insights");

const chart = calculateBirthChart({ /* ... */ });
const tattva = calculateTattvaBalance(
  chart.planets.map(p => ({ name: p.name, signNumber: p.signNumber }))
);

console.log(tattva);
// {
//   Fire: { planets: ["Mars", "Jupiter"], count: 2, percent: 22.2 },
//   Earth: { planets: ["Moon", "Saturn"], count: 2, percent: 22.2 },
//   Air: { planets: ["Rahu"], count: 1, percent: 11.1 },
//   Water: { planets: ["Sun", "Mercury", "Venus", "Ketu"], count: 4, percent: 44.4 },
//   dominant: "Water",
//   weak: "Air"
// }

calculateFriendships(planets)

Compute natural, temporal, and compound (Pancha-vargiya) friendships between planets.

Parameters:

| Param | Type | Description | |---|---|---| | planets | FriendshipInput[] | Array of { name, signNumber } |

Returns: PlanetaryFriendships -- natural, temporal, and compound relationship maps.

const { calculateFriendships } = require("astrology-insights");

const friendships = calculateFriendships(
  chart.planets.map(p => ({ name: p.name, signNumber: p.signNumber }))
);

// friendships.natural.Sun.Jupiter   → "friend"
// friendships.temporal.Sun.Mars     → "friend" or "enemy"
// friendships.compound.Sun.Saturn   → "bitter_enemy" or "neutral"

calculateAspects(planets)

Calculate Vedic planetary aspects with full and partial (Drishti) strengths.

Parameters:

| Param | Type | Description | |---|---|---| | planets | AspectPlanetInput[] | Array of { name, house } |

Returns: AspectResult -- array of aspects with source, target, house, and strength.

const { calculateAspects } = require("astrology-insights");

const aspects = calculateAspects(
  chart.planets.map(p => ({
    name: p.name,
    house: chart.houses.findIndex(h => h.planets.includes(p.name)) + 1,
  }))
);

aspects.aspects.forEach(a => {
  console.log(`${a.fromPlanet} aspects ${a.toPlanet} (house ${a.toHouse}, strength: ${a.strength})`);
});

calculateShadBala(planets, lagnaSignNumber, birthHour?)

Compute the six-fold planetary strength (Shad Bala).

Parameters:

| Param | Type | Description | |---|---|---| | planets | ShadBalaPlanetInput[] | Array of { name, signNumber, degreeInSign, speed, house } | | lagnaSignNumber | number | Lagna sign (1-12) | | birthHour | number? | Hour of birth (0-23), optional |

Returns: ShadBalaResult[]

| Field | Type | Description | |---|---|---| | planet | string | Planet name | | sthana | number | Positional strength (0-100) | | dig | number | Directional strength (0-60) | | kala | number | Temporal strength (0-100) | | chesta | number | Motional strength (0-60) | | naisargika | number | Natural strength (fixed) | | drik | number | Aspectual strength (0-60) | | total | number | Sum of all components | | required | number | Minimum required threshold | | ratio | number | total / required (>1 = strong) | | isStrong | boolean | Whether ratio >= 1 |

const { calculateShadBala } = require("astrology-insights");

const bala = calculateShadBala(
  chart.planets.map(p => ({
    name: p.name,
    signNumber: p.signNumber,
    degreeInSign: p.degreeInSign,
    speed: p.speed,
    house: chart.houses.findIndex(h => h.planets.includes(p.name)) + 1,
  })),
  chart.lagna.signNumber
);

bala.forEach(b => {
  console.log(`${b.planet}: ${b.total.toFixed(1)} (${b.isStrong ? "strong" : "weak"})`);
});

Dosha APIs

analyzeManglik(planets, houses)

Detect Manglik (Kuja) Dosha from birth chart data.

Returns: ManglikResult

| Field | Type | Description | |---|---|---| | isManglik | boolean | Whether Manglik Dosha is present | | severity | string | "none", "mild", or "full" | | marsHouse | number | House occupied by Mars | | details | string | Explanation | | cancellations | string[] | Applicable cancellation conditions |

const { analyzeManglik } = require("astrology-insights");

const manglik = analyzeManglik(chart.planets, chart.houses);

console.log(manglik.isManglik);     // true
console.log(manglik.severity);      // "mild"
console.log(manglik.marsHouse);     // 7
console.log(manglik.cancellations); // ["Jupiter aspects Mars from house 3"]

analyzeKaalSarp(planets, houses)

Detect Kaal Sarp Dosha (all planets hemmed between Rahu and Ketu).

Returns: KaalSarpResult

| Field | Type | Description | |---|---|---| | hasDosha | boolean | Whether Kaal Sarp Dosha is present | | type | string | Specific type name (e.g., "Anant", "Kulik") | | rahuHouse | number | House of Rahu | | ketuHouse | number | House of Ketu | | details | string | Explanation |

const { analyzeKaalSarp } = require("astrology-insights");

const kaalSarp = analyzeKaalSarp(chart.planets, chart.houses);

console.log(kaalSarp.hasDosha);     // false
console.log(kaalSarp.type);         // "none" or "Anant", "Kulik", etc.

analyzeGandaMoola(planets)

Detect Ganda Moola Dosha (Moon in a junction nakshatra).

Returns: GandaMoolaResult

| Field | Type | Description | |---|---|---| | hasDosha | boolean | Whether Moon is in a Ganda Moola nakshatra | | nakshatra | string | Moon's nakshatra | | details | string | Explanation and traditional implications |

const { analyzeGandaMoola } = require("astrology-insights");

const gandaMoola = analyzeGandaMoola(chart.planets);

console.log(gandaMoola.hasDosha);    // true/false
console.log(gandaMoola.nakshatra);   // "Ashlesha" (if applicable)

analyzeGandanta(planets, lagna)

Analyze Gandanta -- planets at the junction of water and fire signs (critical degrees).

Returns: GandantaResult

| Field | Type | Description | |---|---|---| | hasGandanta | boolean | Whether any planet or lagna is in Gandanta zone | | affectedPlanets | GandantaPlanet[] | Planets in Gandanta with severity | | details | string | Summary |

const { analyzeGandanta } = require("astrology-insights");

const gandanta = analyzeGandanta(chart.planets, chart.lagna);

console.log(gandanta.hasGandanta);         // true/false
console.log(gandanta.affectedPlanets);     // [{ planet: "Moon", severity: "severe", ... }]

Divisional Charts

calculateDivisionalChart(division, planets, lagnaSignNumber, lagnaDegree)

Calculate any of the 16 Shodashvarga divisional charts.

Parameters:

| Param | Type | Description | |---|---|---| | division | number | Division number (1, 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60) | | planets | PlanetInput[] | Array of { name, signNumber, degreeInSign } | | lagnaSignNumber | number | Lagna sign number (1-12) | | lagnaDegree | number | Lagna degree within sign (0-30) |

Returns: DivisionalChart

| Field | Type | Description | |---|---|---| | name | string | Chart name, e.g. "Navamsa (D9)" | | division | number | Division number | | planets | DivisionalPosition[] | Planet placements in this varga | | lagnaSign | { number, name } | Lagna in this divisional chart |

All 16 Shodashvarga charts:

| Division | Name | Shorthand | Signification | |---|---|---|---| | 1 | Rasi | D1 | Birth chart -- overall life | | 2 | Hora | D2 | Wealth and finances | | 3 | Drekkana | D3 | Siblings and courage | | 4 | Chaturthamsa | D4 | Property and fortune | | 7 | Saptamsa | D7 | Children and progeny | | 9 | Navamsa | D9 | Marriage, dharma, spiritual life | | 10 | Dasamsa | D10 | Career and profession | | 12 | Dwadasamsa | D12 | Parents and ancestry | | 16 | Shodasamsa | D16 | Vehicles and comforts | | 20 | Vimsamsa | D20 | Spiritual progress and worship | | 24 | Chaturvimsamsa | D24 | Education and learning | | 27 | Saptavimsamsa | D27 | Physical strength and stamina | | 30 | Trimsamsa | D30 | Misfortunes and challenges | | 40 | Khavedamsa | D40 | Auspicious/inauspicious effects | | 45 | Akshavedamsa | D45 | General indications, paternal legacy | | 60 | Shashtiamsa | D60 | Past life karma, overall summary |

const { calculateDivisionalChart } = require("astrology-insights");

const planets = chart.planets.map(p => ({
  name: p.name,
  signNumber: p.signNumber,
  degreeInSign: p.degreeInSign,
}));

// Navamsa (D9)
const navamsa = calculateDivisionalChart(9, planets, chart.lagna.signNumber, chart.lagna.degreeInSign);

console.log(navamsa.name);         // "Navamsa (D9)"
console.log(navamsa.lagnaSign);    // { number: 4, name: "Cancer" }
navamsa.planets.forEach(p => {
  console.log(`${p.planet}: ${p.vargaSignName} (${p.vargaSignNumber})`);
});

// Dasamsa (D10) for career
const dasamsa = calculateDivisionalChart(10, planets, chart.lagna.signNumber, chart.lagna.degreeInSign);

calculateShodashvarga(planets, lagnaSignNumber, lagnaDegree)

Compute all 16 divisional charts at once with Varga Viswa dignity scoring.

Returns: ShodashvargaEntry[] -- one entry per planet, each with scores across all 16 charts and a totalPoints (Varga Viswa points).

const { calculateShodashvarga } = require("astrology-insights");

const shodash = calculateShodashvarga(planets, chart.lagna.signNumber, chart.lagna.degreeInSign);

shodash.forEach(entry => {
  console.log(`${entry.planet}: ${entry.totalPoints} Varga Viswa points`);
  entry.scores.forEach(s => {
    console.log(`  ${s.chart}: ${s.sign} [${s.dignity}]`);
  });
});

Vimshottari Dasha

calculateVimshottariDasha(birthDate, moonNakshatra, moonNakshatraDegree, depth?)

Compute the 120-year Vimshottari Dasha planetary period system.

Parameters:

| Param | Type | Default | Description | |---|---|---|---| | birthDate | Date | -- | UTC birth date/time | | moonNakshatra | string | -- | Moon's nakshatra at birth (e.g., "Ashwini") | | moonNakshatraDegree | number | -- | Moon's degree within the nakshatra (0-13.333) | | depth | number | 5 | Levels: 1=Maha, 2=Antar, 3=Pratyantar, 4=Sookshma, 5=Prana |

Returns: VimshottariResult

| Field | Type | Description | |---|---|---| | birthNakshatra | string | Moon's nakshatra | | birthNakshatraLord | string | Nakshatra lord (first Maha Dasha) | | balanceAtBirth | object | { planet, years, months, days } remaining at birth | | mahaDashas | DashaPeriod[] | 9 Maha Dasha periods with nested sub-periods | | currentDasha | object | { maha, antar, pratyantar, sookshma, prana } active now |

DashaPeriod fields:

| Field | Type | Description | |---|---|---| | planet | string | Dasha lord | | level | number | 1=Maha, 2=Antar, 3=Pratyantar, 4=Sookshma, 5=Prana | | levelName | string | "Maha Dasha", "Antar Dasha", etc. | | startDate | string | ISO date (YYYY-MM-DD) | | endDate | string | ISO date | | durationDays | number | Period length in days | | isActive | boolean | Whether current date falls in this period | | subPeriods | DashaPeriod[]? | Next level down (if depth allows) |

const { calculateVimshottariDasha } = require("astrology-insights");

const dasha = calculateVimshottariDasha(
  new Date("2000-01-01T04:30:00Z"),
  "Rohini",
  8.5,
  3  // Maha → Antar → Pratyantar
);

console.log(dasha.birthNakshatra);       // "Rohini"
console.log(dasha.birthNakshatraLord);   // "Moon"

console.log(dasha.balanceAtBirth);
// { planet: "Moon", years: 6, months: 3, days: 18 }

console.log(dasha.currentDasha);
// { maha: "Mars", antar: "Jupiter", pratyantar: "Saturn", ... }

// Traverse the tree
dasha.mahaDashas.forEach(maha => {
  console.log(`${maha.planet} Maha Dasha: ${maha.startDate} → ${maha.endDate}`);
  maha.subPeriods?.forEach(antar => {
    console.log(`  ${antar.planet} Antar: ${antar.startDate} → ${antar.endDate}`);
  });
});

Recommendations

getNameSuggestions(nakshatra, pada)

Get auspicious baby name suggestions based on birth nakshatra and pada.

Parameters:

| Param | Type | Description | |---|---|---| | nakshatra | string | Birth nakshatra (e.g., "Ashwini") | | pada | number | Pada (1-4) |

Returns: NameSuggestion[] -- suggestions with syllable, gender, and name list.

const { getNameSuggestions } = require("astrology-insights");

const names = getNameSuggestions("Ashwini", 1);

console.log(names[0].syllable);    // "Chu"
console.log(names[0].nakshatra);   // "Ashwini"
console.log(names[0].pada);        // 1
names[0].names.forEach(n => {
  console.log(`${n.name} (${n.gender})`);
});
// "Chunda (male)", "Chumki (female)", etc.

getRemedies(planets)

Recommend gemstones, mantras, charity, and fasting remedies for weak or afflicted planets.

Parameters:

| Param | Type | Description | |---|---|---| | planets | RemedyPlanetInput[] | Array of { name, dignity, isCombust, house } |

Returns: RemedyResult

| Field | Type | Description | |---|---|---| | weakPlanets | WeakPlanetRemedy[] | Each weak planet with reason and full remedy | | generalRemedies | string[] | General spiritual advice |

WeakPlanetRemedy contains a PlanetaryRemedy:

| Field | Type | Description | |---|---|---| | gemstone | GemstoneInfo | Name, alternates, metal, finger, day, weight | | mantra | MantraInfo | Vedic mantra, beej mantra, japa count | | charity | CharityInfo | Items, day, deity | | color | string | Lucky color | | direction | string | Favorable direction | | fasting | string | Recommended fasting day |

const { getRemedies } = require("astrology-insights");

const remedies = getRemedies(
  chart.planets.map(p => ({
    name: p.name,
    dignity: p.dignity,
    isCombust: p.isCombust,
    house: chart.houses.findIndex(h => h.planets.includes(p.name)) + 1,
  }))
);

remedies.weakPlanets.forEach(wp => {
  console.log(`${wp.planet} is weak: ${wp.reason}`);
  console.log(`  Gemstone: ${wp.remedy.gemstone.name} (${wp.remedy.gemstone.weight})`);
  console.log(`  Mantra: ${wp.remedy.mantra.vedic} (${wp.remedy.mantra.japaCount}x)`);
  console.log(`  Charity: ${wp.remedy.charity.items.join(", ")} on ${wp.remedy.charity.day}`);
  console.log(`  Fast on: ${wp.remedy.fasting}`);
});

Legacy APIs

These functions remain available and backward-compatible. They work with HH:mm:ss time strings.

calculateSunriseSunset(date, latitude, longitude, timezone)

const { calculateSunriseSunset } = require("astrology-insights");

const { sunrise, sunset } = calculateSunriseSunset("2026-03-21", 28.6139, 77.209, "Asia/Kolkata");
// sunrise: "06:25:46", sunset: "18:33:45"

calculateChoghadiya(date, sunrise, sunset, timezone)

const { calculateChoghadiya } = require("astrology-insights");

const choghadiya = calculateChoghadiya("2026-03-21", sunrise, sunset, "Asia/Kolkata");
// choghadiya.daytimeChoghadiyas: 8 periods
// choghadiya.nighttimeChoghadiyas: 8 periods
// choghadiya.auspicious: ["Amrit", "Shubh", "Labh"]

calculateAbhijeetMuhurt(date, sunrise, sunset, latitude, longitude, timezone)

const { calculateAbhijeetMuhurt } = require("astrology-insights");

const muhurt = calculateAbhijeetMuhurt("2026-03-21", sunrise, sunset, 28.6139, 77.209, "Asia/Kolkata");
// { start: "12:05:29", end: "12:54:01" }

calculateRahuKalam(date, sunrise, sunset, timezone)

const { calculateRahuKalam } = require("astrology-insights");

const rahu = calculateRahuKalam("2026-03-21", sunrise, sunset, "Asia/Kolkata");
// { start: "09:27:45", end: "10:58:45" }

calculateGulikaKalam(date, sunrise, sunset, timezone)

Breaking change in v2.0.0: Previously accepted a date string only. Now requires (date, sunrise, sunset, timezone) -- same signature as Rahu Kalam.

const { calculateGulikaKalam } = require("astrology-insights");

const gulika = calculateGulikaKalam("2026-03-21", sunrise, sunset, "Asia/Kolkata");
// { start: "06:25:46", end: "07:56:45" }

calculateDurMuhurtam(date, sunrise, sunset, timezone)

const { calculateDurMuhurtam } = require("astrology-insights");

const dur = calculateDurMuhurtam("2026-03-21", sunrise, sunset, "Asia/Kolkata");
// Inauspicious time periods for the day

calculateYamghantKalam(date, sunrise, sunset, timezone)

const { calculateYamghantKalam } = require("astrology-insights");

const yamghant = calculateYamghantKalam("2026-03-21", sunrise, sunset, "Asia/Kolkata");
// Yamaganda Kalam period

calculateMoonPosition(date, latitude, longitude, timezone)

const { calculateMoonPosition } = require("astrology-insights");

const moon = calculateMoonPosition("2026-03-21", 28.6139, 77.209, "Asia/Kolkata");
// moon.getMoonPosition: { azimuth, altitude, distance, parallacticAngle }
// moon.getMoonIllumination: { fraction, phase, angle }
// moon.getMoonTimes: { rise: "07:27:08", set: "21:07:18" }

calculateBioRhythms(dateOfBirth, targetDate)

const { calculateBioRhythms } = require("astrology-insights");

const bio = calculateBioRhythms("1991-12-10", "2026-03-21");
// bio.data: Physical, Emotional, Intellectual, Intuitive cycles

React Native

The package provides a React Native compatible entry point at index.rn.js. It excludes Swiss Ephemeris (native module not available on RN) and exports:

• All legacy utility modules (work offline on device)
• fetchPanchang() for server-side Swiss Ephemeris precision via API

// Automatically resolved via "react-native" field in package.json
const { fetchPanchang, calculateSunriseSunset } = require("astrology-insights");

// Fetch full Panchang from your API
const result = await fetchPanchang(
  "2026-03-21",
  28.6139,
  77.209,
  "Asia/Kolkata",
  "https://your-app.vercel.app/api/panchang"
);

// Or use offline utilities directly
const { sunrise, sunset } = calculateSunriseSunset("2026-03-21", 28.6139, 77.209, "Asia/Kolkata");

Validation Against Drik Panchang

Cross-validated for March 21, 2026 (Delhi, 28.6139N, 77.209E):

| Field | Our Value | Drik Panchang | Match | |---|---|---|---| | Tithi | Shukla Tritiya | Shukla Tritiya | YES | | Nakshatra | Ashwini | Ashwini | YES | | Yoga | Indra | Indra | YES | | Karana | Taitila | Taitila | YES | | Vara | Saturday | Saturday | YES | | Sunrise | 06:25 | 06:24 | ~1 min | | Sunset | 18:33 | 18:33 | YES | | Moon Sign | Aries | Aries | YES | | Sun Sign | Pisces | Pisces | YES | | Paksha | Shukla | Shukla | YES | | Brahma Muhurta | 04:48-05:36 | 04:49-05:37 | ~1 min | | Pratah Sandhya | 05:14-06:25 | 05:13-06:24 | ~1 min | | Abhijit Muhurat | 12:04-12:53 | 12:04-12:53 | YES | | Vijaya Muhurat | 14:30-15:19 | 14:30-15:18 | ~1 min | | Godhuli Muhurat | 18:32-18:55 | 18:32-18:55 | YES | | Sayahna Sandhya | 18:33-19:44 | 18:33-19:44 | YES | | Nishita Muhurat | 00:05-00:53 | 00:04-00:52 | ~1 min | | Rahu Kalam | 09:27-10:58 | 09:26-10:57 | ~1 min | | Yamaganda | 14:00-15:30 | 14:00-15:31 | ~1 min | | Gulika Kalam | 06:25-07:56 | 06:24-07:55 | ~1 min | | Dur Muhurtam | 06:25-07:13 | 06:24-07:13 | ~1 min | | Vikram Samvat | 2083 | 2083 | YES | | Shaka Samvat | 1948 | 1948 | YES | | Samvatsar | Siddharthi | Siddharthi | YES | | Ritu | Vasanta | Vasanta | YES | | Ayana | Uttarayana | Uttarayana | YES | | Dinamana | 12h 08m | 12h 08m | YES |

Score: 28/29 fields match (moonrise has ~8 min variance due to SunCalc library limitation for lunar calculations).

Also validated against historical dates:

• October 20, 2025 (Diwali) -- Chaturdashi, Hasta, Shakuni confirmed
• January 14, 2026 (Makar Sankranti) -- Ekadashi, Anuradha confirmed
• August 15, 1947 (Independence Day) -- historical accuracy verified

Deployment (Vercel Serverless API)

The package includes a ready-to-deploy Vercel Serverless Function at api/panchang.js.

cd astrology-insights
npx vercel

Test the endpoint:

curl "https://your-app.vercel.app/api/panchang?date=2026-03-21&lat=28.6139&lon=77.209&tz=Asia/Kolkata"

| Param | Type | Required | Example | |---|---|---|---| | date | string | Yes | 2026-03-21 | | lat | number | Yes | 28.6139 | | lon | number | Yes | 77.209 | | tz | string | Yes | Asia/Kolkata |

Responses are cached for 1 hour (s-maxage=3600) with stale-while-revalidate for 24 hours.

Breaking Changes from v1

v2.0.0

• calculateGulikaKalam signature changed from (date) to (date, sunrise, sunset, timezone) -- now matches Rahu Kalam's signature.
• calculateNakshatraV2 replaces the old calculateNakshatra for core nakshatra calculation from raw longitude. The legacy calculateNakshatras module is still exported for backward compatibility.

v2.1.0

• Added birth chart module: calculateBirthChart, analysis APIs, dosha detection, divisional charts, Vimshottari Dasha, and recommendations.
• No breaking changes from v2.0.0.

Testing

npm run test         # Legacy test (node test.js)
npm run test:unit    # Jest unit tests (62 tests)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Write tests for new functionality
4. Ensure all tests pass: npm run test:unit
5. Submit a pull request

Please follow existing code style and add JSDoc comments to all public functions.

License

MIT License. See LICENSE for details.

Acknowledgments

• Swiss Ephemeris (swisseph) -- high-precision planetary positions
• Luxon -- date-time utilities
• SunCalc -- sunrise/sunset and moon calculations
• Vedic astrology principles for Panchang, Kundli, Dasha, and Muhurat calculations