SoulOSSoulOS API
Getting Started
Overview Authentication Quick Start
Endpoint
POST /v1/chart Parameters
Response Fields
Basic Info Planets Houses Dasha Yogas Nakshatra
Reference
POST /v1/compatibility POST /v1/panchang POST /v1/synastry POST /v1/divisional POST /v1/dosha POST /v1/ankashastra Errors Rate Limits Support
Introduction

SoulOS Kundli API

The most accurate Vedic astrology calculation engine available as an API. Built on Swiss Ephemeris 2.10, strictly following Parashar's Brihat Parashar Hora Shastra — Whole Sign houses, Lahiri ayanamsa, Vimshottari Dasha.

Base URL
kundli.soulmapbysahil.in
Protocol
HTTPS · REST · JSON
Ayanamsa
Lahiri (Chitra Paksha)
House System
Whole Sign (Parashar)
Dasha System
Vimshottari (120-year)
Ephemeris
Swiss Ephemeris 2.10.03
Authentication

API Keys

Every request must carry your API key. Pass it in the Authorization header (preferred) or in the JSON body.

Authorization Header 
Authorization: Bearer soul_live_<your-key>

Or include api_key directly in the JSON body:

Body Auth 
{
  "api_key": "soul_live_<your-key>",
  "dob":     "1987-07-08",
  // ... other fields
}
Register free at kundli.soulmapbysahil.in/dev/register — instant key, no approval needed. Free Plan gives you 100 calls/day to start.
Quick Start

Your First Request

One POST, one response. A complete Vedic birth chart in milliseconds.

cURL

terminal 
curl -X POST https://kundli.soulmapbysahil.in/v1/chart \
     -H "Authorization: Bearer soul_live_<YOUR_KEY>" \
     -H "Content-Type: application/json" \
     -d '{
       "dob": "1987-07-08",
       "tob": "05:19:00",
       "lat": "32:47",
       "lon": "74:44",
       "tz":  5.5
     }'

Python

chart.py 
import requests

payload = {
    "dob": "1987-07-08",
    "tob": "05:19:00",
    "lat": "32:47",
    "lon": "74:44",
    "tz":  5.5
}
headers = {"Authorization": "Bearer soul_live_<YOUR_KEY>"}

r = requests.post(
    "https://kundli.soulmapbysahil.in/v1/chart",
    json=payload,
    headers=headers
)
data = r.json()["data"]
print(data["basic"]["lagna"])   # → "Gemini"

PHP

chart.php 
$response = file_get_contents(
    'https://kundli.soulmapbysahil.in/v1/chart',
    false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n"
                  . "Authorization: Bearer soul_live_<YOUR_KEY>",
        'content' => json_encode([
            'dob' => '1987-07-08',  'tob' => '05:19:00',
            'lat' => '32:47',     'lon' => '74:44',
            'tz'  => 5.5
        ])
    ]])
);
$chart = json_decode($response, true)['data'];
echo $chart['basic']['lagna'];  // Gemini

JavaScript

chart.js 
const res = await fetch("https://kundli.soulmapbysahil.in/v1/chart", {
    method:  "POST",
    headers: {
        "Content-Type":  "application/json",
        "Authorization": "Bearer soul_live_<YOUR_KEY>"
    },
    body: JSON.stringify({
        dob: "1987-07-08",  tob: "05:19:00",
        lat: "32:47",     lon: "74:44",  tz: 5.5
    })
});
const { data } = await res.json();
console.log(data.basic.lagna);   // "Gemini"
Endpoint

POST /v1/chart

Calculates a complete Vedic birth chart. Returns planets in all 12 signs, Whole Sign houses, Vimshottari Dasha timeline, Yogas, Nakshatra details, and Avkahada Chakra.

POST https://kundli.soulmapbysahil.in/v1/chart
Parameters

Request Body

FieldTypeStatusDescription
dob string Required Date of birth in YYYY-MM-DD format.
Example: 1987-07-08
tob string Required Time of birth in HH:MM or HH:MM:SS format (24-hour).
Example: 05:19:00
lat string Required Latitude — decimal degrees or DMS notation.
Decimal: 32.7833  ·  DMS: 32:47
lon string Required Longitude — decimal degrees or DMS notation.
Decimal: 74.7333  ·  DMS: 74:44
tz float Optional UTC offset in hours. Defaults to 5.5 (IST).
Example: 5.5 for IST, -5 for EST
name string Optional Person's name — echoed back in the response.
dasha_depth integer Optional Depth of the Vimshottari Dasha tree. Default 5 (all levels).
1 = Mahadasha only  ·  2 = +Antardasha  ·  3 = +Pratyantar  ·  4 = +Sookshma  ·  5 = +Prana (full ~66K entries)
chart boolean Optional Include a rendered North Indian birth chart SVG in the response. Default false.
When true — data.chart_svg contains the full inline SVG string. meta.chart_included confirms whether it was generated. Omit or pass false to keep the response lean. For divisional chart SVGs (D9, D10, etc.) use POST /v1/divisional with the same chart: true parameter.
include array Optional Array of optional response expansions.
"insights" — adds data.insights: a complete natal interpretation built from Dr. Sahil Kohli's Parashar knowledge base. Includes a synthesis (flowing combined reading), per-planet interpretations (in sign + in house), house lord placements, Moon nakshatra, conjunctions, and current Mahadasha meaning.
Example: "include": ["insights"]
Combine with name to personalise the text with the person's name.
lang string Optional Language code for data.insights interpretation text. Default en (English).
Supported: en English  ·  hi Hindi  ·  hg Hinglish  ·  ne Nepali  ·  ur Urdu  ·  ta Tamil  ·  te Telugu  ·  ml Malayalam  ·  pa Punjabi
Falls back to English if a translation is incomplete. Only applies when "insights" is included in include.
api_key string Optional API key if not passing via Authorization header.
Response

Complete Response

Below is the actual verified response for 08 Jul 1987 · 05:19 IST · Jammu, J&K — cross-verified against AstroSage.

JSON Basic Info

response.json → data.basic 
"basic": {
  "lagna":          "Gemini",         // Ascendant sign
  "lagna_lord":     "Mercury",
  "rashi":          "Scorpio",        // Moon sign
  "rashi_lord":     "Mars",
  "nakshatra":      "Anuradha",       // Moon nakshatra
  "nakshatra_pada": 2,
  "nakshatra_lord": "Saturn",
  "dob":            "1987-07-08",
  "tob":            "05:19:00",
  "latitude":       32.783,
  "longitude":      74.733,
  "timezone":       5.5,
  "ayanamsa":       "Lahiri"
}
Planets

Planets

All 9 Vedic grahas — Sun through Ketu — including outer planets for reference. Each planet includes sign, degree within sign, absolute ecliptic longitude, retrograde flag, and combustion flag.

response.json → data.planets 
"planets": {

  "sun": {
    "sign":        "Gemini",
    "sign_num":    3,
    "degree":      21.6423,      // degrees within sign
    "longitude":   81.6423,      // absolute ecliptic longitude
    "retrograde":  false
  },

  "moon": {
    "sign":        "Scorpio",
    "sign_num":    8,
    "degree":      7.3559,
    "longitude":   217.3559,
    "retrograde":  false,
    "combust":     false
  },

  "mercury": {
    "sign":        "Gemini",
    "sign_num":    3,
    "degree":      15.8020,
    "longitude":   75.8020,
    "retrograde":  true,          // ← Retrograde
    "combust":     true           // ← Combust
  },

  "venus": {
    "sign":        "Gemini",
    "sign_num":    3,
    "degree":      8.9666,
    "longitude":   68.9666,
    "retrograde":  false,
    "combust":     false
  },

  "mars": {
    "sign":        "Cancer",
    "sign_num":    4,
    "degree":      7.1437,
    "longitude":   97.1437,
    "retrograde":  false,
    "combust":     true           // ← Combust
  },

  "jupiter": {
    "sign":        "Aries",
    "sign_num":    1,
    "degree":      3.1922,
    "longitude":   3.1922,
    "retrograde":  false
  },

  "saturn": {
    "sign":        "Scorpio",
    "sign_num":    8,
    "degree":      22.2013,
    "longitude":   232.2013,
    "retrograde":  true           // ← Retrograde
  },

  "rahu": {
    "sign":        "Pisces",
    "sign_num":    12,
    "degree":      12.8579,
    "longitude":   342.8579,
    "retrograde":  true           // always retrograde
  },

  "ketu": {
    "sign":        "Virgo",
    "sign_num":    6,
    "degree":      12.8579,
    "longitude":   162.8579,
    "retrograde":  true           // always retrograde (180° from Rahu)
  }

}
Houses

Houses

Whole Sign system per Parashar BPHS. Each house occupies exactly one sign. House 1 starts at Lagna sign degree 0.

response.json → data.houses 
"houses": {
  "1":  { "sign": "Gemini",      "sign_num": 3,  "longitude": 60  },  // Tanu — Self
  "2":  { "sign": "Cancer",      "sign_num": 4,  "longitude": 90  },  // Dhana — Wealth
  "3":  { "sign": "Leo",         "sign_num": 5,  "longitude": 120 },  // Sahaja — Siblings
  "4":  { "sign": "Virgo",        "sign_num": 6,  "longitude": 150 },  // Sukha — Home
  "5":  { "sign": "Libra",        "sign_num": 7,  "longitude": 180 },  // Putra — Children / Intelligence
  "6":  { "sign": "Scorpio",      "sign_num": 8,  "longitude": 210 },  // Ari — Enemies / Disease
  "7":  { "sign": "Sagittarius", "sign_num": 9,  "longitude": 240 },  // Yuvati — Partnership
  "8":  { "sign": "Capricorn",    "sign_num": 10, "longitude": 270 },  // Randhra — Longevity
  "9":  { "sign": "Aquarius",     "sign_num": 11, "longitude": 300 },  // Dharma — Fortune
  "10": { "sign": "Pisces",       "sign_num": 12, "longitude": 330 },  // Karma — Career
  "11": { "sign": "Aries",        "sign_num": 1,  "longitude": 0   },  // Labha — Gains
  "12": { "sign": "Taurus",       "sign_num": 2,  "longitude": 30  }   // Vyaya — Liberation
}
Dasha

Vimshottari Dasha — All 5 Levels

The only Vedic astrology API that returns all 5 levels of Vimshottari Dasha pre-calculated with exact dates. No need to compute sub-periods yourself. Control response size with dasha_depth.

5 levels, all pre-calculated. Most APIs stop at Antardasha (level 2). We give you Mahadasha → Antardasha → Pratyantar → Sookshma → Prana with exact start/end dates at every level. dasha_depth=5 = default. Use dasha_depth=2 if you only need MD+AD.

JSON Top-level structure

response.json → data.dasha 
"dasha": {
  "system":  "Vimshottari",
  "depth":   5,                       // levels calculated in timeline

  "balance_at_birth": {
    "planet":          "Saturn",       // nakshatra lord at birth
    "years_remaining": 2.41,          // years of Saturn MD remaining at DOB
    "ends":            "1989-10-22"    // exact date first MD period ends
  },

  "current": {                         // always 5 levels regardless of depth param
    "mahadasha":  { "planet": "Venus",   "start": "2024-10-22", "end": "2044-10-22" },
    "antardasha": { "planet": "Venus",   "start": "2024-10-22", "end": "2028-02-21" },
    "pratyantar": { "planet": "Saturn",  "start": "2026-01-14", "end": "2026-08-30" },
    "sookshma":   { "planet": "Rahu",    "start": "2026-04-04", "end": "2026-05-22" },
    "prana":      { "planet": "Mercury", "start": "2026-04-28", "end": "2026-05-03" }
  },

  "timeline": [                        // 9 Mahadashas, each nested to dasha_depth
    {
      "planet": "Saturn", "years": 2.41, "start": "1987-07-08", "end": "1989-10-22",
      "antardasha": [                  // 9 Antardashas
        {
          "planet": "Saturn", "years": 0.3823, "start": "1987-07-08", "end": "1987-11-19",
          "pratyantar": [              // 9 Pratyantars
            {
              "planet": "Saturn", "years": 0.0607, "start": "1987-07-08", "end": "1987-08-30",
              "sookshma": [            // 9 Sooksmas
                {
                  "planet": "Saturn", "years": 0.009643, "start": "1987-07-08", "end": "1987-07-12",
                  "prana": [          // 9 Pranas — hours to days
                    { "planet": "Saturn",  "start": "1987-07-08", "end": "1987-07-09" },
                    { "planet": "Mercury", "start": "1987-07-09", "end": "1987-07-09" }
                    // ... 7 more
                  ]
                }
                // ... 8 more sooksmas
              ]
            }
            // ... 8 more pratyantars
          ]
        }
        // ... 8 more antardashas
      ]
    }
    // ... 8 more mahadashas
  ]
}

Depth reference

dasha_depthLevels returnedTotal entriesUse case
1Mahadasha9Quick lookup, dashboards
2MD + Antardasha81Most apps — years-level planning
3+ Pratyantar729Month-level precision
4+ Sookshma6,561Week-level precision
5+ Prana (default)~66,430Day-level precision, full pre-calculation

The current block always returns all 5 levels regardless of dasha_depth.

Yogas

Yogas

40 Parashari Yogas checked per Brihat Parashar Hora Shastra across 7 categories. Only yogas present in the chart are returned. If no yoga is present, the array is empty.

Category Yogas
Pancha Mahapurusha Hamsa, Malavya, Ruchaka, Sasa, Bhadra
Raja Kendra-Trikona, Dharma-Karma Adhipati, Neecha Bhanga Raja, Parijata
Dhana Dhana, Lakshmi, Akhand Samrajya
Special Gajakesari, Budhaditya, Chandra-Mangal, Amala, Vasumati, Chatussagara, Parvata, Kahala, Chamara, Shankha, Saraswati, Kalanidhi, Kusuma, Mahabhagya, Pushkala, Musala
Chandra Sunapha, Anapha, Durudhura, Kemdrum, Shakata, Adhi
Surya Vesi, Vosi, Ubhayachari
Viparita Raja Harsha, Sarala, Vimala
response.json → data.yogas 
"yogas": [
  {
    "name":              "Budhaditya Yoga",
    "category":         "Special",
    "nature":           "benefic",          // "benefic" or "challenging"
    "present":          true,           // always true — absent yogas are not returned
    "description":      "Sun and Mercury in the same sign. Sharp intellect, eloquence, and analytical precision.",
    "planets_involved": ["Sun", "Mercury"],
    "house_positions":  [1]             // houses where planets forming yoga sit
  }
  // only actually present yogas appear here — empty array [] if none
]
Nakshatra

Nakshatra & Avkahada

Nakshatra data for Moon and Sun, plus the full Avkahada Chakra (Varna, Gana, Nadi, Yoni, Vasya).

response.json → data.nakshatras + data.avkahada 
"nakshatras": {
  "moon": {
    "name":  "Anuradha",
    "lord":  "Saturn",
    "pada":  2,
    "index": 17
  },
  "sun": {
    "name":  "Ardra",
    "lord":  "Rahu",
    "pada":  4,
    "index": 6
  }
},

"avkahada": {
  "varna":  "Vaishya",      // social classification
  "gana":   "Manushya",     // nature: Deva / Manushya / Rakshasa
  "nadi":   "Madhya",       // Adi / Madhya / Antya
  "yoni":   "Mriga",        // animal symbol
  "vasya":  "Manav"         // compatibility group
}
Endpoint

POST /v1/compatibility

Ashtakoot (8-guna) Kundali Milan compatibility score. Returns a 36-point score with all 8 gunas broken down, doshas identified, and an overall verdict.

Supports two modes:

  • Mode A — Pass boy_nakshatra, boy_rashi, girl_nakshatra, girl_rashi directly. Fast — no ephemeris call needed.
  • Mode B — Pass full birth details boy{} and girl{} (dob, tob, lat, lon, tz). Calculates Nakshatra and Rashi via Swiss Ephemeris, then runs Ashtakoot.
POST https://kundli.soulmapbysahil.in/v1/compatibility

JSON Mode A — Direct Nakshatra/Rashi

{
  "api_key":          "your_api_key",
  "boy_nakshatra":    "Rohini",
  "boy_rashi":        "Taurus",
  "girl_nakshatra":   "Ashwini",
  "girl_rashi":       "Aries"
}

JSON Mode B — Full Birth Details

{
  "api_key": "your_api_key",
  "boy":  {
    "dob": "1994-03-15", "tob": "10:30",
    "lat": 28.6139,    "lon": 77.2090,  "tz": 5.5
  },
  "girl": {
    "dob": "1997-11-22", "tob": "14:15",
    "lat": 19.0760,    "lon": 72.8777,  "tz": 5.5
  }
}

JSON Response

{
  "status":  "success",
  "data": {
    "compatibility": {
      "total":   24.5,
      "max":     36,
      "percent": 68,
      "verdict": "Good",
      "gunas": [
        { "name": "Varna",        "max": 1,  "score": 1,   "detail": "Kshatriya · Vaishya" },
        { "name": "Vashya",       "max": 2,  "score": 2,   "detail": "Chatushpad · Chatushpad" },
        { "name": "Tara",         "max": 3,  "score": 1.5, "detail": "Sampat (Girl→Boy) · Vipat (Boy→Girl)" },
        { "name": "Yoni",         "max": 4,  "score": 3,   "detail": "Snake (Boy) · Deer (Girl)" },
        { "name": "Graha Maitri", "max": 5,  "score": 4,   "detail": "Venus→Moon: Friend · Moon→Venus: Neutral" },
        { "name": "Gana",         "max": 6,  "score": 6,   "detail": "Manav (Boy) · Manav (Girl)" },
        { "name": "Bhakoot",      "max": 7,  "score": 7,   "detail": "Taurus (Boy) · Aries (Girl)" },
        { "name": "Nadi",         "max": 8,  "score": 0,   "detail": "Aadi (Boy) · Aadi (Girl) — Nadi Dosha" }
      ],
      "doshas": [
        { "type": "Nadi Dosha", "severity": "High", "description": "Same Nadi..." }
      ]
    },
    "input": {
      "boy":  { "nakshatra": "Rohini",  "rashi": "Taurus" },
      "girl": { "nakshatra": "Ashwini", "rashi": "Aries"  }
    }
  }
}

Gunas Reference

Guna Max Measures
Varna 1 Spiritual compatibility (Brahmin > Kshatriya > Vaishya > Shudra based on Rashi)
Vashya 2 Control and dominance between the two (Chatushpad, Manav, Keeta, Jaldchar)
Tara 3 Birth star harmony — auspiciousness of nakshatra positions
Yoni 4 Sexual and intimate compatibility based on nakshatra animal symbols
Graha Maitri 5 Natural friendship between the lords of the Moon signs
Gana 6 Temperament — Deva (divine), Manav (human), Rakshasa (demonical)
Bhakoot 7 Emotional and financial compatibility based on relative Moon signs
Nadi 8 Health and genetic compatibility — most critical (Dosha if same Nadi)
Endpoint

POST /v1/panchang

Daily Panchang (Hindu almanac) for any date, time, and location. Returns all 5 elements — Vara, Tithi, Nakshatra, Yoga, Karana — calculated with Lahiri Ayanamsa via Swiss Ephemeris. Each element includes degree progress, degree remaining, and quality/nature rating.

Try Live Panchang + Transit Chart →

POST https://kundli.soulmapbysahil.in/v1/panchang

JSON Request Body

{
  "api_key": "your_api_key",
  "date":    "2026-05-04",   // required, YYYY-MM-DD
  "time":    "06:00",       // optional, HH:MM, defaults to "00:00"
  "lat":     28.6139,       // required
  "lon":     77.2090,       // required
  "tz":      5.5            // optional, UTC offset, defaults to 5.5
}

JSON Response

{
  "status": "success",
  "data": {
    "date":  "2026-05-04",
    "time":  "06:00",
    "vara": {
      "day":   "Monday",
      "name":  "Somavara",
      "lord":  "Moon"
    },
    "tithi": {
      "number":        7,
      "name":          "Saptami",
      "paksha":        "Shukla",
      "display":       "Shukla 7",
      "nature":        "Bhadra",
      "deg_elapsed":   8.4271,
      "deg_remaining": 3.5729
    },
    "nakshatra": {
      "index":         4,
      "name":          "Rohini",
      "lord":          "Moon",
      "pada":          2,
      "deg_elapsed":   5.1028,
      "deg_remaining": 8.2305
    },
    "yoga": {
      "number":        14,
      "name":          "Harshana",
      "quality":       "Good",
      "deg_elapsed":   4.2109,
      "deg_remaining": 9.1224
    },
    "karana": {
      "number":        14,
      "name":          "Balava",
      "quality":       "Good",
      "deg_elapsed":   2.4271,
      "deg_remaining": 3.5729
    },
    "paksha": "Shukla Paksha (Waxing)",
    "sun":    { "longitude": 19.4122,  "sign": "Aries"  },
    "moon":   { "longitude": 103.5141, "sign": "Cancer" },
    "festivals": [
      {
        "key":         "hanuman_jayanti",
        "name":        "Hanuman Jayanti",
        "name_hi":     "हनुमान जयंती",
        "description": "Birthday of Lord Hanuman — Chaitra Purnima.",
        "importance":  1,
        "region":      "all",
        "type":        "tithi",
        "fast":        true,
        "fast_type":   "phalahar",  // nirjala | phalahar | saatvik | moonrise | vigil | null
        "observance":  "sunrise"    // sunrise | noon | pradosh | nishita | moonrise | sunset | all_day
      }
    ]
  },
  "meta": { "powered_by": "SoulOS Kundli API — soulmapbysahil.in", "by": "Dr. Sahil Kohli | Kohli Media LLP", "engine": "SoulOS Ephemeris v1.0", "ayanamsa": "Lahiri", "response_time_ms": 42 }
}

Panchang Elements Reference

Element Count Basis
Vara 7 Weekday (Sun–Sat). Each day ruled by a planet — Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn.
Tithi 30 Lunar day. Moon-Sun angle ÷ 12°. 15 Shukla (waxing) + 15 Krishna (waning).
Nakshatra 27 Moon's nakshatra. Moon longitude ÷ 13.33°. Determines the day's star quality.
Yoga 27 (Sun + Moon longitude) ÷ 13.33°. Each yoga has an auspiciousness rating.
Karana 11 Half-tithi. 7 movable karanas cycle 8 times + 4 fixed karanas. 6° per karana.

Festivals Array — Field Reference

Each object in the festivals array contains the following fields. Array is sorted by importance ascending (most important first). Empty array if no festival today.

Field Type Description
key string Unique identifier for the festival (e.g. "diwali", "maha_shivaratri").
name string English name of the festival.
name_hi string Hindi name (Unicode). May be empty for minor observances.
description string Short description — what is observed and why.
importance int (1–3) 1 = major national festival, 2 = significant regional, 3 = minor / monthly.
region string "all" or a regional identifier (e.g. "north", "south", "maharashtra", "gujarat").
type string Basis for date calculation: tithi | nakshatra | sankranti | combined.
fast bool Whether a fast (vrat) is traditionally observed on this day.
fast_type string|null Type of fast: nirjala (waterless), phalahar (fruits only), saatvik (no grains), moonrise (break at moonrise), vigil (all-night fast), or null if not a fasting day.
observance string When the primary ritual or puja is performed: sunrise | noon | pradosh | nishita | moonrise | sunset | all_day.
Endpoint

POST /v1/synastry

Parashari Graha-Sthiti (Planetary Overlay) — places Person 1's planets into Person 2's houses and vice versa. Returns both overlays with interpretation texts, a theme summary, and a Mahadasha-level timing narrative for each person.

POST https://kundli.soulmapbysahil.in/v1/synastry

Request Parameters

FieldTypeRequiredDescription
api_keystringYesYour API key
p1objectYesPerson 1 birth details (see sub-fields below)
p2objectYesPerson 2 birth details (same structure as p1)
p1.dobstringYesDate of birth — YYYY-MM-DD
p1.tobstringYesTime of birth — HH:MM (24h)
p1.latfloatYesLatitude of birth place (decimal degrees)
p1.lonfloatYesLongitude of birth place (decimal degrees)
p1.tzfloatNoUTC offset (default 5.5 for IST)
p1.namestringNoDisplay name used in interpretation texts
interpretboolNoInclude interpretations, themes, summary, dasha narrative (default true). Pass false for raw overlay data only.

Request Example

POST /v1/synastry 
{
  "api_key":   "your_api_key",
  "interpret": true,
  "p1": {
    "dob":  "1990-06-15",
    "tob":  "08:30",
    "lat":  28.6139,
    "lon":  77.2090,
    "tz":   5.5,
    "name": "Arjun"
  },
  "p2": {
    "dob":  "1993-02-20",
    "tob":  "14:15",
    "lat":  19.0760,
    "lon":  72.8777,
    "tz":   5.5,
    "name": "Priya"
  }
}

Response Structure

200 OK — Synastry Response 
{
  "status": "success",
  "data": {
    "p1":        /* chart summary: lagna, 9 planets, current_dasha, nakshatra, rashi */
    "p2":        /* chart summary (same structure) */
    "p1_on_p2": /* array — P1's planets in P2's houses */ [
      {
        "planet":     "sun",
        "sign":       "Gemini",
        "sign_num":   3,
        "degree":     24.53,
        "house":      5,   // P1's Sun falls in P2's 5th house
        "retrograde": false,
        "combust":    false,
        "text":       "Arjun's Sun in Priya's 5th house...",
        "theme":      "emotional_bond",
        "intensity":  "high"
      }
      /* ... 8 more planets */
    ],
    "p2_on_p1": /* same structure — P2's planets in P1's houses */
    "themes": {              // when interpret:true
      "emotional_bond": {
        "strength":   "strong",   // strong | present | subtle
        "count":      4,
        "placements": [ /* planet, house, intensity, direction */ ]
      }
      /* themes: emotional_bond | karmic_ties | growth_friction | long_term | identity | communication */
    },
    "summary": "Arjun and Priya share a deeply karmic connection...",
    "dasha_synastry": [     // timing narrative for each person's current Mahadasha
      {
        "person":            "p1",
        "mahadasha_planet":  "saturn",
        "mahadasha_ends":    "2031-03-14",
        "antardasha_planet": "mercury",
        "antardasha_ends":   "2027-09-01",
        "house_in_partner":  7,   // P1's Saturn in P2's 7th house
        "house_in_self":     10,  // P1's Saturn in P1's own 10th house
        "narrative":         "Arjun is in their Saturn Mahadasha — a long, karmic period...",
        "natal_context":     "Arjun's Saturn in their own 10th house: the career is being tested...",
        "antardasha_focus":  "Right now the Mercury Antardasha is focusing that energy into Priya's 7th house..."
      }
      /* ... block for p2 */
    ]
  },
  "meta": {
    "response_time_ms": 412,
    "interpreted":      true,
    "ayanamsa":         "Lahiri Ayanamsa",
    "engine":           "SoulOS Ephemeris v1.0",
    "method":           "Parashari Graha-Sthiti (Planetary Overlay)"
  }
}

Themes Reference

ThemeWhat It Measures
emotional_bond Emotional depth and intimate resonance between the two charts
karmic_ties Past-life patterns, soul-level connections, fated quality
growth_friction Challenge and growth — planets that push, stretch, and activate
long_term Structural longevity — Saturn, Jupiter placements that build over time
identity Influence on each other's sense of self (1st house, Sun, Lagna)
communication Mental connection, words, ideas, and shared understanding

Notes

  • All planetary positions use Lahiri Ayanamsa (sidereal, Parashari system)
  • House formula: ((planet_sign_A − lagna_sign_B + 12) % 12) + 1
  • Pass "interpret": false to skip texts, themes, summary, and dasha_synastry — returns raw overlay only (faster)
  • dasha_synastry text uses real names — pass name in p1/p2 for personalised output
  • You can pass the full response to an AI API for deeper narrative generation — the structured data is designed for this
Endpoint

POST /v1/divisional

Shodashavarga — compute any of the 16 Parashari divisional charts (D1 through D60) for a given birth. D9 and D10 are available on all plans. D12 through D60 require a Pro or Enterprise key.

POST https://kundli.soulmapbysahil.in/v1/divisional

Request Parameters

FieldTypeRequiredDescription
api_keystringRequiredYour API key
dobstringRequiredDate of birth — YYYY-MM-DD
tobstringRequiredTime of birth — HH:MM (24-hour)
latfloatRequiredLatitude of birth place (decimal degrees)
lonfloatRequiredLongitude of birth place (decimal degrees)
tzfloatOptionalUTC offset (default 5.5 for IST)
chartstring | arrayRequiredWhich divisional chart(s) to compute. Single: "D9". Multiple: ["D9","D10"]. Accepts with or without the D prefix ("9" and "D9" both work). See chart list below.

Available Charts

CodeNameDomainPlan
D1RashiMain natal chart (physical life, lagna)All
D2HoraWealth & financial potentialPro
D3DrekkanaSiblings, couragePro
D4ChaturthamshaProperty, fortune, fixed assetsPro
D7SaptamshaChildren, progenyPro
D9NavamshaMarriage, inner dharma, soul purposeAll
D10DashamshaCareer, profession, public lifeAll
D12DwadashamshaParents, ancestral karmaPro
D16ShodashamshaVehicles, comforts, conveyancesPro
D20VimsamshaSpiritual practice, worshipPro
D24ChaturvimsamshaEducation, learning, skillsPro
D27SaptavimsamshaStrength, vitality (Nakshatramsha)Pro
D30TrimsamshaMisfortune, evil, healthPro
D40KhavedamshaAuspicious/inauspicious effectsPro
D45AkshavedamshaAll matters of lifePro
D60ShastiamshaPast life karma (most powerful varga)Pro

Request Example

POST /v1/divisional — single chart 
{
  "api_key": "your_api_key",
  "dob":     "1987-07-08",
  "tob":     "19:25",
  "lat":     30.7333,
  "lon":     76.7794,
  "tz":      5.5,
  "chart":   "D9"
}
POST /v1/divisional — multiple charts 
{
  "api_key": "your_api_key",
  "dob":     "1987-07-08",
  "tob":     "19:25",
  "lat":     30.7333,
  "lon":     76.7794,
  "tz":      5.5,
  "chart":   ["D9", "D10"]
}

Response Structure

200 OK — D9 response (abbreviated) 
{
  "status": "success",
  "data": {
    "D9": {
      "meta": {
        "D":    9,
        "name": "Navamsha",
        "desc": "Marriage, dharma, soul purpose"
      },
      "lagna": {
        "sign":     "Libra",
        "sign_num": 7,
        "lord":     "Venus"
      },
      "planets": {
        "sun": {
          "sign":      "Gemini",
          "sign_num":  3,
          "house":     9,
          "retrograde": false,
          "combust":    false
        },
        "moon": { /* same structure */ },
        // mars, mercury, jupiter, venus, saturn, rahu, ketu …
      }
    }
  },
  "meta": {
    "powered_by": "SoulOS Kundli API — soulmapbysahil.in",
    "by":         "Dr. Sahil Kohli | Kohli Media LLP",
    "engine":     "SoulOS Ephemeris v1.0",
    "ayanamsa":   "Lahiri",
    "charts":     ["D9"]
  }
}

Response Fields

FieldTypeDescription
data.{D}.meta.DintDivisional number (e.g. 9 for D9)
data.{D}.meta.namestringSanskrit name (e.g. "Navamsha")
data.{D}.meta.descstringDomain of life this chart governs
data.{D}.lagna.signstringLagna (ascendant) sign in this varga
data.{D}.lagna.sign_numintLagna sign number 1–12
data.{D}.lagna.lordstringLord of the lagna sign
data.{D}.planets.{name}.signstringPlanet's sign in this varga
data.{D}.planets.{name}.sign_numintSign number 1–12
data.{D}.planets.{name}.houseintHouse from lagna in this varga (1–12)
data.{D}.planets.{name}.retrogradeboolWhether planet is retrograde
data.{D}.planets.{name}.combustboolWhether planet is combust (within 6° of Sun)

Plan Gating

Requesting a Pro-only chart with a free key returns a 403 PLAN_LIMIT error for that chart. D1, D9, and D10 are available on all plans.

403 — PLAN_LIMIT 
{
  "status":  "error",
  "code":    "PLAN_LIMIT",
  "message": "D12 requires Pro plan. Requested: D12. Allowed on your plan: D1, D9, D10"
}
  • One swetest call is made per request regardless of how many charts you request — batch ["D9","D10"] is the same cost as "D9" alone
  • House numbers are computed as ((planet_sign - lagna_sign + 12) % 12) + 1 relative to the varga lagna
  • D30 (Trimsamsha) uses the non-equal Parashari division, not the equal variant — follow BPHS Ch. 7
  • For transit (gochar) overlays over natal D9, call this endpoint with today's date/time and compare to the stored natal chart client-side
  • The response is designed to be pasted directly into an AI prompt for Vedic interpretation — use the "Copy to AI" button on freekundli.in result page to see the format
Endpoint

POST /v1/dosha

Detect the four classical Vedic doshas for a natal chart. All detections are Parashari BPHS only — no invented doshas, no KP, no Western equivalents. Kaal Sarpa Dosha is not included as it has no source in any classical text.

Doshas detected: Mangal Dosha (BPHS Ch. 18), Shrapit Dosha (BPHS Ch. 84), Pitra Dosha (BPHS Ch. 32), Sadhe Sati (BPHS Ch. 45).

Request

FieldTypeRequiredDescription
dobstringYesDate of birth — YYYY-MM-DD
tobstringYesTime of birth — HH:MM or HH:MM:SS (local time)
latnumberYesLatitude of birth place (decimal degrees)
lonnumberYesLongitude of birth place (decimal degrees)
tznumberNoUTC offset in hours. Default: 5.5 (IST)
gochar_datestringNoYYYY-MM-DD date for Sadhe Sati calculation (Saturn's current position). Defaults to today IST.

Example Request

POST /v1/dosha 
{
  "dob":         "1990-07-15",
  "tob":         "08:30",
  "lat":         28.6139,
  "lon":         77.2090,
  "tz":          5.5,
  "gochar_date": "2026-05-24"
}

Response — data object

Response 
{
  "doshas": {
    "mangal_dosha": {
      "name":                   "Mangal Dosha",
      "present":                true,
      "raw_present":            true,
      "cancelled":              false,
      "cancellation_reason":    "",
      "intensity":              "medium",
      "mars_sign":              "Aries",
      "mars_house_from_lagna":  12,
      "mars_house_from_moon":   8,
      "mars_house_from_venus":  3,
      "active_references":      [
        { "reference": "Lagna", "mars_house": 12 },
        { "reference": "Moon",  "mars_house": 8  }
      ],
      "jupiter_aspects_mars":   false,
      "source":                 "BPHS Ch. 18"
    },
    "shrapit_dosha": {
      "name":         "Shrapit Dosha",
      "present":      false,
      "saturn_sign":  "Capricorn",
      "saturn_house": 10,
      "rahu_sign":    "Gemini",
      "rahu_house":   5,
      "source":       "BPHS Ch. 84"
    },
    "pitra_dosha": {
      "name":            "Pitra Dosha",
      "present":         true,
      "triggers":        [
        { "type": "A", "description": "Rahu in 9th house from Lagna." }
      ],
      "trigger_count":  1,
      "ninth_lord":     "Mercury",
      "rahu_house":     9,
      "source":         "BPHS Ch. 32"
    },
    "sadhe_sati": {
      "name":                     "Sadhe Sati",
      "present":                  true,
      "phase":                    "peak",
      "phase_description":        "Peak phase: Saturn transiting natal Moon sign directly...",
      "natal_moon":               "Pisces",
      "gochar_saturn":             "Pisces",
      "saturn_house_from_moon":   1,
      "source":                   "BPHS Ch. 45"
    }
  },
  "natal_moon":    "Pisces",
  "lagna":         "Taurus",
  "gochar_date":   "2026-05-24",
  "gochar_saturn": "Pisces"
}

Dosha fields reference

Doshapresent = true whenCancellationsSource
Mangal Dosha Mars in houses 1, 2, 4, 7, 8, or 12 from Lagna, Moon, or Venus Mars in own sign (Aries/Scorpio) or exalted (Capricorn); Lagna is Aries/Scorpio BPHS Ch. 18
Shrapit Dosha Saturn and Rahu conjunct in the same house None — presence is the condition BPHS Ch. 84
Pitra Dosha Any of: Rahu/Ketu in 9th; Sun conjunct Rahu/Ketu in 9th; Saturn in 9th; 9th lord conjunct Saturn/Rahu/Ketu Multiple triggers increase severity (see trigger_count) BPHS Ch. 32
Sadhe Sati Gochar Saturn in 12th, 1st, or 2nd sign from natal Moon. Phase: rising / peak / setting N/A — phase ends when Saturn moves to 3rd sign from Moon BPHS Ch. 45

Notes

  • Kaal Sarpa Dosha is not included — it appears in no classical Vedic text (BPHS, Jaimini Sutras, Uttara Kalamrita, Saravali). It is a modern invention. SoulOS does not implement non-classical doshas.
  • Sadhe Sati phase lasts ~2.5 years per phase (total ~7.5 years) as Saturn transits each sign at ~30 months.
  • Mangal raw_present is true even when cancelled — useful for showing "Mangal Dosha but cancelled" text to the user.
  • Mangal jupiter_aspects_mars is provided as additional context even when it doesn't trigger cancellation.
  • All calculations use Lahiri Ayanamsa, Whole Sign houses, Swiss Ephemeris 2.10.
Endpoint

POST /v1/ankashastra

Vedic Ankashastra — the classical planetary number system. Sun=1 Moon=2 Jupiter=3 Rahu=4 Mercury=5 Venus=6 Ketu=7 Saturn=8 Mars=9.

Computes Moolank (birth number), Bhagyank (destiny number), Universal Day, Personal Day, and optionally Naam Ank (name number). All numbers reduce to 1–9. No master numbers. Compatibility uses Naisargik Maitri from BPHS.

This is the only correct Vedic numerology. Not Pythagorean (A=1,B=2…). Not Chaldean. The letter mapping is phonetic — based on each sound's planetary resonance per classical Vedic tradition.

Request

FieldTypeRequiredDescription
dobstringYesDate of birth — YYYY-MM-DD
namestringNoFull name — triggers Naam Ank calculation and Moolank–name compatibility
datestringNoYYYY-MM-DD — date for Universal Day and Personal Day. Defaults to today IST.
moon_rashiintegerNoNatal Moon sign 1–12 (Aries=1 … Pisces=12). Enables Moolank ↔ Moon-lord compatibility block.

Example Request — Moolank + Bhagyank only

POST /v1/ankashastra 
{
  "dob":         "1990-07-15",
  "date":        "2026-05-25"
}

Example Request — with name and Moon sign

POST /v1/ankashastra 
{
  "dob":         "1990-07-15",
  "name":        "Sahil Kohli",
  "date":        "2026-05-25",
  "moon_rashi":  8
}

Response — data object

Response 
{
  "moolank": {
    "number":        6,
    "planet":        "Venus",
    "planet_hi":     "शुक्र",
    "planet_hg":     "Venus (Shukra)",
    "sanskrit":      "Shukra",
    "qualities_en":  "Love, beauty, harmony, creativity, relationships",
    "qualities_hi":  "प्रेम, सौंदर्य, सामंजस्य, रचनात्मकता",
    "qualities_hg":  "Love, beauty, harmony, creativity",
    "nature_en":     "Venus blesses with charm, artistic sense, and a deep need for beauty...",
    "nature_hi":     "शुक्र को सौंदर्य, कला और सहचर्य का आशीर्वाद देता है...",
    "nature_hg":     "Venus deta hai charm, artistic sense...",
    "lucky_day_en":  "Friday",
    "lucky_day_hi":  "शुक्रवार",
    "lucky_color_en": "White, Cream, Pale Pink",
    "lucky_gem_en":   "Diamond (Heera)",
    "birth_days":    [6, 15, 24],
    "deity":         "Lakshmi"
  },
  "bhagyank": {
    "number":  4,
    "planet":  "Rahu"
    // ...same fields as moolank...
  },
  "universal_day": {
    "number":  3,
    "planet":  "Jupiter",
    "date":    "2026-05-25"
    // ...same fields as moolank...
  },
  "personal_day": {
    "number":  9,
    "planet":  "Mars",
    "date":    "2026-05-25"
    // ...same fields as moolank...
  },
  "naam_ank": {
    "number":       5,
    "planet":       "Mercury",
    "name_used":    "SAHILKOHLI",
    "raw_sum":      59,
    "letter_map":   { "S":3, "A":1, "H":5, "I":1, "L":3, "K":2, "O":7 },
    "moolank_compatibility": {
      "code":      "F",
      "en":        "Friend",
      "hi":        "मित्र",
      "hg":        "Mitra (Friend)",
      "effect_en": "Supportive and harmonious. Natural alignment of energies.",
      "planets":   ["Venus", "Mercury"]
    }
    // ...same planet fields as moolank...
  },
  "compatibility": {
    "moolank_bhagyank": {
      "code":      "N",
      "en":        "Neutral",
      "hi":        "सम",
      "effect_en": "Mixed results. Neither blocked nor fully supported.",
      "planets":   ["Venus", "Rahu"]
    },
    "moolank_moon_lord": {
      "code":       "E",
      "en":         "Enemy",
      "effect_en":  "Friction and challenge. Growth comes through conscious effort.",
      "moon_rashi": "Scorpio",
      "moon_lord":  "Mars",
      "planets":    ["Venus", "Mars"]
    }
  }
}

Planetary Number System

NumberPlanetSanskritBirth DaysQualities
1Sun (Surya)सूर्य1, 10, 19, 28Leadership, authority, clarity of purpose
2Moon (Chandra)चंद्र2, 11, 20, 29Intuition, sensitivity, nurturing
3Jupiter (Guru)गुरु3, 12, 21, 30Wisdom, expansion, dharma, generosity
4Rahuराहु4, 13, 22, 31Ambition, transformation, unconventional paths
5Mercury (Budha)बुध5, 14, 23Intelligence, communication, adaptability
6Venus (Shukra)शुक्र6, 15, 24Love, beauty, harmony, creativity
7Ketuकेतु7, 16, 25Spirituality, intuition, liberation, detachment
8Saturn (Shani)शनि8, 17, 26Discipline, karma, structure, endurance
9Mars (Mangal)मंगल9, 18, 27Energy, courage, action, completion

Vedic Letter Mapping (Naam Ank)

Based on Sanskrit phonetic affinity — NOT Pythagorean sequential (A=1,B=2…). Each letter group shares sound-energy with its ruling planet.

NumberPlanetLetters
1SunA, I, J, Q, Y
2MoonB, K, R
3JupiterC, G, L, S
4RahuD, M, T
5MercuryE, H, N, X
6VenusU, V, W
7KetuO, Z
8SaturnF, P
9MarsAll remaining letters

Compatibility Codes (Naisargik Maitri)

CodeMeaningEffect
FFriend (Mitra)Supportive and harmonious. Natural alignment of energies.
NNeutral (Sama)Mixed results. Neither blocked nor fully supported.
EEnemy (Shatru)Friction and challenge. Growth comes through conscious effort.

Notes

  • No master numbers. 11 reduces to 2, 22 reduces to 4. Always 1–9 per Vedic Ankashastra.
  • Moolank = birth day digits only. Born 17th: 1+7=8 (Saturn).
  • Bhagyank = full DOB all digits. 15/08/1990: 1+5+0+8+1+9+9+0=33 → 3+3=6 (Venus).
  • Universal Day = today's date digits reduced. Same for everyone on that date.
  • Personal Day = reduce(Moolank + Universal Day). Unique per person, changes daily.
  • Naam Ank strips non-alphabetic characters, uppercases the string, maps each letter via the Vedic phonetic table, sums all values, and reduces to 1–9.
  • Compatibility is drawn from BPHS Naisargik Maitri (natural friendship between planet lords).
  • This endpoint requires only DOB — no time, place, or coordinates needed.
Errors

Error Codes

All errors return a consistent JSON envelope with status: "error", a machine-readable code, and a human-readable message.

HTTPCodeMeaning
401AUTH_FAILEDMissing or invalid API key
400MISSING_FIELDRequired field not provided
400INVALID_JSONRequest body is not valid JSON
405METHOD_NOT_ALLOWEDOnly POST is accepted on this endpoint
429RATE_LIMITDaily call limit exceeded for your plan
403PLAN_EXPIREDSubscription plan has expired
404ENDPOINT_NOT_FOUNDInvalid endpoint path
500ENGINE_ERRORCalculation engine failed
Error Response 
{
  "status":  "error",
  "code":    "MISSING_FIELD",
  "message": "dob is required"
}
Plans

Rate Limits

Limits are enforced per API key per UTC day. The calls_today counter resets at midnight IST.

PlanCalls / DayCalls / MinEndpointsPrice
Free 100 10 chart, dasha, dosha, panchang ₹ 0
Starter 1,000 30 + ashtakvarga, transit ₹ 499 / mo
Pro 5,000 60 All endpoints + divisional + compatibility ₹ 2,999 / mo
Enterprise Unlimited Unlimited All endpoints + webhook + SLA Custom
When you hit the limit, the API returns HTTP 429 with code: "RATE_LIMIT". Your counter resets automatically at midnight IST — no action needed.
Support

Support

For integration help, partnership, or enterprise access — reach out directly. We respond fast.

care@kohli.tel soulmapbysahil.in Get Free Key

Frequently Asked Questions

Quick answers for developers integrating the SoulOS Kundli API.

What is the API endpoint? +

POST https://kundli.soulmapbysahil.in/v1/chart — send JSON with dob (YYYY-MM-DD), tob (HH:MM), lat (decimal), lon (decimal), tz (float, default 5.5), and your api_key or Authorization: Bearer header.

How many Dasha levels are returned? +

All 5 levels — Mahadasha, Antardasha, Pratyantar, Sookshma, and Prana — with exact start and end dates. Use dasha_depth (1–5) to limit depth. dasha_depth=1 gives 9 MD entries; dasha_depth=5 gives all ~66,000 entries pre-calculated.

Which ayanamsa and house system? +

Lahiri ayanamsa (Chitra Paksha, official Indian government standard) and Whole Sign houses as prescribed by Maharishi Parashar in BPHS. The ayanamsa value is returned in every response under meta.ayanamsa.

What yogas does the API detect? +

40 Parashari Yogas across 7 categories — Pancha Mahapurusha, Raja, Dhana, Chandra, Surya, Viparita Raja, and Special. Each yoga includes name, category, nature (benefic/challenging), description, planets involved, and house positions. Only actually-present yogas are returned — empty array if none.

Is there a free tier? +

Yes. 100 calls/day forever free — no credit card required. Register at /dev/register.php. Paid plans start at ₹499/month for 1,000 calls/day.

What does the response include? +

basic (lagna, rashi, nakshatra), planets (9 planets with sign, degree, nakshatra, pada, retrograde, combust), houses (12), nakshatras, avkahada chakra, dasha (5-level Vimshottari + current chain), yogas, lagna_degree, combustion map.

How does the Kundali Milan / compatibility API work? +

POST /v1/compatibility — Mode A: pass boy_nakshatra, boy_rashi, girl_nakshatra, girl_rashi directly. Mode B: pass full boy{} and girl{} birth details (dob, tob, lat, lon, tz) and the API calculates Nakshatra/Rashi via ephemeris. Returns all 8 Ashtakoot gunas (Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi), total score out of 36, percentage, verdict, and any doshas present.

How does the Panchang API work? +

POST /v1/panchang with date (YYYY-MM-DD), time (HH:MM, optional), lat, lon, and tz. Returns all 5 Panchang elements — Vara (weekday + lord), Tithi (lunar day + paksha + nature), Nakshatra (Moon star + pada + lord), Yoga (Sun+Moon combination + quality), and Karana (half-tithi + quality) — with degree elapsed/remaining for each element so you can show progress within the current element.

What is POST /v1/synastry and how is it different from compatibility? +

POST /v1/synastry implements Parashari Graha-Sthiti — a planetary overlay technique. It places Person 1's planets into Person 2's houses and vice versa to show how each person's planetary energy lands in specific life domains of their partner. Unlike Ashtakoot compatibility (which scores by Nakshatra), synastry works at the degree level with the full birth chart. It returns both overlays (p1_on_p2 and p2_on_p1), 108 interpretation texts, a themes summary, and a Mahadasha-level timing narrative showing which life chapter each person is currently running and where that energy lands in the partner's chart.