Authentication
Working from real payloads: every endpoint's exact request and response JSON — captured live, downloadable, nothing hand-written — is on the API samples page.
All API requests require authentication via an API key. Include your API key in the X-Api-Key header with every request.
Important: Your API key is linked to verified domains/IPs. Requests from unverified origins will be rejected. Add domains and IPs in your Dashboard.
Every endpoint on this page requires a key. There is no public or trial
access: a request without X-Api-Key is answered with 401, and a key
calling from an origin you have not verified is answered with 403. The only
exception is GET /v1/health, which returns service status and no astrology data.
Keep the key on your server. If you call KundliAPI straight from a browser or a mobile app, the key ships to every user who opens developer tools — proxy the call through your own backend instead, and keep the verified-origin list as small as it can be.
Base Parameters
Most astrology endpoints require the following birth data parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
day | Integer | Required | Birth day (1-31) |
month | Integer | Required | Birth month (1-12) |
year | Integer | Required | Birth year (e.g., 1990) |
hour | Integer | Required | Birth hour in 24h format (0-23) |
min | Integer | Required | Birth minute (0-59) |
lat | Float | Required | Birth latitude (e.g., 28.6139) |
lon | Float | Required | Birth longitude (e.g., 77.2090) |
tzone | Float | Required | Timezone offset (e.g., 5.5 for IST) |
Getting latitude/longitude for a birth place
KundliAPI does not provide a geocoding (place name → lat/lon) endpoint for API customers, and we recommend against building on top of our internal one even if you discover it — it's meant only for kundliapi.com's own website and isn't covered by our uptime/rate-limit guarantees; it can change or be throttled without notice.
Convert your users' birth place into coordinates using your own mapping provider before calling KundliAPI — e.g. Google Maps Geocoding API, Mapbox Geocoding API, or OpenStreetMap Nominatim (self-hosted or via your own paid usage tier). Cache the result against the place name on your side so you're not re-geocoding on every request.
Accuracy matters here: every downstream calculation (Ascendant, houses, Dasha, Dosha — everything) is computed directly from the exact latitude/longitude/timezone you send. Sending an approximate or wrong location produces a fully self-consistent but incorrect chart, with nothing in the response to indicate it. Always validate that lat/lon/tzone are present and correspond to the actual birth place before calling the API — do not fall back to a default city if your own geocoding step fails.
Language
Language is chosen per request — there is no account-level or key-level language setting, so the same key can ask for Hindi on one call and English on the next.
| Parameter | Where | Values | Effect |
|---|---|---|---|
lang | Request body | hi (default), en | Language of the generated text: predictions, horoscope, remedies, mantra meanings. |
labelLang | Request body, chart endpoints only | en | Returns rashi and gender labels in English instead of Devanagari. |
Charts use a separate field on purpose: lang already had a meaning there before
labelLang existed, and changing it would have altered what live integrations
receive. Send labelLang: "en" for English chart labels; omit it and the response is
exactly what it has always been.
Panchang names (tithi, nakshatra, yoga, karana, chaughadiya) are returned in Hindi in both modes; they come from the panchang tables rather than the text layer.
Error Handling
The API returns standard HTTP status codes:
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad Request — missing or invalid parameters |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — domain/IP not verified |
429 | Rate limit exceeded |
500 | Internal server error |
Panchang
Complete Hindu Panchang data including Tithi, Nakshatra, Yoga, Karana, and timings.
Returns complete Panchang data for the given date and location.
Request Body:
Response includes:
Tithi, Nakshatra, Yoga, Karana, Sunrise, Sunset, Moonrise, Moonset, Rahu Kaal, Gulika Kaal, Yamaganda, Abhijit Muhurat, etc.
Returns Choghadiya timings for the day — auspicious and inauspicious periods.
Muhurat Timings
Returns planetary Hora timings for the day.
Astro Data
Get basic and extended astrological data for a birth chart.
Returns ascendant sign, nakshatra, deity, and Moon sign information.
Example Request (cURL):
Note: Ascendant lord, Rashi lord, Varna, Yoni, Gan, and Nadi are already included in the get_astro_data response above — there is no separate "extended details" endpoint.
Planet Positions
Get planetary positions, dignity, aspects, and house placements.
Returns positions of all 9 planets (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) with sign, degree, nakshatra, house, and retrograde status. Note: this is /planet/ (singular).
Note: Nakshatra sub-lord and sub-sub-lord (KP-style) are returned by the KP Astrology endpoints below, not by /planet/.
Dasha System
Vimshottari and Yogini Dasha periods with precise calculations.
Returns all Vimshottari Maha Dasha periods with start/end dates. Use /v1/dasha/get_vimshottary_current_dasha for just the currently running one.
Returns Antar Dasha periods within each Maha Dasha.
Returns current running Chara (Jaimini) Dasha. Note: Jaimini-system endpoints (Chara Dasha, Chara Karakas, Karakamsha) are mounted under /v1/gemini/, not /v1/dasha/.
Returns Yogini Dasha periods — 36-year cycle system. Use /v1/dasha/get_current_yogini_dasha for just the current one.
Dosha Analysis
Check major doshas in a birth chart.
Returns Mangal (Mars) Dosha analysis with intensity and detailed description.
Returns Kaal Sarp Dosha analysis — Rahu/Ketu axis check.
Returns Pitra Dosha analysis — ancestral karma effects.
Returns Sadhesati (Saturn transit) analysis — current phase and dates.
Birth Charts
Generate divisional charts. Note: the path segment is /chart/ (singular).
Which divisions are supported
Twenty divisions are computed with their own rules:
Ask for anything else — D13, D999, abc — and the API
answers 400 naming what it does support. It will never return a D1 chart under
another division's name, so a chart you receive is always the chart you asked for.
The division may be written with or without the D, in either case:
10, D10 and d10 are the same request.
Returns Lagna (Ascendant) chart data with planet placements in houses.
Returns Navamsa chart data — used for marriage and dharma analysis. Every other division is available at /v1/chart/get_divisional_chart/:division.
One divisional chart. The division goes in the path, the birth data in the body.
Request:
Response:
rashiIndex is 1-indexed. Planet names inside chart are
two-letter codes (Su Mo Ma Me Ju Ve Sa Ra Ke). division and
divisionName appear only on this endpoint, where you named a division.
Add "labelLang": "en" to the body for English rashi and
gender labels.
Returns allDivisionalCharts with the fifteen standard vargas — D2, D3, D4,
D7, D9, D10, D12, D16, D20, D24, D27, D30, D40, D45, D60 — each in the same
chart shape as above. Use this instead of fifteen separate calls.
Returns Bhava Chalit chart — houses based on actual house cusps.
One shape difference worth knowing: get_divisional_chart,
get_moon_chart, get_sun_chart and get_chalit_chart nest
everything under chartData, while get_birth_chart returns the same
fields directly on data[0] with no chartData wrapper. Handle that one
case and the rest are identical.
Daily / Weekly / Monthly Horoscope
Sign-based readings with the life areas split into their own fields, so you can lay them out without parsing prose.
No birth data needed — just the sign.
Request Body:
sign is one of aries, taurus, gemini, cancer, leo, virgo, libra, scorpio,
sagittarius, capricorn, aquarius, pisces (case-insensitive).
Response:
The eight category keys are always present and always strings.
lucky.numbers is always two integers between 1 and 9. The text is
deterministic: the same sign on the same day returns the same sentences, so you can cache
per sign per day.
Prediction
A reading built from the birth chart: the ascendant, its lord, and what each planet is doing in the house it occupies.
Request Body:
Response (lang: "en"):
With lang absent or "hi", every one of those values comes back
in Devanagari instead.
Mantra
Traditional graha and rashi mantras, with the Devanagari text, a Roman transliteration, a plain-language meaning and the japa count. Available on starter and above.
The mantra for the weekday's ruling planet, plus the mantra for the moon sign. Every field is optional; send no date and you get today.
Request Body:
Response:
Request body: { "sign": "libra", "lang": "en" } — the sign may be given in
English or Hindi. Returns sign, lord, mantra and
beejMantra.
Request body: { "planet": "Saturn", "lang": "en" }. Omit
planet to receive all nine under mantras.
Each planet carries its beejMantra and the traditional japa count — Sun
7,000 · Moon 11,000 · Mars 10,000 · Mercury 9,000 · Jupiter 19,000 · Venus 16,000 · Saturn
23,000 · Rahu 18,000 · Ketu 17,000.
An unknown planet or sign returns 400 listing the accepted values.
Kundli Matching
Ashtakoota and other matching systems for marriage compatibility.
Returns 8-fold matching (Gun Milan) score out of 36 points.
Request Body:
Response includes scores for: Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi.
KP Astrology
Krishnamurti Paddhati system endpoints.
Returns KP house cusps with sign lord, star lord, and sub lord.
Returns planets with sign lord, star lord, sub lord — KP style.
Numerology
Complete numerology analysis endpoints.
Returns birth number, life path number, name analysis.
Additional Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | String | Required | Full name for numerology analysis |
Returns Lo Shu Grid (magic square) analysis based on birth date.
Western Astrology — Natal
Tropical/Western astrology calculations using Placidus house system.
Returns Western natal chart with tropical zodiac positions, aspects, house placements, element/modality analysis.
Response includes:
Sun sign, Moon sign, Rising sign, all planet positions in tropical zodiac, major & minor aspects with orbs, house system data, element balance, hemisphere emphasis.
Western — Synastry & Composite
Compares two birth charts for relationship compatibility. Returns inter-aspects between both charts.
Additional Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
day2, month2, year2 | Integer | Required | Second person's birth date |
hour2, min2 | Integer | Required | Second person's birth time |
latitude2, longitude2 | Float | Required | Second person's birth location |
timezone2 | Float | Required | Second person's timezone |
Returns midpoint composite chart of two people — the relationship chart. Same parameters as Synastry.
Western — Transits & Progressions
Returns Solar Return chart for a specific year (birthday chart). Add targetYear to request body.
Returns progressed chart positions (day-for-a-year method).
Returns current planetary positions in tropical zodiac.
Returns moon phases for a given month/year with New Moon, Full Moon, and quarter phases.
Western — Reports
Returns detailed personality analysis based on Western chart — Sun, Moon, Rising, elements, and aspects.
Returns romantic forecast based on Venus, Mars, 7th house and relationship aspects.
Returns karma and destiny analysis based on Saturn, Nodes, and 12th house.
Tarot Card API
Complete 78-card Tarot engine with multiple spread types.
Returns Past, Present, Future reading with full card interpretations.
Optional Parameters:
| Parameter | Type | Description |
|---|---|---|
question | String | Your question for the reading |
seed | Integer | Seed for reproducible readings |
Returns full Celtic Cross spread — the most comprehensive single-question reading.
Returns Yes, No, or Maybe answer with supporting card and explanation.
Returns today's daily tarot card with guidance message.
Returns complete deck — 22 Major Arcana + 56 Minor Arcana with all meanings.
Varshaphal (Annual Horoscope)
Vedic Solar Return / Tajika astrology system for annual predictions.
Returns annual horoscope chart with Muntha, Panchadhikari, and Harsha Bala. Add targetYear to request body.
Returns Tajika yogas: Ithasala, Easarapha, Nakta, Yamaya, Manaú, Kamboola.
Returns 16 Sahams — Punya, Vidya, Yashas, Mitra, and more.
Gochar (Transit Analysis)
Personalized transit analysis with Vedha (obstruction) logic.
Returns current transits relative to your natal Moon sign with Vedha analysis and benefic/malefic determination.
Returns detailed Saturn transit analysis — Sade Sati phase, Dhaiya, Kantaka, with start/end dates and remedies.
Returns Jupiter (Guru) transit analysis with effects based on house from Moon.
Lal Kitab
Complete Lal Kitab astrology system with unique remedies.
Returns Lal Kitab chart with Pakka Ghar assignments and sleeping/awakened planet status.
Returns planet-specific remedies — materials, donations, rituals based on house placements.
Returns 6 planetary debts: Pitru Rin, Matru Rin, Stri Rin, Swa Rin, Bandhu Rin, Sasur Rin with symptoms and remedies.
Biorhythm
Physical, Emotional, Intellectual, and extended cycles.
Returns 6 biorhythm cycles: Physical (23d), Emotional (28d), Intellectual (33d), Intuitive (38d), Aesthetic (43d), Spiritual (53d).
Compare biorhythm cycles between two people. Uses day2/month2/year2 parameters.
Human Design
BodyGraph, Type, Strategy, Authority, Gates, Channels, and Profile.
Returns complete Human Design analysis: Type (Generator, Projector, Manifestor, Reflector, MG), Strategy, Authority, Profile, all defined/undefined Centers, active Channels, Gates, and Incarnation Cross.
Returns simplified summary: Type, Strategy, Authority, Profile, defined/undefined centers list.
Yoga Combinations
Identify powerful yoga combinations in a birth chart — Raj Yoga, Dhan Yoga, Panch Mahapurush, and Moon-based yogas.
Returns all yoga combinations present in a birth chart — including Raj Yoga, Dhan Yoga, Panch Mahapurush Yoga, Chandra Yoga, and more.
Example Request (cURL):
Returns Raj Yoga analysis — combinations of Kendra and Trikona lords that indicate power, authority, and success.
Returns Dhan Yoga (wealth yoga) analysis — planetary combinations indicating financial prosperity and material gains.
Returns Panch Mahapurush Yoga analysis — Ruchaka, Bhadra, Hamsa, Malavya, and Sasa yogas formed by Mars, Mercury, Jupiter, Venus, and Saturn in Kendra in own/exaltation sign.
Returns Moon-based yoga analysis — Sunaphа, Anaphа, Durudhara, Kemadruma, Gajakesari, and other Chandra yogas.
Muhurat Finder
Find auspicious dates and times (Muhurat) for important life events — marriage, housewarming, business, travel, and more.
Returns auspicious dates for marriage (Vivah Muhurat) within the given date range.
Request Body:
Muhurat Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
start_year | Integer | Required | Start year of the search range |
start_month | Integer | Required | Start month (1-12) |
start_day | Integer | Required | Start day (1-31) |
end_year | Integer | Required | End year of the search range |
end_month | Integer | Required | End month (1-12) |
end_day | Integer | Required | End day (1-31) |
lat | Float | Required | Location latitude |
lon | Float | Required | Location longitude |
tzone | Float | Required | Timezone offset (e.g., 5.5 for IST) |
Returns auspicious dates for housewarming (Grihapravesh) ceremony within the given date range.
Returns auspicious dates for naming ceremony (Namkaran) within the given date range.
Returns auspicious dates for business or shop opening within the given date range.
Returns auspicious dates for travel within the given date range.
Returns auspicious dates for vehicle purchase within the given date range.
Returns auspicious dates for property purchase within the given date range.
Returns auspicious dates for Mundan (first head shaving) ceremony within the given date range.
Returns auspicious dates for Annaprashan (first rice feeding) ceremony within the given date range.
Check if a specific date and time is auspicious for general activities.
Request Body:
Note: This endpoint uses standard birth-data parameters (year, month, day, hour, min, lat, lon, tzone) instead of the date-range parameters used by other muhurat endpoints.
How to Generate a PDF Report
There are two ways to get a Kundli PDF, depending on how much design control you want.
Option A — /v1/pdf/generate: a ready-made, fully-branded PDF in one call
Send birth details plus your own branding — business name, astrologer name, logo, photo, footer banner, colors, contact info — and get back a complete, print-ready Kundli PDF with your branding on it, not ours. Nothing to set up beforehand: every field is sent per request, so there's no separate "save your branding" step and nothing stored on our side between calls.
Available on professional and enterprise plans. PDF rendering is significantly heavier than a JSON endpoint (typically 10–25 seconds per call), so it isn't part of the free/starter tier — each call still counts as a single request against your plan's quota.
Returns the PDF file directly — the response's Content-Type is application/pdf, not JSON.
Request Body:
Example Request (cURL):
Branding fields
| Field | Type | Notes |
|---|---|---|
brandName | string | Your business/brand name — heads the cover page. |
panditName | string | The astrologer who signs the report. Left blank, that line is simply not printed — it never falls back to any name of ours. |
brandPhone, brandEmail, brandWebsite | string | Contact line on the cover. |
brandFooter | string | Short text shown in the report footer. |
logoUrl, profileImageUrl, footerBannerUrl | string (URL) | See "Supplying images" below. |
businessColor, titleColor, nameColor | hex string | e.g. "#7a1e1e". Anything not a valid #rgb/#rrggbb/#rrggbbaa string is ignored. |
socialLinks | object | Any of facebook, instagram, youtube, twitter, linkedin — printed on the closing page. |
youtubeVideo | object | { url, title, description } — an optional featured-video block. |
Supplying images
logoUrl, profileImageUrl and footerBannerUrl each accept either:
- An
https://URL you host yourself (recommended — no size limit from us; our renderer fetches it directly while building the PDF). Plainhttp://is not accepted. - An inline
data:image/...;base64,...URI, for small images (logos, icons) you'd rather send directly — capped at roughly 900KB decoded per image, since up to three of these travel in the same request body.
A URL that resolves to a private, loopback or link-local address (e.g. 127.0.0.1, 192.168.x.x, cloud metadata endpoints) is refused rather than fetched. If an image URL is unreachable or invalid, that one image is silently skipped — a bad logoUrl does not fail the whole report.
Other fields
variant — "detailed" (default) for the full report, or "basic" for the shorter free-tier-style report. lang — same language codes as every other endpoint (en, hi, mr, bn, ta, gu, te, kn).
Option B — build the PDF yourself from JSON
If you want full design control over the layout (not just the branding), you can still fetch the underlying data as JSON and render it however you like — this is how every KundliAPI PDF was generated before /v1/pdf/generate existed, and it's still fully supported.
1. Fetch the data. Call the endpoints you need for the same birth details — e.g. /v1/astro/get_astro_data, /v1/planet/get_all_planet_data, /v1/chart/get_lagna_chart, /v1/chart/get_navamsa_chart, /v1/dasha/get_vimshottary_maha_dasha, /v1/dosha/mangal_dosh_analysis — and combine the JSON responses.
2. Render that JSON into a PDF, using your own code. Two common approaches:
| Approach | How it works | Typical libraries |
|---|---|---|
| Draw the PDF programmatically | Your code places text, tables, and lines at specific coordinates directly onto a blank PDF canvas. | PDFKit (Node.js), ReportLab (Python), iText (Java), QuestPDF (.NET) |
| HTML → PDF conversion | Design the report as a normal HTML/CSS page, inject the API's JSON values into it, then "print" that page to a PDF using a headless browser. | Puppeteer / Playwright (Chromium), wkhtmltopdf, WeasyPrint |
The HTML → PDF route is usually easier to start with — you can design and preview the report visually in a normal browser before exporting it.
3. Drawing the Kundli chart itself. The API only tells you which planet sits in which house as JSON (e.g. { "house": 1, "planet": "Sun" }) — it does not return a chart image. You need to draw the diamond shape (North Indian style) or the fixed 12-box grid (South Indian style) yourself, then place each planet's abbreviation into the correct box based on that house data.
Need More Details?
This documentation covers the most commonly used endpoints. For a complete list of all 203+ endpoints, test them directly from your dashboard or contact our support.