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, sookshma
• 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

dotnet add package 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"
  }'

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

const { data: loc } = await roxy.location.searchCities({
  query: { q: 'London' },
});
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='London')
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: 'London');
$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'];

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var loc = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "London");
var city = loc!.Cities![0];

var kundli = await roxy.VedicAstrology.BirthChart.PostAsync(new()
{
    Date = new Date(1990, 7, 15),
    Time = "14:30:00",
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});

Console.WriteLine(kundli!.Houses!.Count);  // 12 bhavas
// Rashis (kundli.Aries, kundli.Taurus, ...) and yogas are typed; the per-planet meta map is a dynamic object

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

Five endpoints in the dasha series. The three 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.

• POST /vedic-astrology/dasha/current returns the active mahadasha, antardasha, pratyantardasha, and sookshma dasha, plus how much time is left in each. Highest-value single-shot Vedic query, and everything a current DBA readout needs.
• 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.
• POST /vedic-astrology/dasha/sub/{mahadasha}/{antardasha} expands one antardasha into its nine pratyantardashas.
• POST /vedic-astrology/dasha/sub/{mahadasha}/{antardasha}/{pratyantardasha} expands one pratyantardasha into its nine sookshma dashas, periods of roughly three to thirty days.

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.

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

• 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 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.