# 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](/pricing).
2. The birth city. We geocode it for you in step 1.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

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


### curl
```bash
# 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"
  }'
```

### TypeScript SDK
```typescript
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
```

### Python SDK
```python
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 SDK
```php
<?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'];
```

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

Also add `roxy-location` the same way. Then ask Claude, "generate the kundli for someone born July 15 1990 at 2:30 PM in Mumbai." The agent geocodes, fills the chart request, and summarizes the result. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

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`](/docs/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.

```tsx
'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`](/api-reference#tag/vedic-astrology/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.

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

**Tip: `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](/docs/ui)), 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`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/dasha/major) returns the full 120-year timeline with all nine mahadashas.
- [`POST /vedic-astrology/dasha/sub/{mahadasha}`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/panchang/basic) gives tithi, nakshatra, yoga, karana for a date and location.
- [`POST /vedic-astrology/panchang/detailed`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/panchang/choghadiya) returns 8 day and 8 night choghadiya periods for electional timing.
- [`POST /vedic-astrology/panchang/hora`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/dosha/manglik) checks Mangal dosha, returns severity, exceptions, remedies, effects on marriage.
- [`POST /vedic-astrology/dosha/kalsarpa`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/dosha/kalsarpa) checks Kaal Sarp dosha with type and remedies.
- [`POST /vedic-astrology/dosha/sadhesati`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/kp/chart) returns cusps, planets, nodes, significators.
- [`POST /vedic-astrology/kp/planets`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/kp/planets) returns per-planet signLord, nakshatraLord, starLord, subLord, subSubLord, kpNumber.
- [`POST /vedic-astrology/kp/ruling-planets`](/api-reference#tag/vedic-astrology/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`](/api-reference#tag/vedic-astrology/POST/vedic-astrology/navamsa) returns the classical marriage chart with vargottama planets. For any other varga, [`POST /vedic-astrology/divisional-chart`](/api-reference#tag/vedic-astrology/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](/api-reference#tag/vedic-astrology).

## Ready-made starter

The [/starters/jyotish-vedic-astrology-app](/starters/jyotish-vedic-astrology-app) (web) or [/starters/vedic-astrology-starter-app](/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](/docs/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](/docs/tutorials/ai-chatbot) wires Vedic endpoints through MCP so an agent can answer kundli questions in conversation. For a custom build, the [Next.js integration guide](/docs/integrations/nextjs) is the fastest path to a deployed matrimonial UI. Power users building KP tooling should read the [SDK guide](/docs/sdk) for typed calls.