Pillar B — Build guides
Published 2026-05-28 · Updated 2026-06-18 · By Avinash Chandan, Founder, Navamsha
Build a Kundli Generator in Next.js Using Navamsha API
A Kundli generator is a web app that accepts birth date, time, and place, then renders a sidereal birth chart (Janam Kundli) with lagna, planetary positions, and Nakshatra data. This guide walks through building one in Next.js using Navamsha's Kundali API on the free tier — 10,000 calls per month, no credit card required.
What you need before you start
- A free Navamsha account and API key — sign up at /auth/signup, then create a key in the dashboard.
- Next.js 14+ with the App Router (this pattern works in Route Handlers and Server Components).
- An environment variable NAVAMSHA_API_KEY — never expose the raw key in client-side code.
- Birth inputs: date (YYYY-MM-DD), time (HH:MM, 24-hour), latitude, and longitude.
Free tier walkthrough
The launch free tier gives you 10,000 API calls per month. A typical Kundli page makes one call to GET /api/v1/kundali/basic (1 credit). That means you can serve thousands of chart generations during development and early production without upgrading. Create your key at /getting-started, copy it once, and store it as NAVAMSHA_API_KEY in .env.local.
Verify with curl
curl — basic Kundali
curl -G "https://api.navamsha.in/api/v1/kundali/basic" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "date=1995-08-15" \ --data-urlencode "time=14:30" \ --data-urlencode "latitude=19.0760" \ --data-urlencode "longitude=72.8777"
Python — httpx
import httpx
import os
resp = httpx.get(
"https://api.navamsha.in/api/v1/kundali/basic",
headers={"X-API-Key": os.environ["NAVAMSHA_API_KEY"]},
params={
"date": "1995-08-15",
"time": "14:30",
"latitude": 19.0760,
"longitude": 72.8777,
},
timeout=30.0,
)
resp.raise_for_status()
chart = resp.json()
print(chart["data"]["ascendant"]["sign"])
print(chart["meta"]["ayanamsa"])Next.js Route Handler (server-side fetch)
Keep the API key on the server. A Route Handler proxies birth inputs to Navamsha and returns chart JSON to your React components. Add NAVAMSHA_API_KEY to .env.local — do not prefix it with NEXT_PUBLIC_.
app/api/kundli/route.ts
import { NextRequest, NextResponse } from "next/server";
const API_BASE = process.env.NAVAMSHA_API_BASE_URL ?? "https://api.navamsha.in";
export async function GET(request: NextRequest) {
const key = process.env.NAVAMSHA_API_KEY;
if (!key) {
return NextResponse.json({ error: "Missing NAVAMSHA_API_KEY" }, { status: 500 });
}
const { searchParams } = request.nextUrl;
const query = new URLSearchParams({
date: searchParams.get("date") ?? "",
time: searchParams.get("time") ?? "",
latitude: searchParams.get("latitude") ?? "",
longitude: searchParams.get("longitude") ?? "",
});
const res = await fetch(`${API_BASE}/api/v1/kundali/basic?${query}`, {
headers: { "X-API-Key": key },
next: { revalidate: 3600 },
});
if (!res.ok) {
return NextResponse.json({ error: "Chart request failed" }, { status: res.status });
}
return NextResponse.json(await res.json());
}Client component — call your Route Handler
"use client";
import { useState } from "react";
export function KundliForm() {
const [chart, setChart] = useState<unknown>(null);
async function generate(form: FormData) {
const params = new URLSearchParams({
date: String(form.get("date")),
time: String(form.get("time")),
latitude: String(form.get("latitude")),
longitude: String(form.get("longitude")),
});
const res = await fetch(`/api/kundli?${params}`);
setChart(await res.json());
}
return (
<form action={generate}>
{/* date, time, lat, lng inputs */}
<button type="submit">Generate Kundli</button>
{chart ? <pre>{JSON.stringify(chart, null, 2)}</pre> : null}
</form>
);
}JavaScript fetch (Node or browser via your proxy)
const params = new URLSearchParams({
date: "1995-08-15",
time: "14:30",
latitude: "19.0760",
longitude: "72.8777",
});
const res = await fetch(`/api/kundli?${params}`);
const { data, meta } = await res.json();
console.log(data.ascendant.sign, meta.ayanamsa);Rendering the chart
The basic Kundali response includes ascendant, planets (sign, house, Nakshatra, degrees), and reference_sign for whole-sign house layout. Map planets to a North or South Indian chart SVG, or start with a table view while you iterate on design. Log or display the meta block so users know which ayanamsa and engine version produced the chart.
| Response field | Use in UI |
|---|---|
| data.ascendant | Lagna sign, degree, Nakshatra |
| data.planets | Planet rows for chart wheel or table |
| data.reference_sign | Whole-sign house reference (usually lagna) |
| meta.ayanamsa | Display 'Lahiri' badge for trust |
| meta.engine | Audit trail for support tickets |
Next steps
- Add Vimshottari Dasha via /apis/dasha for timing features.
- Use geocoding separately — Navamsha expects coordinates, not place names.
- Browse /apis/kundali for extended planets and divisional charts.
- Open Swagger at the live docs URL when you need exact parameter names.
FAQ
Can I call the Navamsha API directly from the browser?
Not with your secret API key — any key in client JavaScript is visible to users. Proxy through a Next.js Route Handler, Server Action, or backend service and keep NAVAMSHA_API_KEY server-side only.
Which Kundali endpoint should I start with?
GET /api/v1/kundali/basic is the lightest starting point: lagna, classical planets, houses, and Nakshatra data in one call (1 credit). See /apis/kundali for extended and divisional endpoints when you need more depth.
Does the free tier require a credit card?
No. Sign up at www.navamsha.in/auth/signup, create an API key in the dashboard, and you get 10,000 calls per month on the launch tier. Follow /getting-started for the full three-step flow.
What if birth time is approximate?
Chart accuracy depends on birth time — especially Moon degree, ascendant, and house placements. Surface this in your UI. For rough time, consider showing a range or prompting users to confirm with a birth certificate or hospital record.