RoxyAPI
Quick StartPlaygroundSDKMCP SetupFree TemplatesAGENTS.md
  1. Docs
  3. Domain Guides
  5. Vedic Astrology

Kundli API and Vedic Astrology, what to build and how to call it

Ship a kundli generator, a Gun Milan matchmaker, a panchang calendar, or a full KP chart in under 30 minutes. No Jyotish knowledge required.

Vedic astrology is the depth moat. The India astrology market is on a 49% CAGR, and every matrimonial platform, muhurat app, and KP tool needs the same handful of endpoints. Kundli, panchang, dasha, dosha, and KP are the five search-dominant queries in the space. RoxyAPI gives you all of them under one key.

What you can build

  • Kundli generators and matrimonial matchmaking platforms
  • Gun Milan 36-point compatibility checks with dosha cancellation
  • Vimshottari Dasha timelines with mahadasha, antardasha, pratyantardasha, sookshma, prana
  • Panchang calendars with rahu kaal, abhijit muhurta, choghadiya, hora
  • Daily reading features that answer "how is today for this person" in a single call
  • KP (Krishnamurti Paddhati) horary and birth charts with sub-lords
  • Manglik, Kaal Sarp, and Sade Sati dosha reports

Prerequisites

  1. A RoxyAPI key. Get one on the pricing page.
  2. The birth city. We geocode it for you in step 1.

Install

npm install @roxyapi/sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the endpoint

The #1 Vedic call is the birth chart (kundli). Every matrimonial and Jyotish product starts here. The canonical two-step pattern is geocode the city, then post the chart. Pick a language.

# 1. geocode the city
curl "https://roxyapi.com/api/v2/location/search?q=London" \
  -H "X-API-Key: $ROXY_API_KEY"
# returns cities[0] with latitude, longitude, timezone (IANA)

# 2. post the kundli request
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/birth-chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

The response groups planets two ways. The 12 rashi keys (aries through pisces) each list the planets sitting in that sign, so you can render the north-Indian 12-house chart by iterating them. The top-level meta keyed by planet name gives you direct lookup with rashi, longitude, nakshatra (with ratio and left decimals for pada precision), isRetrograde, combustion, and planetaryWar.

Render the result

The @roxyapi/ui library ships <roxy-vedic-kundli>, a drop-in South, North, or East Indian render path, so the 12-sign grid is one element. Geocode first, fetch the chart on your server with the secret key, then hand the unwrapped response to the component and it draws the chart. Want your own layout? The response is plain JSON, render it however you like.

'use client';
import { RoxyVedicKundli, type RoxyVedicKundliProps } from '@roxyapi/ui-react';

// chart = unwrapped /vedic-astrology/birth-chart response from your backend route
export function Kundli({ chart }: { chart: RoxyVedicKundliProps['data'] }) {
  return <RoxyVedicKundli data={chart} chartStyle="south" />;
}

Switch chartStyle to "north" or "east" for the other regional layouts. Want the tabular planet breakdown (degree, nakshatra, pada, lord, bhava, avastha) alongside the wheel? Pass the same birth-chart response to <roxy-vedic-planets-table>. The Moon nakshatra is the most important Vedic placement because it drives the dasha sequence, and the component surfaces it for you.

Ship the rest

Gun Milan, the matrimonial core

POST /vedic-astrology/compatibility takes two people and returns the full 36-point Ashtakoota score with 8 sub-scores (Varna, Vasya, Tara, Yoni, Maitri, Gana, Bhakoot, Nadi) plus dosha cancellation logic. This is the endpoint behind every Indian matrimonial app.

curl -X POST https://roxyapi.com/api/v2/vedic-astrology/compatibility \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {"date":"1990-07-15","time":"14:30:00","latitude":19.076,"longitude":72.8777,"timezone":5.5},
    "person2": {"date":"1992-03-22","time":"09:00:00","latitude":28.6139,"longitude":77.209,"timezone":5.5}
  }'

breakdown[] returns all 8 kutas with individual scores. Show the total as the headline and the sub-scores as a radar chart. doshas[] and doshaCancellations[] tell you which red flags apply and whether they cancel out.

Render it with <roxy-guna-milan> (RoxyGunaMilan in @roxyapi/ui-react), the 36-point Ashtakoota card with all eight sub-scores. Pass the unwrapped compatibility response straight to data.

Vimshottari Dasha, the life-phase engine

Six endpoints in the dasha series. The four sub routes are a drill-down chain: each one expands a single period from the level above it into its nine children, so a UI makes exactly one call per expand.

One thing to expect when you drill into the chart's FIRST mahadasha: it returns fewer than nine sub-periods. The Vimshottari cycle is already running when someone is born, so that mahadasha began before the birth date and the sub-periods that finished beforehand are not part of the chart. The one in force at birth starts on the birth date and carries a nominalStartDate showing where it really began. Asking for a sub-period that ended before birth returns a 400 naming the ones you can ask for. Every other mahadasha returns all nine.

Each response also echoes moonLongitude, ayanamsa and ayanamsaType, the exact sidereal Moon position and frame the dates were derived from, so you can reconcile any date against a reference chart without guesswork.

Every dasha route takes an optional ayanamsa field: lahiri (the default, matching traditional Vedic software), kp-newcomb, or kp-old. Dasha boundaries come from where the birth Moon sits in its nakshatra, so switching frames moves every date by weeks. Send the frame your reference software uses and the tables line up.

KP significators on a dasha period

Send "significators": true on any dasha route and every period in the response gains a significators block for its lord: the starLord and subLord from the KP birth chart, the house it occupies, the houses it signifies broken out by tier in signifies.L1 to signifies.L4, a flat signifiedHouses list ordered strongest first, the strongHouses subset reached at the two strongest tiers, and a strength grade. Leave the field off and the response is byte for byte what it was before, so this cannot disturb an existing integration.

The grading follows standard KP practice, where the significators of a house rank A planets in the star of the occupant, B occupants, C planets in the star of the house owner, D the owner, weighted 100, 75, 50 and 25 percent. Each house is counted once, at the strongest tier it is reached, and strength.score is the mean across them, which is what grade and label band. A high grade means the lord is firmly connected to the houses it signifies, not that those houses are favourable: whether 2, 7 and 11 are the right houses depends on the question you are asking.

/dasha/current additionally returns commonHouses, the houses the running lords agree on: dashaBhuktiAntara for the classical three-lord test, and allLevels for the houses carried by all five running lords at once. The chart is erected on Placidus cusps in the same ayanamsa you selected for the dasha, and nodeType (mean or true) applies to Rahu and Ketu here only. Placidus has no solution at the poles, so significators is rejected with a 400 above latitude 66.56 while the dasha dates themselves still work anywhere.

Render any of them with <roxy-dasha-timeline> (RoxyDashaTimeline), setting period to "current", "major", or "sub" to match the endpoint you called.

Panchang, the Hindu calendar

Render basic or detailed with <roxy-panchang-table> (RoxyPanchangTable), setting detail="detailed" to surface the full muhurta set or detail="basic" for the five-limb view.

The daily reading, one person and one day in one call

POST /vedic-astrology/daily (getVedicDailyReading) answers the question a daily-horoscope feature actually needs: how is this date for this native. It is the reading a Jyotishi assembles by hand from five or six separate charts, returned as one structured response.

curl -X POST https://roxyapi.com/api/v2/vedic-astrology/daily \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1984-11-03",
    "birthTime": "01:35:00",
    "latitude": 28.8944,
    "longitude": 76.5894,
    "timezone": 5.5,
    "date": "2026-06-21"
  }'

What comes back, and every part of it is classical rather than a house style:

  • grahas[], all nine transiting grahas judged by Gochara counted from the Janma Rashi, which is the reference Phaladeepika prescribes for transit results. Each one carries the house it makes from the natal Moon, its Ashtakavarga bindus in the sign it is crossing, the vedha pair that can cancel it, its dignity and combustion, the drishti falling on it, and a single state naming what all of that came to. stateSource names the classical rule that decided it, so a verdict is auditable rather than opaque.
  • panchanga, the four limbs resolved for the day, each with the instant it gives way and the limb that follows, so you can label the whole day instead of asserting one value for it. The panchanga day runs sunrise to sunrise at the birth coordinates, not midnight to midnight.
  • tara[] and chandrabala[], tarabala and chandrabala resolved for THIS native rather than as the day-wide lists, with Ashtama Chandra as its own flag. Both are arrays of time windows, because the Moon can change nakshatra or rashi partway through a day and a single value would be wrong for the rest of it.
  • dasha[], the running Vimshottari chain three levels deep, which is the period the day is being read inside.
  • areas.finance, a KP reading of the money houses off the running dasha lords, with drivers and cautions naming every lord-to-house connection behind the number.
  • score, verdict and tally, a strength reading with its full per-state breakdown. The arithmetic is published in the field description and recomputes by hand from tally alone, so you can show a customer where the number came from.
  • frames, the sidereal frames behind the reading and which sections each one produced. There is no ayanamsa request field here, unlike the dasha and KP routes, because the reading computes in more than one frame at once and tells you which produced what.

score is a rare-high scale, not a mark out of 100. Classical transit rules cancel far more often than they deliver, so most days land in the lower bands and a high score is genuinely uncommon. Render it as a strength reading with its verdict band and its tally, never as a progress bar out of 100, or an ordinary day will read to your users as a bad one.

?focus=finance swaps the twelve house themes into money vocabulary, exactly as it does on the dasha routes, and changes no number in the response. ?lang= is honoured throughout. A location inside the polar circle still returns its gochara, panchang and dasha, with degraded[] naming the part that could not be computed there rather than failing the call.

Doshas, the matrimonial red flags

Render each with <roxy-dosha-card> (RoxyDoshaCard), setting type to "manglik", "kalsarpa", or "sadhesati" to match the response. The card surfaces presence, severity, and remedies for you.

KP system, the practitioner differentiator

KP (Krishnamurti Paddhati) endpoints expose sub-lord and sub-sub-lord data that generic Vedic APIs do not return. Three endpoints, same BirthDataSchema plus optional ayanamsa (kp-newcomb default, kp-old, lahiri, or custom).

POST /vedic-astrology/navamsa returns the classical marriage chart with vargottama planets. For any other varga, POST /vedic-astrology/divisional-chart takes a division integer (2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60).

Render either with <roxy-divisional-chart> (RoxyDivisionalChart), the generic varga wheel. Set chartStyle to "south", "north", or "east" for the regional layout.

Yoga detection, 48 verdicts from one chart

POST /vedic-astrology/yoga/detect (detectYogas) scans a computed kundli and returns 48 verdicts: the 12 classical yogas, all 32 Nabhasa, and the four wealth and poverty verdicts (Dhana, Daridra, Lakshmi, Dhana Malika), grouped by family (classical, asraya, dala, akriti, sankhya). Each entry carries present, quality, and an evidence string naming the rule that triggered or failed, so a verdict is auditable rather than opaque.

The four wealth verdicts each answer for a whole family of classical combinations rather than for one, so evidence names every rule that matched and the exact condition it matched on, and a rule that rests on a single authority is left out of the verdict and says so. Raja Yoga remains glossary-only: it lives in GET /vedic-astrology/yoga (listYogas), a dictionary lookup that inspects no chart.

The Jaimini layer: Arudha padas and Chara Karakas

POST /vedic-astrology/arudha (calculateArudhaPadas) returns all twelve Jaimini padas, AL through UL, with the derivation attached so the classical exception is visible rather than assumed.

POST /vedic-astrology/chara-karakas (calculateCharaKarakas) ranks the karaka offices and lifts atmakaraka and darakaraka to the top level.

const [arudha, charaKarakas] = await Promise.all([
  roxy.vedicAstrology.calculateArudhaPadas({ body: birth }),
  roxy.vedicAstrology.calculateCharaKarakas({ body: { ...birth, scheme: 'eight' } }),
]);

scheme is a BODY field, not a query parameter. Passing it in the query string is ignored rather than rejected, so the call returns 200 with the default eight ranking and nothing signals the choice was dropped. The eight scheme ranks Rahu and includes Pitrikaraka; seven drops both. The two can name a different Atmakaraka for the same birth.

Avastha readings

The birth chart returns each graha state across three systems (Baladi, Jagradadi, Deeptadi) as bare Sanskrit names. The translated readings live at GET /vedic-astrology/avasthas (listAvasthas) and getAvastha, joined on id === name.toLowerCase(). Filter with ?system=jagradadi, and the readings honour ?lang=.

See the full list at the Vedic Astrology API reference.

Ready-made starter

The /starters/jyotish-vedic-astrology-app (web) or /starters/vedic-astrology-starter-app (mobile) starter ships a working Vedic astrology app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, drop in <roxy-vedic-kundli> from @roxyapi/ui.

Gotchas

  • Timezone accepts decimal or IANA string (2026-04-23). Pass -5 or "America/New_York". IANA is DST-resolved against the birth date. Vedic endpoints default to 5.5 if omitted, but always pass an explicit timezone for births outside that offset.
  • Ayanamsa is server-side. Lahiri is the default for standard Vedic endpoints, KP uses kp-newcomb. Do not subtract ayanamsa in client code to "correct" positions, the server already did.
  • Tithi count is 30, not 2. There are 15 Shukla and 15 Krishna tithis. Older LLM training data conflates Purnima and Amavasya, our split is authoritative.
  • Rahu and Ketu are shadow points, not planets. KP endpoints let you pick true-node or mean-node via nodeType. Default is mean node. Pick consciously if your product compares against a specific set of practitioner tables.
  • Nakshatra count is 27. Abhijit is not an endpoint in the standard 27 scheme.
  • The detailed panchang endpoint takes date, not time. Sunrise and sunset anchor the muhurtas for that full day at that location.

What to build next

The AI chatbot tutorial wires Vedic endpoints through MCP so an agent can answer kundli questions in conversation. For a custom build, the Next.js integration guide is the fastest path to a deployed matrimonial UI. Power users building KP tooling should read the SDK guide for typed calls.