Kundali API Documentation

Table of Contents

Getting Started

The Vedika Kundali API provides comprehensive Vedic astrology calculations through simple REST endpoints. This guide covers all birth chart related endpoints with complete examples.

Base URL

https://api.vedika.io

Quick Start

1. Sign up at vedika.io/dashboard
2. Copy your API key from the dashboard
3. Make your first request (see examples below)
4. Parse the JSON response

Authentication

All API requests require authentication using your API key in the Authorization: Bearer <key> header.

Header Format

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example Request

curl -X POST https://api.vedika.io/v2/astrology/birth-chart \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T10:30:00",
    "latitude": 19.07,
    "longitude": 72.87,
    "timezone": "+05:30"
  }'

Birth Chart Endpoint

Request Parameters

Example Request Body

{
  "datetime": "1990-05-15T10:30:00",
  "latitude": 19.07,
  "longitude": 72.87,
  "timezone": "+05:30",
  "ayanamsa": "lahiri",
  "language": "en"
}

Response Format

{
  "success": true,
  "data": {
    "ascendant": {
      "sign": "Cancer",
      "signLord": "Moon",
      "degree": 2.41,
      "fullDegree": 92.41,
      "nakshatra": {"name": "Punarvasu", "lord": "Jupiter", "pada": 4}
    },
    "sunSign": "Taurus",
    "moonSign": "Sagittarius",
    "nakshatra": "Uttara Ashadha",
    "tithi": "Krishna Panchami",
    "planets": [
      {
        "name": "Sun",
        "sign": "Taurus",
        "signLord": "Venus",
        "house": 11,
        "degree": 0.4,
        "fullDegree": 30.4,
        "isRetrograde": false,
        "nakshatra": {"name": "Krittika", "lord": "Sun", "pada": 2}
      }
      // ... other planets
    ],
    "houses": [
      {"number": 1, "sign": "Cancer", "lord": "Moon", "cusp": 90}
      // ... houses 2-12
    ]
  },
  "billing": {"charged": 0.02, "currency": "USD", "category": "chart"}
}

Planetary Positions

Available Planets

• Sun (Surya) - Atma Karaka, self, soul
• Moon (Chandra) - Manas Karaka, mind, emotions
• Mars (Mangal) - Energy, courage, siblings
• Mercury (Budh) - Intelligence, communication
• Jupiter (Guru) - Wisdom, knowledge, children
• Venus (Shukra) - Love, beauty, luxury
• Saturn (Shani) - Discipline, karma, delays
• Rahu - North Node, worldly desires
• Ketu - South Node, spirituality, moksha

Planetary Dignities

Divisional Charts (Vargas)

Available Divisional Charts

Example: Get Navamsa Chart (D9)

POST /v2/astrology/navamsa

{
  "datetime": "1990-05-15T10:30:00",
  "latitude": 19.07,
  "longitude": 72.87,
  "timezone": "+05:30"
}

Dasha Periods

Vimshottari Dasha Duration

Response Example

{
  "success": true,
  "data": {
    "nakshatra": {"id": 21, "name": "Uttara Ashadha", "lord": "Sun", "pada": 1},
    "dasha_balance": {"planet": "Sun", "years": 4, "months": 6, "days": 24},
    "current_dasha": {
      "maha_dasha": {"planet": "Rahu", "start_date": "2011-12-09", "end_date": "2029-12-09"},
      "antar_dasha": {"planet": "Sun", "start_date": "2026-06-28", "end_date": "2027-05-23"},
      "pratyantar_dasha": {"planet": "Rahu", "start_date": "2026-08-29", "end_date": "2026-10-17"}
    },
    "maha_dasha": [
      {
        "planet": "Sun",
        "start_date": "1990-05-15",
        "end_date": "1994-12-08",
        "duration_years": 4.57,
        "is_current": false,
        "antar_dasha": [...]
      }
      // ... remaining mahadashas
    ]
  }
}

Yoga Detection

Major Yoga Categories

• Panch Mahapurusha Yogas - Five great planetary yogas
• Raj Yogas - Royal combinations for success and power
• Dhan Yogas - Wealth-giving combinations
• Gaja Kesari Yoga - Wisdom and prosperity
• Neech Bhang Raj Yoga - Cancellation of debilitation
• Budhaditya Yoga - Sun-Mercury combination for intelligence
• Chandra-Mangal Yoga - Moon-Mars for wealth

Response Format

{
  "success": true,
  "data": {
    "system": "jaimini",
    "rajayogas": [
      {
        "name": "Atmakaraka-Amatyakaraka conjunction",
        "formed": true,
        "planets": ["Saturn", "Mercury"],
        "houses": [9, 10],
        "description": "Soul significator joined with the minister significator",
        "strength": "strong"
      }
    ]
  }
}

Kundali Matching

Eight Kootas (Gunas)

Request Example

{
  "male": {
    "datetime": "1995-06-20T10:30:00",
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": "+05:30"
  },
  "female": {
    "datetime": "1997-03-15T14:00:00",
    "latitude": 19.076,
    "longitude": 72.8777,
    "timezone": "+05:30"
  }
}

Response Example

{
  "success": true,
  "data": {
    "total_points": 17.5,
    "maximum_points": 36,
    "percentage": 49,
    "match_result": "Not Compatible",
    "recommendation": "Low compatibility - Not recommended for marriage",
    "guna_kootas": [
      {"name": "Varna", "points": 1, "maximum_points": 1, "description": "Brahmin (male) vs Vaishya (female)"},
      {"name": "Vasya", "points": 1, "maximum_points": 2, "description": "Partial Vasya"},
      {"name": "Tara", "points": 1.5, "maximum_points": 3}
      // ... remaining kootas
    ],
    "male_info": {"moon_nakshatra": "Uttara Bhadrapada", "moon_sign": "Pisces"},
    "female_info": {"moon_nakshatra": "Mrigashira", "moon_sign": "Taurus"}
  }
}

Complete Code Examples

Python Example

import os
import requests

class VedikaAPI:
    def __init__(self, api_key):
        self.base_url = "https://api.vedika.io"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def post(self, path, body):
        """Every v2 call returns {"success": true, "data": {...}, "billing": {...}}"""
        response = requests.post(f"{self.base_url}{path}", json=body, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_birth_chart(self, birth_data):
        """Get complete birth chart"""
        return self.post("/v2/astrology/birth-chart", birth_data)

    def get_dashas(self, birth_data):
        """Get Vimshottari dasha periods"""
        return self.post("/v2/astrology/vimshottari-dasha", birth_data)

    def match_kundali(self, male, female):
        """Ashtakoota (36 guna) matching"""
        return self.post("/v2/astrology/guna-milan", {"male": male, "female": female})

# Usage
api = VedikaAPI(os.environ["VEDIKA_API_KEY"])

birth_data = {
    "datetime": "1990-05-15T10:30:00",
    "latitude": 19.07,
    "longitude": 72.87,
    "timezone": "+05:30",
    "ayanamsa": "lahiri"
}

# Get birth chart
chart = api.get_birth_chart(birth_data)["data"]
print(f"Sun Sign: {chart['sunSign']}")
print(f"Moon Sign: {chart['moonSign']}")
print(f"Ascendant: {chart['ascendant']['sign']}")

for planet in chart["planets"]:
    print(f"- {planet['name']}: {planet['sign']}, house {planet['house']}")

# Get current dasha
dashas = api.get_dashas(birth_data)["data"]
print(f"\nCurrent Mahadasha: {dashas['current_dasha']['maha_dasha']['planet']}")
print(f"Current Antardasha: {dashas['current_dasha']['antar_dasha']['planet']}")

# Match two charts
male = {"datetime": "1995-06-20T10:30:00", "latitude": 28.6139, "longitude": 77.209, "timezone": "+05:30"}
female = {"datetime": "1997-03-15T14:00:00", "latitude": 19.076, "longitude": 72.8777, "timezone": "+05:30"}
match = api.match_kundali(male, female)["data"]
print(f"\nGuna Milan: {match['total_points']} / {match['maximum_points']} ({match['match_result']})")

JavaScript (Node.js) Example

const axios = require('axios');

class VedikaAPI {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseURL = 'https://api.vedika.io';
        this.headers = {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        };
    }

    // Every v2 call returns { success, data, billing }
    async post(path, body) {
        const response = await axios.post(`${this.baseURL}${path}`, body, { headers: this.headers });
        return response.data;
    }

    async getBirthChart(birthData) {
        return this.post('/v2/astrology/birth-chart', birthData);
    }

    async getDivisionalChart(division, birthData) {
        return this.post('/v2/astrology/divisional-chart', { ...birthData, division });
    }

    async getYogas(birthData) {
        return this.post('/v2/astrology/jaimini/rajayogas', birthData);
    }
}

// Usage
const api = new VedikaAPI(process.env.VEDIKA_API_KEY);

const birthData = {
    datetime: '1990-05-15T10:30:00',
    latitude: 19.07,
    longitude: 72.87,
    timezone: '+05:30'
};

(async () => {
    // Get birth chart
    const chart = await api.getBirthChart(birthData);
    console.log('Planetary Positions:');
    chart.data.planets.forEach((planet) => {
        console.log(`${planet.name}: ${planet.sign} (${planet.degree.toFixed(2)}°)`);
    });

    // Get Navamsa chart (division 9)
    const navamsa = await api.getDivisionalChart(9, birthData);
    console.log('\nNavamsa Chart:');
    console.log(navamsa.data);

    // Get Jaimini rajayogas
    const yogas = await api.getYogas(birthData);
    console.log('\nRajayogas:');
    console.log(yogas.data);
})();

PHP Example

<?php

class VedikaAPI {
    private $apiKey;
    private $baseURL = 'https://api.vedika.io';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    private function makeRequest($endpoint, $data) {
        $ch = curl_init($this->baseURL . $endpoint);

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new Exception("API Error: " . $response);
        }

        return json_decode($response, true);
    }

    public function getBirthChart($birthData) {
        return $this->makeRequest('/v2/astrology/birth-chart', $birthData);
    }

    public function getDashas($birthData) {
        return $this->makeRequest('/v2/astrology/vimshottari-dasha', $birthData);
    }

    public function matchKundali($male, $female) {
        return $this->makeRequest('/v2/astrology/guna-milan', [
            'male' => $male,
            'female' => $female
        ]);
    }
}

// Usage
$api = new VedikaAPI(getenv('VEDIKA_API_KEY'));

$birthData = [
    'datetime' => '1990-05-15T10:30:00',
    'latitude' => 19.07,
    'longitude' => 72.87,
    'timezone' => '+05:30'
];

try {
    // Get birth chart
    $chart = $api->getBirthChart($birthData);

    echo "Birth Chart Analysis\n";
    echo "===================\n\n";

    echo "Sun sign: " . $chart['data']['sunSign'] . "\n";
    echo "Moon sign: " . $chart['data']['moonSign'] . "\n";
    echo "Ascendant: " . $chart['data']['ascendant']['sign'] . "\n\n";

    // Get dashas
    $dashas = $api->getDashas($birthData);
    echo "Current Dasha Periods:\n";
    echo "Mahadasha: " . $dashas['data']['current_dasha']['maha_dasha']['planet'] . "\n";
    echo "Antardasha: " . $dashas['data']['current_dasha']['antar_dasha']['planet'] . "\n";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

?>

Best Practices

1. Error Handling

Always implement comprehensive error handling:

try {
    const chart = await api.getBirthChart(birthData);
} catch (error) {
    if (error.response) {
        // Server error
        if (error.response.status === 400) {
            console.error('Invalid birth data');
        } else if (error.response.status === 401) {
            console.error('Invalid API key');
        } else if (error.response.status === 429) {
            console.error('Rate limit exceeded');
        }
    } else {
        // Network error
        console.error('Network error');
    }
}

2. Caching

Cache birth charts to reduce API calls:

• Birth charts never change - cache indefinitely
• Use user ID or birth details hash as cache key
• Implement Redis or in-memory caching
• Set appropriate TTL for different endpoints

3. Input Validation

Validate data before API calls:

• Date: Valid YYYY-MM-DD format, reasonable range (1800-2100)
• Time: 24-hour HH:MM format
• Latitude: -90 to 90
• Longitude: -180 to 180
• Timezone: -12 to +14

4. Rate Limiting

Respect API rate limits:

• Starter: 300 credits/month ($12), Pro: 1,500 credits ($60), Business: 3,000 credits ($120), Enterprise: 6,000 credits ($240)
• Implement request queuing for batch operations
• Add exponential backoff for 429 errors
• Monitor usage via dashboard

5. Security

• Never expose API keys in frontend JavaScript
• Use environment variables for API keys
• Implement backend proxy for client requests
• Rotate API keys periodically
• Use HTTPS for all requests