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. Roxy 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
• Panchang calendars with rahu kaal, abhijit muhurta, choghadiya, hora
• KP (Krishnamurti Paddhati) horary and birth charts with sub-lords
• Manglik, Kaal Sarp, and Sade Sati dosha reports

Prerequisites

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

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require 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=Mumbai" \
  -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": 19.076,
    "longitude": 72.8777,
    "timezone": "Asia/Kolkata"
  }'

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: loc } = await roxy.location.searchCities({
  query: { q: 'Mumbai' },
});
const { latitude, longitude, timezone } = loc.cities[0];

const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude, longitude, timezone,
  },
});

console.log(kundli.meta.Moon.nakshatra.name); // Moon nakshatra, most important field
console.log(kundli.meta.Sun.rashi);           // Sun rashi

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

loc = roxy.location.search_cities(q='Mumbai')
city = loc['cities'][0]

kundli = roxy.vedic_astrology.generate_birth_chart(
    date='1990-07-15', time='14:30:00',
    latitude=city['latitude'], longitude=city['longitude'],
    timezone=city['timezone'],
)
print(kundli['meta']['Moon']['nakshatra']['name'])
print(kundli['meta']['Sun']['rashi'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$loc = $roxy->location->searchCities(q: 'Mumbai');
$city = $loc['cities'][0];

$kundli = $roxy->vedicAstrology->generateBirthChart(
    date: '1990-07-15',
    time: '14:30:00',
    latitude: $city['latitude'],
    longitude: $city['longitude'],
    timezone: $city['timezone'],
);
echo $kundli['meta']['Moon']['nakshatra']['name'];
echo $kundli['meta']['Sun']['rashi'];

claude mcp add-json --scope user roxy-vedic '{"type":"http","url":"https://roxyapi.com/mcp/vedic-astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

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

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

Three endpoints in the dasha series.

• POST /vedic-astrology/dasha/current returns the active mahadasha, antardasha, pratyantardasha, and how much time is left in each. Highest-value single-shot Vedic query.
• POST /vedic-astrology/dasha/major returns the full 120-year timeline with all nine mahadashas.
• POST /vedic-astrology/dasha/sub/{mahadasha} expands a single mahadasha into its nine antardashas.

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

Panchang, the Hindu calendar

• POST /vedic-astrology/panchang/basic gives tithi, nakshatra, yoga, karana for a date and location.
• POST /vedic-astrology/panchang/detailed gives 15+ muhurtas in one call, including rahu kaal, abhijit, brahma, vijaya, nishita, godhuli, chandrabalam, tarabalam. This is the India matrimonial-app spec.
• POST /vedic-astrology/panchang/choghadiya returns 8 day and 8 night choghadiya periods for electional timing.
• POST /vedic-astrology/panchang/hora returns 12 day horas and 12 night horas for planetary-hour features.

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.

Doshas, the matrimonial red flags

• POST /vedic-astrology/dosha/manglik checks Mangal dosha, returns severity, exceptions, remedies, effects on marriage.
• POST /vedic-astrology/dosha/kalsarpa checks Kaal Sarp dosha with type and remedies.
• POST /vedic-astrology/dosha/sadhesati checks the 7.5-year Saturn phase.

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/kp/chart returns cusps, planets, nodes, significators.
• POST /vedic-astrology/kp/planets returns per-planet signLord, nakshatraLord, starLord, subLord, subSubLord, kpNumber.
• POST /vedic-astrology/kp/ruling-planets is the KP horary endpoint. Answers "will X happen" using ruling planets at the moment of the query.

Navamsa (D9)

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.

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.5 or "Asia/Kolkata". IANA is DST-resolved against the birth date. Vedic endpoints default to 5.5 (IST) if omitted, but do not rely on this for non-Indian births.
• 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.