Kundali API Documentation

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/v1

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 x-api-key header.

Header Format

x-api-key: YOUR_API_KEY
Content-Type: application/json

Example Request

curl -X POST https://api.vedika.io/v1/birth-chart \
  -H "x-api-key: vdk_abc123xyz456" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-06-15",
    "time": "14:30",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": 5.5
  }'

Birth Chart Endpoint

Request Parameters

Example Request Body

{
  "date": "1990-06-15",
  "time": "14:30",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "timezone": 5.5,
  "ayanamsa": "lahiri",
  "language": "en"
}

Response Format

{
  "status": "success",
  "data": {
    "planets": {
      "sun": {
        "sign": "Gemini",
        "sign_lord": "Mercury",
        "degree": 24.5678,
        "house": 10,
        "nakshatra": "Punarvasu",
        "nakshatra_lord": "Jupiter",
        "pada": 3,
        "retrograde": false,
        "combust": false,
        "dignity": "neutral"
      },
      "moon": {
        "sign": "Pisces",
        "sign_lord": "Jupiter",
        "degree": 12.3456,
        "house": 7,
        "nakshatra": "Uttara Bhadrapada",
        "nakshatra_lord": "Saturn",
        "pada": 2,
        "retrograde": false,
        "dignity": "exalted"
      }
      // ... other planets
    },
    "houses": {
      "1": {
        "sign": "Virgo",
        "degree": 15.23,
        "lord": "Mercury"
      }
      // ... houses 2-12
    },
    "ascendant": {
      "sign": "Virgo",
      "degree": 15.23,
      "nakshatra": "Hasta",
      "pada": 1
    },
    "yogas": [
      {
        "name": "Gajakesari Yoga",
        "description": "Moon and Jupiter in kendras from each other",
        "strength": "strong",
        "effects": "Wisdom, prosperity, fame"
      }
      // ... other yogas
    ],
    "dashas": {
      "mahadasha": {
        "planet": "Venus",
        "start": "2018-06-15",
        "end": "2038-06-15"
      },
      "antardasha": {
        "planet": "Sun",
        "start": "2025-06-15",
        "end": "2026-04-13"
      }
    }
  }
}

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 /v1/divisional-chart/d9

{
  "date": "1990-06-15",
  "time": "14:30",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "timezone": 5.5
}

Dasha Periods

Vimshottari Dasha Duration

Response Example

{
  "status": "success",
  "data": {
    "current_mahadasha": {
      "planet": "Venus",
      "start": "2018-06-15",
      "end": "2038-06-15",
      "duration_years": 20
    },
    "current_antardasha": {
      "planet": "Sun",
      "start": "2025-06-15",
      "end": "2026-04-13",
      "duration_months": 10
    },
    "current_pratyantardasha": {
      "planet": "Moon",
      "start": "2025-12-20",
      "end": "2026-01-05"
    },
    "complete_sequence": [
      {
        "mahadasha": "Ketu",
        "start": "1990-06-15",
        "end": "1997-06-15",
        "antardashas": [...]
      }
      // ... 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

{
  "status": "success",
  "data": {
    "total_yogas": 12,
    "yogas": [
      {
        "name": "Gajakesari Yoga",
        "category": "beneficial",
        "strength": "strong",
        "planets_involved": ["Moon", "Jupiter"],
        "houses_involved": [1, 7],
        "description": "Moon and Jupiter in kendras from each other",
        "effects": "Wisdom, prosperity, eloquence, fame, virtue",
        "interpretation": "You possess natural wisdom and will gain respect in society. This yoga brings prosperity through knowledge."
      },
      {
        "name": "Hamsa Yoga",
        "category": "mahapurusha",
        "strength": "moderate",
        "planets_involved": ["Jupiter"],
        "houses_involved": [1],
        "description": "Jupiter in kendra in own/exaltation sign",
        "effects": "Righteous, learned, wealthy, spiritual",
        "interpretation": "You have strong moral values and will be respected for wisdom."
      }
    ]
  }
}

Kundali Matching

Eight Kootas (Gunas)

Request Example

{
  "person1": {
    "date": "1990-06-15",
    "time": "14:30",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": 5.5
  },
  "person2": {
    "date": "1992-03-20",
    "time": "10:15",
    "latitude": 19.0760,
    "longitude": 72.8777,
    "timezone": 5.5
  }
}

Response Example

{
  "status": "success",
  "data": {
    "total_points": 28.5,
    "max_points": 36,
    "match_percentage": 79.2,
    "conclusion": "Excellent Match",
    "recommendation": "Marriage is highly recommended",
    "gunas": [
      {
        "name": "Varna",
        "score": 1,
        "max": 1,
        "description": "Spiritual compatibility is perfect"
      },
      {
        "name": "Vashya",
        "score": 2,
        "max": 2,
        "description": "Strong mutual attraction"
      },
      {
        "name": "Tara",
        "score": 1.5,
        "max": 3,
        "description": "Good birth star compatibility"
      }
      // ... remaining gunas
    ],
    "doshas": {
      "mangal_dosha": {
        "person1": false,
        "person2": true,
        "cancellation": "Yes - Both have Mars in 7th house"
      }
    }
  }
}

Complete Code Examples

Python Example

import requests
import os
from datetime import datetime

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

    def get_birth_chart(self, birth_data):
        """Get complete birth chart"""
        endpoint = f"{self.base_url}/birth-chart"
        response = requests.post(endpoint, json=birth_data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_dashas(self, birth_data):
        """Get Vimshottari dasha periods"""
        endpoint = f"{self.base_url}/dasha/vimshottari"
        response = requests.post(endpoint, json=birth_data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def match_kundali(self, person1, person2):
        """Match two kundalis"""
        endpoint = f"{self.base_url}/kundali-matching"
        data = {"person1": person1, "person2": person2}
        response = requests.post(endpoint, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

# Usage
api = VedikaAPI(os.getenv("VEDIKA_API_KEY"))

birth_data = {
    "date": "1990-06-15",
    "time": "14:30",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": 5.5,
    "ayanamsa": "lahiri"
}

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

# Get active yogas
if chart['data']['yogas']:
    print(f"\nActive Yogas: {len(chart['data']['yogas'])}")
    for yoga in chart['data']['yogas'][:3]:
        print(f"- {yoga['name']}: {yoga['description']}")

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

JavaScript (Node.js) Example

const axios = require('axios');

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

    async getBirthChart(birthData) {
        try {
            const response = await axios.post(
                `${this.baseURL}/birth-chart`,
                birthData,
                { headers: this.headers }
            );
            return response.data;
        } catch (error) {
            throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
        }
    }

    async getDivisionalChart(varga, birthData) {
        const response = await axios.post(
            `${this.baseURL}/divisional-chart/${varga}`,
            birthData,
            { headers: this.headers }
        );
        return response.data;
    }

    async getYogas(birthData) {
        const response = await axios.post(
            `${this.baseURL}/yogas`,
            birthData,
            { headers: this.headers }
        );
        return response.data;
    }
}

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

const birthData = {
    date: '1990-06-15',
    time: '14:30',
    latitude: 28.6139,
    longitude: 77.2090,
    timezone: 5.5
};

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

    // Get Navamsa chart
    const navamsa = await api.getDivisionalChart('d9', birthData);
    console.log('\nNavamsa Chart:');
    console.log(`Ascendant: ${navamsa.data.ascendant.sign}`);

    // Get yogas
    const yogas = await api.getYogas(birthData);
    console.log(`\nActive Yogas: ${yogas.data.total_yogas}`);
    yogas.data.yogas.forEach(yoga => {
        console.log(`- ${yoga.name} (${yoga.strength})`);
    });
})();

PHP Example

<?php

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

    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('/birth-chart', $birthData);
    }

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

    public function matchKundali($person1, $person2) {
        return $this->makeRequest('/kundali-matching', [
            'person1' => $person1,
            'person2' => $person2
        ]);
    }
}

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

$birthData = [
    'date' => '1990-06-15',
    'time' => '14:30',
    'latitude' => 28.6139,
    'longitude' => 77.2090,
    'timezone' => 5.5
];

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

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

    echo "Sun: " . $chart['data']['planets']['sun']['sign'] . "\n";
    echo "Moon: " . $chart['data']['planets']['moon']['sign'] . "\n";
    echo "Ascendant: " . $chart['data']['ascendant']['sign'] . "\n\n";

    // Display yogas
    if (!empty($chart['data']['yogas'])) {
        echo "Active Yogas:\n";
        foreach ($chart['data']['yogas'] as $yoga) {
            echo "- " . $yoga['name'] . ": " . $yoga['description'] . "\n";
        }
    }

    // Get dashas
    $dashas = $api->getDashas($birthData);
    echo "\nCurrent Dasha Periods:\n";
    echo "Mahadasha: " . $dashas['data']['current_mahadasha']['planet'] . "\n";
    echo "Antardasha: " . $dashas['data']['current_antardasha']['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: 1,000 calls/month, Pro: 10,000, Business: 50,000
• 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