Kundli API Complete Guide for Indian Astrology App Developers

# Get your API key from https://roxyapi.com/pricing
export VEDIC_API_KEY="your_api_key_here"

# Test authentication
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/birth-chart \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VEDIC_API_KEY" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": 5.5
  }'

// Time is a string in HH:MM:SS format
const birthTime = "14:30:00"; // 2:30 PM
const morningTime = "09:15:00"; // 9:15 AM
const nightTime = "23:45:00"; // 11:45 PM

POST /birth-chart

{
  "date": "1990-07-15",
  "time": "14:30:00",
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": 5.5
}

{
  "aries": {
    "rashi": "aries",
    "signs": [
      {
        "graha": "Mars",
        "longitude": 8.15,
        "nakshatra": { "name": "Ashwini", "pada": 3, "key": 1 },
        "isRetrograde": false
      }
    ]
  },
  "gemini": {
    "rashi": "gemini",
    "signs": [
      {
        "graha": "Sun",
        "longitude": 88.92,
        "nakshatra": { "name": "Punarvasu", "pada": 3, "key": 7 },
        "isRetrograde": false
      }
    ]
  },
  "meta": {
    "Lagna": {
      "graha": "Lagna",
      "rashi": "Aquarius",
      "longitude": 301.46,
      "nakshatra": { "name": "Dhanishta", "pada": 3, "key": 23 },
      "isRetrograde": false
    },
    "Sun": {
      "graha": "Sun",
      "rashi": "Gemini",
      "longitude": 88.92,
      "nakshatra": { "name": "Punarvasu", "pada": 3, "key": 7 },
      "isRetrograde": false
    },
    "Moon": {
      "graha": "Moon",
      "rashi": "Pisces",
      "longitude": 357.79,
      "nakshatra": { "name": "Revati", "pada": 4, "key": 27 },
      "isRetrograde": false
    }
  },
  "houses": [
    { "number": 1, "name": "Lagna", "description": "Self, personality, physical body, general health" },
    { "number": 2, "name": "Dhana", "description": "Wealth, family, speech, food, early education" }
  ]
}

interface BirthChartResponse {
  [rashiKey: string]: {
    rashi: string;
    signs: Array<{
      graha: string;
      longitude: number;
      nakshatra: { name: string; pada: number; key: number };
      isRetrograde: boolean;
    }>;
  };
  meta: {
    [grahaName: string]: {
      graha: string;
      rashi: string;
      longitude: number;
      nakshatra: { name: string; pada: number; key: number };
      isRetrograde: boolean;
    };
  };
  houses: Array<{
    number: number;
    name: string;
    description: string;
  }>;
}

POST /navamsa

{
  "rashis": {
    "aries": {
      "rashi": "Aries",
      "planets": ["Sun", "Mars"]
    },
    "taurus": {
      "rashi": "Taurus",
      "planets": ["Lagna", "Venus"]
    }
  },
  "meta": {
    "Lagna": {
      "graha": "Lagna",
      "rashi": "Taurus",
      "longitude": 45.23,
      "navamsaLord": "Venus"
    },
    "Sun": {
      "graha": "Sun",
      "rashi": "Aries",
      "longitude": 15.67,
      "navamsaLord": "Mars"
    }
  }
}

async function getCompleteCharts(birthData: BirthData) {
  const [birthChart, navamsa] = await Promise.all([
    api.getBirthChart(birthData),
    api.getNavamsa(birthData),
  ]);

  return {
    d1: birthChart,
    d9: navamsa,
  };
}

POST /divisional-chart

{
  "date": "1990-07-15",
  "time": "14:30:00",
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": 5.5,
  "division": 10
}

async function analyzeCareer(birthData: BirthData) {
  // D1 for overall indications
  const d1 = await api.getBirthChart(birthData);
  
  // D10 for detailed career analysis
  const d10 = await api.getDivisionalChart(birthData, 10);
  
  // D24 for education and skills
  const d24 = await api.getDivisionalChart(birthData, 24);
  
  return {
    overallChart: d1,
    careerChart: d10,
    educationChart: d24,
    analysis: generateCareerAnalysis(d1, d10, d24),
  };
}

POST /shadbala

{
  "planets": [
    {
      "planet": "Sun",
      "sthanaBala": 168.4,
      "digBala": 6.43,
      "kalaBala": 116.58,
      "chestaBala": 26.06,
      "naisargikaBala": 60.0,
      "drikBala": 6.98,
      "totalVirupas": 384.45,
      "totalRupas": 6.41,
      "minRequired": 5.0,
      "strengthRatio": 1.28,
      "ishtaPhala": 34.11,
      "kashtaPhala": 22.83,
      "relativeRank": 2
    }
  ]
}

function interpretStrength(rupas: number): string {
  if (rupas >= 5.0) return 'Very Strong - Excellent results';
  if (rupas >= 4.0) return 'Strong - Good results';
  if (rupas >= 3.0) return 'Moderate - Average results';
  if (rupas >= 2.0) return 'Weak - Limited results';
  return 'Very Weak - Challenges expected';
}

GET /yoga

{
  "yogas": [
    { "id": "gajakesari", "name": "Gajakesari Yoga" },
    { "id": "neecha-bhanga-raja", "name": "Neecha Bhanga Raja Yoga" },
    { "id": "vipareeta-raja", "name": "Vipareeta Raja Yoga" }
  ],
  "total": 300
}

GET /yoga/{id}

{
  "id": "gajakesari",
  "name": "Gajakesari Yoga",
  "description": "Jupiter in kendra from Moon",
  "result": "Gajakesari Yoga is one of the most powerful yogas. You will be eloquent, wealthy...",
  "quality": "Positive"
}

async function browseYogas() {
  // List all available yogas
  const list = await api.listYogas(); // GET /yoga

  // Get details for a specific yoga
  const details = await api.getYoga('gajakesari'); // GET /yoga/gajakesari

  return {
    totalYogas: list.total,
    yogaList: list.yogas,
    selectedYoga: details,
  };
}

POST /panchang/basic

{
  "date": "2026-01-09",
  "time": "14:30:00",
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": 5.5
}

{
  "tithi": {
    "number": 2,
    "name": "Dvītiyā",
    "paksha": "Shukla Paksha",
    "completion": 38.94,
    "deity": "Vidhāṭṛ",
    "element": "Earth",
    "characteristics": "Good for agriculture, ceremonies",
    "auspicious": true
  },
  "nakshatra": {
    "number": 8,
    "name": "Pushya",
    "lord": "Saturn",
    "deity": "Brihaspati",
    "symbol": "Cows Udder",
    "characteristics": "Most auspicious, nurturing, disciplined",
    "auspicious": true
  },
  "yoga": {
    "number": 15,
    "name": "Vajra",
    "completion": 58.91,
    "characteristics": "Powerful, forceful, creates obstacles",
    "auspicious": false
  },
  "karana": {
    "number": 3,
    "name": "Kaulav",
    "type": "char",
    "completion": 77.88,
    "characteristics": "Friendly, caring, loving",
    "auspicious": true
  },
  "sunLongitude": 88.924,
  "moonLongitude": 105.597,
  "sunrise": "07:15:23",
  "sunset": "17:42:18",
  "moonrise": "09:32:45",
  "moonset": "20:18:12"
}

function findAuspiciousMuhurat(panchang: PanchangResponse): boolean {
  const { tithi, nakshatra, yoga, karana } = panchang;
  
  // Check all factors
  const isAuspicious = 
    tithi.auspicious &&
    nakshatra.auspicious &&
    !yoga.characteristics.includes('obstacles') &&
    karana.auspicious;
  
  return isAuspicious;
}

POST /dasha/current

{
  "birthMoonNakshatra": {
    "name": "Ashwini",
    "lord": "Ketu"
  },
  "mahadasha": {
    "planet": "Moon",
    "startDate": "2023-01-15T00:00:00Z",
    "endDate": "2033-01-15T00:00:00Z",
    "durationYears": 10,
    "remainingYears": 6,
    "remainingMonths": 11,
    "remainingDays": 24
  },
  "antardasha": {
    "planet": "Jupiter",
    "startDate": "2025-12-15T00:00:00Z",
    "endDate": "2027-04-15T00:00:00Z",
    "durationYears": 1.33
  },
  "pratyantardasha": {
    "planet": "Jupiter",
    "startDate": "2025-12-15T00:00:00Z",
    "endDate": "2026-02-20T00:00:00Z",
    "durationYears": 0.178
  }
}

POST /dasha/major

POST /dasha/sub/{mahadasha}

POST /compatibility

{
  "person1": {
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": 5.5
  },
  "person2": {
    "date": "1992-03-20",
    "time": "10:00:00",
    "latitude": 19.076,
    "longitude": 72.8777,
    "timezone": 5.5
  }
}

{
  "total": 18.5,
  "maxScore": 36,
  "percentage": 51.39,
  "isCompatible": true,
  "breakdown": [
    {
      "category": "Nadi",
      "score": 8,
      "maxScore": 8,
      "description": "Health and progeny compatibility"
    },
    {
      "category": "Bhakoot",
      "score": 5,
      "maxScore": 7,
      "description": "Love and prosperity"
    },
    {
      "category": "Gana",
      "score": 0,
      "maxScore": 6,
      "description": "Temperament match"
    }
  ],
  "recommendation": "Average compatibility. Consider consulting astrologer for detailed analysis."
}

function getCompatibilityRating(percentage: number): string {
  if (percentage >= 80) return 'Excellent Match';
  if (percentage >= 70) return 'Very Good Match';
  if (percentage >= 60) return 'Good Match';
  if (percentage >= 50) return 'Average Match';
  if (percentage >= 40) return 'Below Average';
  return 'Not Recommended';
}

POST /dosha/manglik

{
  "present": true,
  "severity": "Moderate",
  "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.",
  "exceptions": ["Mars aspected by Jupiter (reduces severity)"],
  "remedies": [
    "Chant Hanuman Chalisa daily",
    "Visit Hanuman temple on Tuesdays",
    "Perform Mangal Shanti puja",
    "Kumbh Vivah ritual before marriage"
  ],
  "effects": {
    "marriage": "Delays in marriage, marital discord, separation, or multiple marriages",
    "personality": "Aggressive behavior, impatience, dominance, short temper",
    "timing": "Effects significantly reduce after age 28 (Mars maturity age)",
    "relationships": "Conflicts with spouse, power struggles, lack of harmony"
  }
}

POST /dosha/kalsarpa

{
  "present": true,
  "severity": "Severe",
  "type": "Ananta Kalsarpa",
  "description": "Ananta Kalsarpa Dosha present. All planets hemmed between Rahu (house 1) and Ketu.",
  "remedies": [
    "Perform Kaal Sarp Dosh Puja at Trimbakeshwar or Ujjain",
    "Chant Mahamrityunjaya Mantra daily",
    "Donate to snake sanctuaries"
  ],
  "effects": {
    "duration": "Effects active during Rahu and Ketu Mahadasha/Antardasha periods",
    "career": "Obstacles in progress, sudden setbacks, delayed success",
    "health": "Chronic health issues, accidents, mental stress",
    "relationships": "Family disputes, separation from loved ones",
    "mindset": "Anxiety, fear, nightmares, psychological struggles",
    "positive": "Can bring spiritual inclination and inner strength when managed well"
  }
}

POST /dosha/sadhesati

POST /kp/chart

{
  "cusps": [
    {
      "house": 1,
      "degree": 301.46,
      "rashi": "Aquarius",
      "lord": "Saturn",
      "subLord": "Mercury",
      "subSubLord": "Venus"
    }
  ],
  "planets": {
    "Sun": {
      "degree": 88.92,
      "rashi": "Gemini",
      "nakshatra": "Punarvasu",
      "lord": "Mercury",
      "subLord": "Venus",
      "subSubLord": "Mars",
      "significators": [3, 5, 10]
    }
  },
  "ruling": {
    "planets": ["Moon", "Jupiter", "Venus"],
    "signs": ["Gemini", "Sagittarius"],
    "stars": ["Punarvasu", "Uttara Ashadha"]
  }
}

// services/vedic-api-service.ts
export class VedicAstrologyService {
  private apiKey: string;
  private baseURL: string;
  private cache: Map<string, any>;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
    this.baseURL = 'https://roxyapi.com/api/v2/vedic-astrology';
    this.cache = new Map();
  }

  async getCompleteKundli(birthData: BirthData) {
    const cacheKey = `kundli:${JSON.stringify(birthData)}`;
    
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey);
    }

    // Fetch all data in parallel
    const [
      birthChart,
      navamsa,
      yogas,
      strengths,
      currentDasha,
      panchang,
      manglikDosha,
      kalsarpaDosha,
    ] = await Promise.all([
      this.getBirthChart(birthData),
      this.getNavamsa(birthData),
      this.getShadbala(birthData),
      this.getCurrentDasha(birthData),
      this.getPanchang(birthData),
      this.getManglikDosha(birthData),
      this.getKalsarpaDosha(birthData),
    ]);

    const kundli = {
      birthChart,
      navamsa,
      shadbala,
      currentDasha,
      panchang,
      doshas: {
        manglik: manglikDosha,
        kalsarpa: kalsarpaDosha,
      },
      generatedAt: new Date().toISOString(),
    };

    // Cache for 1 year (birth charts never change)
    this.cache.set(cacheKey, kundli);

    return kundli;
  }

  async getMatchingAnalysis(
    person1: BirthData,
    person2: BirthData
  ) {
    const [
      compatibility,
      person1Kundli,
      person2Kundli,
    ] = await Promise.all([
      this.getCompatibility(person1, person2),
      this.getCompleteKundli(person1),
      this.getCompleteKundli(person2),
    ]);

    return {
      compatibility,
      person1: {
        chart: person1Kundli.birthChart,
        doshas: person1Kundli.doshas,
      },
      person2: {
        chart: person2Kundli.birthChart,
        doshas: person2Kundli.doshas,
      },
      recommendation: this.generateMatchingRecommendation(
        compatibility,
        person1Kundli,
        person2Kundli
      ),
    };
  }

  private async request<T>(
    endpoint: string,
    data: any
  ): Promise<T> {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey,
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(error.message || `API error: ${response.statusText}`);
    }

    return response.json();
  }

  // Individual endpoint methods
  getBirthChart(data: BirthData) {
    return this.request('/birth-chart', data);
  }

  getNavamsa(data: BirthData) {
    return this.request('/navamsa', data);
  }

  getDivisionalChart(data: BirthData, division: number) {
    return this.request('/divisional-chart', { ...data, division });
  }

  listYogas() {
    return this.request('/yoga', undefined);
  }

  getShadbala(data: BirthData) {
    return this.request('/shadbala', data);
  }

  getPanchang(data: BirthData) {
    return this.request('/panchang/basic', data);
  }

  getCurrentDasha(data: BirthData) {
    return this.request('/dasha/current', data);
  }

  getMajorDashas(data: BirthData) {
    return this.request('/dasha/major', data);
  }

  getCompatibility(person1: BirthData, person2: BirthData) {
    return this.request('/compatibility', { person1, person2 });
  }

  getManglikDosha(data: BirthData) {
    return this.request('/dosha/manglik', data);
  }

  getKalsarpaDosha(data: BirthData) {
    return this.request('/dosha/kalsarpa', data);
  }

  getSadhesati(data: BirthData) {
    return this.request('/dosha/sadhesati', data);
  }

  getKPChart(data: BirthData) {
    return this.request('/kp/chart', data);
  }

  private generateMatchingRecommendation(
    compatibility: any,
    p1: any,
    p2: any
  ): string {
    const score = compatibility.percentage;
    
    if (score >= 80) {
      return 'Excellent match! Proceed with confidence.';
    }
    
    if (score >= 70) {
      return 'Very good compatibility. Minor adjustments recommended.';
    }
    
    if (score >= 60) {
      return 'Good match with some areas needing attention.';
    }
    
    // Check dosha cancellations
    const bothManglik = p1.doshas.manglik.present && p2.doshas.manglik.present;
    if (bothManglik && score >= 50) {
      return 'Average compatibility but Manglik dosha is cancelled. Consult astrologer.';
    }
    
    if (score >= 50) {
      return 'Average compatibility. Detailed consultation recommended.';
    }
    
    return 'Below average compatibility. Thorough astrological consultation strongly advised.';
  }
}

class VedicAPIError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public details?: any
  ) {
    super(message);
    this.name = 'VedicAPIError';
  }
}

async function safeAPICall<T>(
  apiCall: () => Promise<T>,
  fallback: T
): Promise<T> {
  try {
    return await apiCall();
  } catch (error) {
    if (error instanceof VedicAPIError) {
      console.error(`API Error ${error.statusCode}:`, error.message);
      
      // Handle specific errors
      if (error.statusCode === 429) {
        throw new Error('Rate limit exceeded. Please upgrade your plan.');
      }
      
      if (error.statusCode === 401) {
        throw new Error('Invalid API key. Please check your credentials.');
      }
    }
    
    return fallback;
  }
}

class RateLimiter {
  private queue: Array<() => Promise<any>> = [];
  private processing = false;
  private requestsPerSecond: number;

  constructor(requestsPerSecond: number = 10) {
    this.requestsPerSecond = requestsPerSecond;
  }

  async enqueue<T>(request: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push(async () => {
        try {
          const result = await request();
          resolve(result);
        } catch (error) {
          reject(error);
        }
      });

      this.processQueue();
    });
  }

  private async processQueue() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      const request = this.queue.shift();
      if (request) {
        await request();
        await new Promise(resolve =>
          setTimeout(resolve, 1000 / this.requestsPerSecond)
        );
      }
    }

    this.processing = false;
  }
}

// Usage
const limiter = new RateLimiter(10); // 10 requests per second

const result = await limiter.enqueue(() =>
  api.getBirthChart(birthData)
);

import { createClient } from 'redis';

class APICache {
  private redis: ReturnType<typeof createClient>;

  constructor(redisURL: string) {
    this.redis = createClient({ url: redisURL });
    this.redis.connect();
  }

  async get<T>(key: string): Promise<T | null> {
    const cached = await this.redis.get(key);
    return cached ? JSON.parse(cached) : null;
  }

  async set(key: string, value: any, ttl: number): Promise<void> {
    await this.redis.set(key, JSON.stringify(value), { EX: ttl });
  }

  getCacheKey(endpoint: string, params: any): string {
    return `vedic:${endpoint}:${JSON.stringify(params)}`;
  }
}

// TTL recommendations
const CACHE_TTL = {
  birthChart: 86400 * 365,     // 1 year (never changes)
  navamsa: 86400 * 365,        // 1 year
  yogas: 86400 * 365,          // 1 year
  panchang: 86400,             // 1 day (changes daily)
  currentDasha: 86400 * 7,     // 1 week (updates weekly)
  compatibility: 86400 * 30,   // 30 days
};

// ❌ Wrong
const time = 14.5; // Decimal number won't work

// ✅ Correct
const time = "14:30:00"; // String in HH:MM:SS format

// ❌ Wrong - missing timezone
const birthData = {
  date: "1990-07-15",
  time: "14:30:00",
  latitude: 28.6139,
  longitude: 77.209,
  // Missing timezone - defaults to 5.5 IST
};

// ✅ Correct - explicit timezone offset
const birthData = {
  date: "1990-07-15",
  time: "14:30:00",
  latitude: 28.6139,
  longitude: 77.209,
  timezone: 5.5, // IST. Use -5 for EST, 0 for UTC
};

// ❌ Wrong - fetching birth chart every time
async function displayChart(userId: string) {
  const user = await db.users.findById(userId);
  const chart = await api.getBirthChart(user.birthData); // Repeated API call
  return chart;
}

// ✅ Correct - cache once, use forever
async function displayChart(userId: string) {
  const cacheKey = `chart:${userId}`;
  let chart = await cache.get(cacheKey);
  
  if (!chart) {
    const user = await db.users.findById(userId);
    chart = await api.getBirthChart(user.birthData);
    await cache.set(cacheKey, chart, 86400 * 365); // 1 year
  }
  
  return chart;
}