Developer Reference
Vedic Astrology API Documentation
The endpoints of the calculation API: charts and reports, panchang, muhurta, horoscopes, matching, remedies and Lal Kitab.
Quick Start
Base URL
https://vedajyotish.com/api
- Create an account, on the website or with
POST /api/auth/register. - Buy the API plan, then create your API key in the developer console (dashboard).
- Send the key on every call:
Authorization: Bearer YOUR_KEY, withAccept: application/json. - Each answer is JSON in the envelope below.
The envelope:
{ "success": true, "message": "…", "data": { … } }
{ "success": false, "message": "What went wrong", "errors": { "field": ["…"] } } // 422
{ "success": false, "message": "…", "data": { "subscription_required": true } } // a flag says why
message is written for people; read the flags in data (or at the top level, as noted) to act on an answer.
Access, keys and plans
Every endpoint below carries one of two marks.
- No token needed A calculation from what you send: a birth, a date and place, a sign. The website's own tool pages call these without a token, and so can you, within the limit of 60 requests a minute for each address. Sent with an API key, the call needs an active API plan and is counted against it.
- Token required It reads or writes something of your account, such as the charts you have saved and readings of them. An API key works here only with an active API plan.
So the plan buys what an account holds and the calls you make as yourself, counted by the month (or the year), with the limits shown under Rate limits. A call with an API key and no plan is answered 403 with data.subscription_required: true; past the plan's calls, 429 with data.api_quota_reached: true. Each counted answer carries X-Api-Calls-Limit and X-Api-Calls-Remaining.
Which token. An API key from the developer console, or the token /api/auth/login and /api/auth/register return: both are API tokens and go through the same plan check. A few account endpoints (sign-out among them) are for the website and the mobile apps only and answer an API token 403.
The detailed birth report (report_type: advanced) also needs a plan that includes detailed reports; see Birth Report.
Authentication
Register
POST /api/auth/register
Creates an account and signs it in. The password is at least 8 characters. Answered 201; where the site can send mail, a link to confirm the address is emailed.
Request Body:
{
"name": "John Doe",
"email": "john@example.com",
"password": "secret123",
"password_confirmation": "secret123"
}
Response (201):
{
"success": true,
"message": "User registered successfully",
"data": {
"user": { "id": 42, "name": "John Doe", "email": "john@example.com", ... },
"access_token": "17|aBcDeFgHiJkLmNoPqRsTuVwXyZ",
"token_type": "Bearer"
}
}
Login
POST /api/auth/login
Answers as Register does (200, data.access_token). Wrong details: 401. After many failed attempts on one account, 429 with retry_after (seconds) and a Retry-After header; a blocked account, 403 with data.account_blocked: true.
Request Body:
{
"email": "john@example.com",
"password": "secret123"
}
Forgot Password
POST /api/auth/forgot-password
Emails a link that sets a new password. The link opens this website and is good once, for an hour. The answer is the same whether or not the address has an account. A site that cannot send email answers 503 with reset_unavailable and the support_email to write to.
Request Body:
{ "email": "john@example.com" }
Logout
POST /api/auth/logout
Ends the sign-in that sent it. It is for the website's and the apps' sign-ins: an API token, a key or one from this API's login, is answered 403. To withdraw an API key, delete it in the developer console.
Birth Chart (saved to your account)
A chart made here is kept on your account and read by the endpoints that follow it. A chart id is looked up among your own charts only: someone else's and one that does not exist are the same 404, "Chart not found." Each chart saved counts against the plan's monthly charts, where it has a limit (403 with data.plan_limit_reached past it).
Generate Birth Chart
POST /api/astrology/chart/generate
Request Body:
{
"date": "1990-05-15",
"time": "14:30",
"place": "Mumbai, India",
"latitude": 19.0760,
"longitude": 72.8777,
"timezone": "Asia/Kolkata",
"include_predictions": false
}
Response:
{
"success": true,
"message": "Birth chart generated successfully",
"data": {
"id": 1,
"ascendant": { "sign": "Leo", "degree": 12.4, ... },
"planetary_positions": { "Sun": { "sign": "Taurus", "house": 10, ... }, ... },
"house_positions": [...],
"nakshatras": {...}
}
}
Life predictions are written only when asked for.
Send include_predictions: true and the answer also holds
life_predictions and life_predictions_by
(the AI model, or rule-engine on a site set to rule-based readings).
Where the model was to write them and could not, life_predictions is
null beside ai_unavailable: true or
ai_limit_reached: true; the chart is saved and returned either way.
With no time zone sent the birth is read on its birthplace's own clock.
Your Latest Chart
GET /api/astrology/chart
The chart you saved last, as Generate returned it; 404 when you have none.
Running Dasha
GET /api/astrology/dasha
The Vimshottari Mahadasha and Antardasha running now in your latest chart (current_dasha, current_antardasha, each with its dates). No parameters; 404 without a saved chart. The whole tree is POST /api/v1/astrology/dasha, below.
Transits Over Your Chart
GET /api/astrology/gochar
Where each planet is now (current_sign), its house from the Moon of your latest chart (house_from_moon), whether that house is favourable for it, and what it brings; 404 without a saved chart.
Reading a saved chart
Each of these takes the chart_id of one of your charts.
Complete Chart
POST /api/v1/astrology/chart/complete
Saves a chart, as Generate does, and returns it with what you ask for beside it: include_divisional, include_yogas, include_doshas, include_dasha, include_predictions (each true or false). Takes date, time, place, latitude, longitude and an optional timezone.
Chart Analysis
GET /api/v1/astrology/chart/{id}/analysis
A summary of a saved chart: yoga_summary, dosha_summary, current_dasha, top_yogas, critical_doshas and planetary_strengths — each planet's Shadbala in Rupas against the Rupas it needs.
Divisional Charts
POST /api/v1/astrology/divisional-charts
chart_id and, optionally, divisions: any of 1, 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60 (all of them when left out). Each planet's sign and degree in each division.
Yogas
POST /api/v1/astrology/yogas
chart_id. The yogas the chart forms, each with the rule that formed it and its strength worked out from the forming planets (strength, strength_basis), and a summary.
Doshas
POST /api/v1/astrology/doshas
chart_id. Mangal, Kaal Sarp and the other doshas the texts give: whether each is formed and whether it stands after its cancellations, and a summary.
Vimshottari Dasha Tree
POST /api/v1/astrology/dasha
chart_id, and include_antardasha / include_pratyantardasha for the deeper levels. all_dashas and current_dasha; each period has start_at / end_at on the birth's clock.
Transits on a Date
POST /api/v1/astrology/transits
chart_id and an optional date (YYYY-MM-DD, today when left out). The planets on that date against the chart; aspects are by sign, as Jyotisha has them.
Birth Report
Full Birth Report
POST /api/v1/astrology/report
The report the website's birth-chart page draws, from a birth sent whole; nothing is saved.
Request Body:
{
"name": "Arjun",
"date": "1990-05-15",
"time": "14:30",
"latitude": 19.0760,
"longitude": 72.8777,
"timezone": "Asia/Kolkata", // optional: else the birthplace's own clock
"gender": "male", // optional: male | female (a yoga needs it)
"report_type": "basic", // basic | advanced
"system": "vedic", // vedic | kp | jaimini
"focus": 5, // 1 | 5 | 10: how far ahead it looks
"lang": "hi" // optional: one of the site's languages
}
- Its parts: the basics (Lagna, Moon and Sun signs, birth star),
planetary_positions, the houses,birth_chartready to draw,strength(Shadbala), yogas, doshas,timing(the dasha and the transits within the focus), the rule engine'sinterpretation, andmeta(engine, ayanamsa, the clock the birth was read on). - A sign or a planet carries
sign_number(1 = Aries) andkeybeside its name, which is in the language asked: reckon with those, not with the name. report_type: advancedadds the divisional charts, KP, Jaimini, the annual chart and more, and needs a token for an account whose plan includes detailed reports: otherwise403withdata.subscription_required.- A part that could not be worked out is named in
meta.unavailable; with no ephemeris at all the answer is503withephemeris_unavailable: true.
Horoscope
A day, week and month are those of the site's own place and calendar (a week runs Monday to Sunday). generated_by says who wrote a reading: rule-engine, or AI (model). Where AI readings are switched on and the model cannot be reached, the rule engine's reading is returned with ai_unavailable: true.
A Sign's Horoscope
GET /api/horoscope/{sign}/{period}
Parameters:
sign: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces (any case)period: daily, weekly, monthly, yearly
/api/horoscope/leo/daily
The Moon sign's reading, the same for everyone of that sign. The short lines beside it (love, career, business, health, finance) hold only the ones that were written.
Horoscope by Moon Sign, Optionally Your Own
GET /api/v1/ai/horoscope/daily
Also /weekly, /monthly and /yearly. moon_sign (Aries … Pisces) is required; lang is optional; the yearly reading takes year — last year, this year or the next. Send a token and the chart_id of one of your charts whose Moon is in that sign, and the reading is made personal to it (the day's star counted from the birth star, the dasha being run) and counts against the plan's monthly readings.
Your Horoscope
GET /api/horoscope/daily
Also /api/horoscope/weekly, /monthly and /yearly. A reading from your latest chart (404 without one). Past the plan's monthly readings it is the Moon sign's reading in the same shape, with is_general, plan_limit_reached, limit and resets_at.
A Question of Your Chart
POST /api/horoscope/personalized
A reading of your own birth chart on one question
(question_type: general, career, love, health, finance or family). On a
site set to the AI model it is the model's; it is answered
503 with
ai_unavailable: true when the model cannot be reached, and
429 with
ai_limit_reached: true and
resets_at once the account has had its AI readings for the day:
nothing is returned in the reading's place. On a site set to rule-based readings it is the rule
engine's, and statements lists each sentence with the id of the rule it came from.
Panchang
Get Panchang
GET /api/v1/panchang
Parameters:
date: the day, YYYY-MM-DDlatitude,longitude: the place, in degreestimezone(optional): the place's zone, such as Asia/Kolkatalang(optional): one of the site's languages, for the names
Example:
/api/v1/panchang?date=2026-10-13&latitude=19.0760&longitude=72.8777&timezone=Asia/Kolkata
The day runs from sunrise to the next sunrise at the place. Tithi, nakshatra, yoga and karana are
the ones at that sunrise, each with the time it ends and what follows it.
The answer's timezone entry says which clock its times are on: the zone sent,
else the zone the place is found to be in, else Local Mean Time, labelled as such.
Today's Panchang
GET /api/v1/panchang/today
The same for today — today at the place, not at the server. Takes
latitude, longitude and the optional timezone.
A Month
GET /api/v1/panchang/month
Every day of a month: year, month and the place.
With view=calendar each day is a calendar cell — tithi and nakshatra at
sunrise, sunrise and sunset, and the day's observances — in place of its whole panchang.
The older /api/panchang/… endpoints remain for existing clients; new integrations should use these.
Muhurta (Auspicious Timing)
List Activities
GET /api/v1/muhurta/activities
The activity profiles available for the finder (key + label).
Response:
{
"success": true,
"data": { "activities": [
{ "key": "general", "label": "General" },
{ "key": "marriage", "label": "Marriage (Vivah)" },
{ "key": "griha_pravesh", "label": "Griha Pravesh" },
{ "key": "vehicle_purchase", "label": "Vehicle Purchase" },
{ "key": "property_purchase", "label": "Property Purchase" }
] }
}
Find Auspicious Times
GET /api/v1/muhurta/find
Ranks each day in a range (max 60 days) for the chosen activity and returns the best / avoid time-windows, sorted best-first.
Query parameters:
activity— one of the keys above (required)from,to— date rangeYYYY-MM-DD(required, range ≤ 60 days)latitude,longitude— location (required)timezone— IANA name, e.g.Asia/Kolkata(optional)
Optional personalization (Premium):
Supply the native's birth details to add tara-bala + chandra-bala to the scoring. When these are present the request requires an authenticated Premium account — 401 if unauthenticated, 403 if not premium. Omit them for the generic finder.
natal_date(YYYY-MM-DD),natal_time(HH:MM)natal_latitude,natal_longitude,natal_timezone
Example:
/api/v1/muhurta/find?activity=marriage&from=2026-07-01&to=2026-07-31&latitude=28.6139&longitude=77.2090&timezone=Asia/Kolkata
Response (abridged):
{
"success": true,
"data": {
"activity": "marriage",
"activity_label": "Marriage (Vivah)",
"from": "2026-07-01", "to": "2026-07-31",
"personalized": false,
"natal": null,
"days": [
{
"date": "2026-07-01", "day_of_week": "Wednesday",
"score": 73, "verdict": "Good",
"factors": [
{ "name": "Vara", "value": "Wednesday", "good": true, "note": "Favourable weekday." }
],
"closed": [],
"best_windows": [ { "name": "Labh (Choghadiya)", "start": "05:26", "end": "07:11" } ],
"avoid_windows": [ { "name": "Rahu Kala", "start": "12:24", "end": "14:09" } ]
},
{
"date": "2026-07-20", "day_of_week": "Monday",
"score": 39, "verdict": "Avoid",
"factors": [
{ "name": "Nakshatra", "value": "Hasta", "good": true, "note": "Favourable nakshatra." },
{ "name": "Period", "value": "Guru Asta", "good": false, "note": "Jupiter is set — lost in the Sun's light (Guru asta)." }
],
"closed": [
{ "period": "guru_asta", "phase": "asta", "label": "Guru Asta", "note": "Jupiter is set — lost in the Sun's light (Guru asta)." },
{ "period": "solar_month", "label": "Sun in Cancer", "note": "The Sun is in Cancer — a solar month closed to this." }
],
"best_windows": [],
"avoid_windows": [ { "name": "Rahu Kala", "start": "07:18", "end": "09:01" } ]
}
]
}
}
closed lists the periods of the year in which the activity is not undertaken, whatever the day's own limbs are; a day with any is Avoid and has no best windows. period is one of guru_asta or shukra_asta (Jupiter or Venus unseen, with phase asta, vriddhatva or shishutva), adhika_masa, solar_month, lunar_month, chaturmas or pitru_paksha. Which of them apply depends on the activity: all but the lunar months and Pitru Paksha close a marriage, none closes general.
A day runs from its sunrise to the next, so a window can fall after midnight. One that begins after midnight carries "next_day": true; one whose end is earlier than its start began in the evening and runs past midnight. Each list also comes worded in the language asked, in shown; decide by the English values.
Kundali Matching
Match by Birth Details
POST /api/v1/compatibility/kundali-matching
36-point Gun Milan from the two partners' birth details. Nothing is saved. Each partner is read in the time zone of their own birth place; send male_timezone / female_timezone to set it yourself.
Request Body:
{
"male_name": "Arjun",
"male_date": "1990-05-15",
"male_time": "14:30",
"male_latitude": 19.0760,
"male_longitude": 72.8777,
"female_name": "Meera",
"female_date": "1992-08-20",
"female_time": "10:15",
"female_latitude": 28.6139,
"female_longitude": 77.2090
}
Response:
{
"success": true,
"data": {
"total_score": 28.5,
"max_score": 36,
"percentage": 79.17,
"compatibility_level": "Very Good",
"compatibility_description": "28.5 of 36. A total of 21 to 30 is read as very good.",
"verdict": { "level": "Very Good", "read_as": "very good", "rule": "total", "from": 21, "to": 30 },
"detailed_analysis": {
"varna": { "score": 0, "max_points": 1, ... },
"vashya": { "score": 2, "max_points": 2, ... },
"tara": { "score": 3, "max_points": 3, ... },
"yoni": { "score": 2, "max_points": 4, ... },
"graha_maitri": { "score": 0.5, "max_points": 5, ... },
"gana": { "score": 6, "max_points": 6, ... },
"bhakoot": { "score": 7, "max_points": 7, "dosha": false, "dosha_type": null,
"cancelled": false, "cancellations": [], ... },
"nadi": { "score": 8, "max_points": 8, "dosha": false, "cancelled": false,
"cancellations": [], "is_critical": false, ... }
},
"mangal_dosha": {
"male_has_mangal_dosha": false,
"female_has_mangal_dosha": true,
"male": { "formed": true, "present": false, "severity": null, "stands_from": [],
"cancellations": ["Jupiter aspects Mars", "Mars is the yogakaraka for Leo rising"], "from": { ... } },
"female": { "formed": true, "present": true, "severity": "Medium", "stands_from": ["Lagna", "Moon"],
"cancellations": [], "from": { ... } },
"compatible": false,
"determined": true,
"description": "Mangal Dosha stands in the bride's chart only: Mars is in the 8th from the Lagna and the 2nd from the Moon. ..."
},
"recommendations": [...],
"strengths": [...],
"concerns": ["Mangal Dosha in one chart only"],
"male_name": "Arjun",
"female_name": "Meera"
}
}
How the total is read. compatibility_level is Excellent (31–36), Very Good (21–30), Average (17–20) or Poor (0–16), as Drik Panchang reads it. With a Bhakoot dosha standing the bands are 26–29, 21–25 and 0–20, and with a Nadi dosha standing the level is Poor whatever the total. verdict.rule says which applied: total, bhakoot or nadi.
Doshas. For nadi and bhakoot, dosha says it is formed and cancelled that an exception excuses it, with the reasons in cancellations; the points stay what the table gives. nadi.is_critical is true only for a dosha that stands.
Mangal Dosha is judged for each chart from the Lagna, the Moon and Venus. formed is Mars in a house of the dosha from any of the three; present is a dosha left standing after its cancellations, with severity Low, Medium or High by how many of the three it stands from. compatible is true when it stands in both charts or in neither; determined is false when a chart has no Mars.
The longevity block this endpoint used to return has been removed: it was not a classical measure.
Match Two Saved Charts
POST /api/compatibility/analyze
Matches two charts saved on your own account and keeps the result in your history. You say which chart is the groom's and which the bride's. Running the same pair again updates the saved result.
Request Body:
{
"male_chart_id": 12,
"female_chart_id": 15
}
Response:
{
"success": true,
"data": {
"id": 7,
"male_chart_id": 12,
"female_chart_id": 15,
"male_name": "Arjun",
"female_name": "Meera",
"total_score": "28.5",
"guna_scores": { "varna": 0, "vashya": 2, "tara": 3, ... },
"is_manglik_male": true,
"is_manglik_female": true,
"compatibility_level": "good"
}
}
A saved match keeps its level in four lower-case words — excellent, good (Very Good), average, poor — where the birth-details match above answers in the verdict's own words.
Your own charts only. Both ids must be charts created on your account with
/api/astrology/chart/generate. Any other id is rejected with 422.
To match someone whose chart you have not saved, use their birth details with the endpoint above.
Saved Matches
GET /api/compatibility/matches
All your saved matches. GET /api/compatibility/history gives them ten to a page.
One Match in Full
POST /api/compatibility/detailed
Takes a compatibility_id and returns that match with the full koota-by-koota analysis; someone else's match and one that does not exist are the same 404.
Remedies
Generate Remedies
POST /api/remedies/generate
The remedies of a planet: mantra, gemstone, puja, charity. Send planet (one of the nine grahas), or issue (career, health, relationship, finance, education, family, legal, spiritual), or both. To read a birth, send it whole: date (YYYY-MM-DD), time (HH:MM), latitude, longitude and, optionally, timezone (IANA name; else the birthplace's). With no planet, no issue and no chart, the request is refused (422); a birth sent, or a saved chart, is answered with that chart's weakest planet.
The response says what it was answered from in basis. general: the remedies the tradition assigns to the planet, the same for everyone, where an issue alone is answered with its natural significator. chart: a birth was sent, or the caller sent a token and has a saved chart (a birth sent is the one read), so an issue is answered with the lord of its house in that chart, chart reports what stands for and against the planet there, and gemstones is empty when the stone is not one to wear for that ascendant.
Remedies From Your Chart
GET /api/remedies
A remedy for each planet that is weak in your latest chart, the weakest first, and an empty list when none is. A planet is weak when its Shadbala, worked out from the chart's birth time and place, is short of the Rupas it needs: strength gives both (rupas, required, ratio). Each remedy names why the planet is weak (reasons, its Shadbala first) and whether it is to be strengthened or pacified (need). Where the Shadbala cannot be worked out, strength_known is false and the list is empty. recommended_gemstones is empty for a planet whose stone is not worn for that ascendant, and gemstone_note says why. Asking again returns the same rows. Needs a saved chart (400 without one).
Gemstones
GET /api/remedies/gemstones
The stones of your chart: primary is the life stone of the ascendant lord, secondary and alternative the stones of the 5th and 9th lords, and avoid the stones of the chart's functional malefics. Each stone says whether wearing it is called for (indicated, true when its planet is short of the Rupas it needs by Shadbala; strength gives the figures) and why.
Remedy for an Area of Life
GET /api/remedies/by-problem
problem_type: career, health, relationship, finance, education or family. Read from your chart: the lord of the house the area belongs to and its significator (planets), with a remedy for whichever of them is weak. remedies is empty when neither is.
Today
GET /api/remedies/daily
The planet the weekday belongs to and its own practice (observance, the same for everyone). remedies is yours: that planet's remedy when it is weak in your chart, and empty otherwise or when no chart is saved (personal: false). Optional timezone (IANA name) decides which day it is.
Remedy History
GET /api/remedies/history
The remedies recommended to you, active and completed. POST /api/remedies/mark-completed with a remedy_id marks one done.
Lal Kitab
Lal Kitab Chart
POST /api/v1/lal-kitab/chart
From date (YYYY-MM-DD), time (HH:MM), latitude, longitude, and optional timezone and lang. Each planet's house counted from the ascendant, whether it is benefic or malefic there (by its house alone) and asleep (no planet in the 7th from it), the nine debts with whether each is indicated or present, and a remedy for each planet that is malefic where it stands. The closed lists also come worded in the language asked, in shown.
Status Codes
| Code | Meaning | When, and the flag to read |
|---|---|---|
| 200 | OK | The request succeeded. |
| 201 | Created | An account was registered. |
| 400 | Bad Request | An endpoint that reads your chart, with no chart saved. |
| 401 | Unauthorized | The token is missing, wrong or expired, or the sign-in details are wrong. |
| 403 | Forbidden | An API key with no active API plan (subscription_required); a detailed report or personalised muhurta without the plan for it; a monthly chart or reading limit reached (plan_limit_reached); an endpoint not open to API keys; a blocked account (account_blocked). |
| 404 | Not Found | No such record, or one that is not yours — the two are answered alike. |
| 409 | Conflict | The record is not in a state that allows the request (a session already ended, for instance). |
| 422 | Validation Error | The input is not valid; errors names each field. |
| 429 | Too Many Requests | Over 60 requests a minute; the API plan's calls used up (api_quota_reached, with per and resets_at); the day's AI readings used (ai_limit_reached); too many failed sign-ins (retry_after). |
| 500 | Server Error | Something failed on our side; the message says what, and the details are logged, not returned. |
| 503 | Unavailable | A service the answer needs is missing: no ephemeris engine (ephemeris_unavailable), the AI model unreachable (ai_unavailable), mail not set up (reset_unavailable), or the site's licence closed (licence_closed, on every call). |
Rate Limits
Every caller
60 requests a minute
Counted for each account, and for a call with no token, for each address. Past it: 429 for the rest of the minute.
With an API key
200 calls a month
API Developer, bought by the month; by the year, no limit in the year
Counted by the calendar month, or for a plan bought by the year over its year. Each answer carries X-Api-Calls-Limit and X-Api-Calls-Remaining; past them, 429 with api_quota_reached: true, per (month or year) and resets_at.