What ayanamsa does the SoulOS Kundli API use?

SoulOS Kundli API uses the Lahiri ayanamsa (also known as Chitra Paksha), which is the official ayanamsa recommended by the Indian government and the most widely used in Parashari Jyotish.

Which house system does the API use?

The API uses the Whole Sign house system as prescribed by Maharishi Parashar in Brihat Parashar Hora Shastra (BPHS). In this system, each house corresponds to exactly one zodiac sign, with the rising sign (lagna) as the first house.

How do I authenticate with the SoulOS Kundli API?

Pass your API key in the HTTP Authorization header as a Bearer token: Authorization: Bearer soul_live_YOUR_KEY. Alternatively, include api_key in the JSON request body. Get a free API key at kundli.soulmapbysahil.in/dev/register.

What is the base URL for the SoulOS Kundli API?

The base URL is https://kundli.soulmapbysahil.in. The chart calculation endpoint is POST https://kundli.soulmapbysahil.in/v1/chart.

What ephemeris engine does the API use?

SoulOS Kundli API is powered by Swiss Ephemeris version 2.10.03 — the gold standard astronomical ephemeris library used by professional astrology software worldwide.

Does the API support Vimshottari Dasha calculations?

Yes. The API returns full Vimshottari Dasha periods up to Panchama (5th level) — Mahadasha, Antardasha, Pratyantardasha, Sookshma, and Prana dashas — with precise start and end dates.

What yogas can the API detect?

The API detects Raj Yogas, Dhan Yogas, Pancha Mahapurusha Yogas (Ruchaka, Bhadra, Hamsa, Malavya, Sasha), Gajakesari Yoga, Budha-Aditya Yoga, Neecha Bhanga Raja Yoga, and more — following classical Parashari rules.

Is the Kundli API free to use?

Yes — the free Developer tier gives 100 API calls per day at no cost. Paid plans (Starter ₹499/month, Pro ₹2,999/month, Enterprise custom) offer higher limits and commercial use rights.

What does the dasha_depth parameter do?

The dasha_depth parameter (integer 1–5, default 5) controls how many levels of Vimshottari Dasha are pre-calculated in the response. Depth 1 returns 9 Mahadasha entries. Depth 2 adds 81 Antardasha entries. Depth 3 adds 729 Pratyantar entries. Depth 4 adds 6,561 Sookshma entries. Depth 5 adds all 59,049 Prana entries. The current active chain is always returned at all 5 levels regardless of dasha_depth.

What is the Avkahada Chakra in Vedic astrology?

Avkahada Chakra is a traditional Vedic summary table derived from the Moon's Nakshatra and Rashi at birth. It includes Varna (caste/quality), Vashya (compatibility group), Yoni (animal symbol), Gana (temperament — Deva, Manushya, or Rakshasa), Nadi (Adi, Madhya, or Antya), and Bhuta (element). The SoulOS Kundli API returns all Avkahada values in every chart response.

How do I calculate Kundli Milan (compatibility) with the API?

Use POST /v1/compatibility — a dedicated Ashtakoot (8-guna, 36-point) Kundali Milan endpoint. Pass either nakshatra and rashi directly (Mode A) or full birth details for both partners (Mode B) and the API returns a complete compatibility breakdown: all 8 gunas with scores, doshas identified (Nadi, Bhakoot, Varna), and an overall verdict from Excellent to Poor.

SoulOS Kundli API Docs — Vedic Astrology REST API | Lahiri Ayanamsa, Swiss Ephemeris

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

Field	Type	Status	Description
`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.
`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

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

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_depth	Levels returned	Total entries	Use case
`1`	Mahadasha	9	Quick lookup, dashboards
`2`	MD + Antardasha	81	Most apps — years-level planning
`3`	+ Pratyantar	729	Month-level precision
`4`	+ Sookshma	6,561	Week-level precision
`5`	+ Prana (default)	~66,430	Day-level precision, full pre-calculation

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

Yogas

8 Parashar Yogas checked per Brihat Parashar Hora Shastra — Gajakesari, Budhaditya, Chandra-Mangal, and all 5 Pancha Mahapurusha Yogas (Hamsa, Malavya, Ruchaka, Sasa, Bhadra). Only yogas present in the chart are returned. If no yoga is present, the array is empty.

response.json → data.yogas

"yogas": [
  {
    "name":              "Budhaditya Yoga",
    "present":          true,           // always true — absent yogas are not returned
    "description":      "Sun and Mercury conjunct. Sharp intellect, eloquence.",
    "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" }
  },
  "meta": { "response_time_ms": 42, "ayanamsa": "Lahiri", "engine": "Swiss Ephemeris 2.10" }
}

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.

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

Field	Type	Required	Description
api_key	string	Yes	Your API key
p1	object	Yes	Person 1 birth details (see sub-fields below)
p2	object	Yes	Person 2 birth details (same structure as p1)
p1.dob	string	Yes	Date of birth — YYYY-MM-DD
p1.tob	string	Yes	Time of birth — HH:MM (24h)
p1.lat	float	Yes	Latitude of birth place (decimal degrees)
p1.lon	float	Yes	Longitude of birth place (decimal degrees)
p1.tz	float	No	UTC offset (default 5.5 for IST)
p1.name	string	No	Display name used in interpretation texts
interpret	bool	No	Include 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":           "Swiss Ephemeris 2.10",
    "method":           "Parashari Graha-Sthiti (Planetary Overlay)"
  }
}

Themes Reference

Theme	What 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

Errors

Error Codes

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

HTTP	Code	Meaning
401	AUTH_FAILED	Missing or invalid API key
400	MISSING_FIELD	Required field not provided
400	INVALID_JSON	Request body is not valid JSON
405	METHOD_NOT_ALLOWED	Only POST is accepted on this endpoint
429	RATE_LIMIT	Daily call limit exceeded for your plan
403	PLAN_EXPIRED	Subscription plan has expired
404	ENDPOINT_NOT_FOUND	Invalid endpoint path
500	ENGINE_ERROR	Calculation 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.

Plan	Calls / Day	Calls / Min	Endpoints	Price
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

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

care@kohli.tel soulmapbysahil.in Get Free Key

SoulOS Kundli API

API Keys

Your First Request

cURL

Python

PHP

JavaScript

POST /v1/chart

Request Body

Complete Response

JSON Basic Info

Planets

Houses

Vimshottari Dasha — All 5 Levels

JSON Top-level structure

Depth reference

Yogas

Nakshatra & Avkahada

POST /v1/compatibility

JSON Mode A — Direct Nakshatra/Rashi

JSON Mode B — Full Birth Details

JSON Response

Gunas Reference

POST /v1/panchang

JSON Request Body

JSON Response

Panchang Elements Reference

POST /v1/synastry

Request Parameters

Request Example

Response Structure

Themes Reference

Notes

Error Codes

Rate Limits

Support

Frequently Asked Questions