Developer Reference

Vedic Astrology API Documentation

The endpoints of the calculation API: charts and reports, panchang, muhurta, horoscopes, matching, remedies and Lal Kitab.

REST API Bearer Auth JSON Response

Quick Start

Base URL

https://vedajyotish.com/api
  1. Create an account, on the website or with POST /api/auth/register.
  2. Buy the API plan, then create your API key in the developer console (dashboard).
  3. Send the key on every call: Authorization: Bearer YOUR_KEY, with Accept: application/json.
  4. 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.

See the plans

Authentication

Register

POST No token needed
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 No token needed
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 No token needed
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 Token required
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 Token required
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 Token required
GET /api/astrology/chart

The chart you saved last, as Generate returned it; 404 when you have none.

Running Dasha

GET Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 No token needed
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_chart ready to draw, strength (Shadbala), yogas, doshas, timing (the dasha and the transits within the focus), the rule engine's interpretation, and meta (engine, ayanamsa, the clock the birth was read on).
  • A sign or a planet carries sign_number (1 = Aries) and key beside its name, which is in the language asked: reckon with those, not with the name.
  • report_type: advanced adds the divisional charts, KP, Jaimini, the annual chart and more, and needs a token for an account whose plan includes detailed reports: otherwise 403 with data.subscription_required.
  • A part that could not be worked out is named in meta.unavailable; with no ephemeris at all the answer is 503 with ephemeris_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 No token needed
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 No token needed
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 Token required
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 Token required
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 No token needed
GET /api/v1/panchang

Parameters:

  • date: the day, YYYY-MM-DD
  • latitude, longitude: the place, in degrees
  • timezone (optional): the place's zone, such as Asia/Kolkata
  • lang (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 No token needed
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 No token needed
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 No token needed
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 No token needed
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 range YYYY-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 No token needed
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 Token required
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 Token required
GET /api/compatibility/matches

All your saved matches. GET /api/compatibility/history gives them ten to a page.

One Match in Full

POST Token required
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 No token needed
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 Token required
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 Token required
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 Token required
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 Token required
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 Token required
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 No token needed
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.