RoxyAPI

Menu

Kundli API Complete Guide for Indian Astrology App Developers

•
17 min read
•By Priya Sharma
Vedic AstrologyKundli APIJanam KundaliAPI ReferenceIndian Astrology

Comprehensive API reference for Vedic astrology features. Birth charts, divisional charts, planetary strengths, yogas detection, and more for building professional kundli apps.

Kundli API Complete Guide for Indian Astrology App Developers

Building a professional Vedic astrology application requires access to accurate astronomical calculations, comprehensive astrological interpretations, and reliable API infrastructure. This complete guide walks you through every endpoint in the RoxyAPI Vedic Astrology API, showing you exactly how to build feature-rich kundli applications that users love.

Whether you are building a matrimonial platform, spiritual wellness app, or professional astrology software, this reference covers everything from basic birth charts to advanced divisional chart analysis.

API Overview

Base URL: https://roxyapi.com/api/v2/vedic-astrology
Authentication: API key in X-API-Key header
Format: JSON requests and responses
Rate Limits: Based on your subscription plan

Quick Start

# 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 '{
    "year": 1990,
    "month": 7,
    "day": 15,
    "hour": 14.5,
    "latitude": 28.6139,
    "longitude": 77.209
  }'

Common Parameters

All endpoints requiring birth data accept these parameters:

Parameter Type Range Description
year integer 1900-2100 Birth year
month integer 1-12 Birth month
day integer 1-31 Birth day
hour float 0-23.99 Birth time in 24-hour format with decimals (14.5 = 14:30)
latitude float -90 to 90 Birth location latitude
longitude float -180 to 180 Birth location longitude
timezone float -12 to 14 Optional: timezone offset (defaults to location)

Time Format Examples

// Convert HH:MM to decimal hour
function timeToHour(hours, minutes) {
  return hours + (minutes / 60);
}

timeToHour(14, 30); // 14.5
timeToHour(9, 15);  // 9.25
timeToHour(23, 45); // 23.75

1. Birth Chart API (D1 Rashi Chart)

The foundation of all Vedic astrology calculations. Returns complete planetary positions, nakshatras, and house placements.

Endpoint

POST /birth-chart

Request

{
  "year": 1990,
  "month": 7,
  "day": 15,
  "hour": 14.5,
  "latitude": 28.6139,
  "longitude": 77.209
}

Response Structure

{
  "rashis": {
    "aries": {
      "rashi": "Aries",
      "planets": ["Mars"]
    },
    "gemini": {
      "rashi": "Gemini",
      "planets": ["Sun", "Jupiter", "Venus"]
    },
    "aquarius": {
      "rashi": "Aquarius",
      "planets": ["Lagna", "Ketu"]
    }
  },
  "meta": {
    "Lagna": {
      "graha": "Lagna",
      "rashi": "Aquarius",
      "longitude": 301.46,
      "nakshatra": {
        "name": "Dhanishta",
        "pada": 3,
        "key": "dhanishta",
        "ratio": 0.543
      },
      "isRetrograde": false
    },
    "Sun": {
      "graha": "Sun",
      "rashi": "Gemini",
      "longitude": 88.92,
      "nakshatra": {
        "name": "Punarvasu",
        "pada": 3,
        "key": "punarvasu",
        "ratio": 0.218
      },
      "isRetrograde": false
    },
    "Moon": {
      "graha": "Moon",
      "rashi": "Pisces",
      "longitude": 357.79,
      "nakshatra": {
        "name": "Revati",
        "pada": 4,
        "key": "revati",
        "ratio": 0.947
      },
      "isRetrograde": true
    }
  },
  "houses": [
    {
      "house": 1,
      "rashi": "Aquarius",
      "lord": "Saturn",
      "description": "Self, personality, physical body, general health"
    },
    {
      "house": 2,
      "rashi": "Pisces",
      "lord": "Jupiter",
      "description": "Wealth, family, speech, food, early education"
    }
  ]
}

TypeScript Types

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

Use Cases

  • Display D1 chart with planetary placements
  • Calculate aspects between planets
  • Determine planetary strengths by house and sign
  • Generate birth chart PDF reports
  • Analyze yogas and doshas

2. Navamsa Chart API (D9)

The most important divisional chart for marriage and spiritual matters.

Endpoint

POST /navamsa

Request

Same birth data parameters as birth chart.

Response

{
  "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"
    }
  }
}

Integration Example

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

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

3. Divisional Charts API (D1-D60)

Access all Varga charts for specialized analysis.

Endpoint

POST /divisional-chart

Request

{
  "year": 1990,
  "month": 7,
  "day": 15,
  "hour": 14.5,
  "latitude": 28.6139,
  "longitude": 77.209,
  "division": 10
}

Available Divisions

Division Name Signification
D1 Rashi Overall life, personality
D2 Hora Wealth
D3 Drekkana Siblings, courage
D4 Chaturthamsa Property, fortune
D7 Saptamsa Children, grandchildren
D9 Navamsa Marriage, dharma
D10 Dasamsa Career, profession
D12 Dwadasamsa Parents
D16 Shodasamsa Vehicles, happiness
D20 Vimsamsa Spiritual pursuits
D24 Chaturvimsamsa Education, learning
D27 Bhamsa Strengths, weaknesses
D30 Trimsamsa Evils, misfortunes
D40 Khavedamsa Auspicious/inauspicious effects
D45 Akshavedamsa General indications
D60 Shashtiamsa Overall karma

Example: Career Analysis

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),
  };
}

4. Planetary Strengths API

Calculate Shadbala (six-fold strength) and other strength metrics.

Endpoint

POST /planetary-strengths

Response

{
  "shadbala": {
    "Sun": {
      "sthanabal": 45.5,
      "digbala": 60.0,
      "kalabala": 30.2,
      "chestabala": 15.0,
      "naisargikabala": 60.0,
      "drikbala": 20.5,
      "total": 231.2,
      "totalRupas": 3.85,
      "strength": "strong"
    },
    "Moon": {
      "total": 180.4,
      "totalRupas": 3.01,
      "strength": "moderate"
    }
  },
  "vimshopakaBala": {
    "Sun": 15.5,
    "Moon": 12.8
  },
  "aspects": [
    {
      "from": "Jupiter",
      "to": "Moon",
      "aspectType": "full",
      "strength": 75
    }
  ]
}

Strength Interpretation

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';
}

5. Planetary Yogas API

Detect over 300 classical yogas automatically.

Endpoint

POST /yogas

Response

{
  "yogas": [
    {
      "name": "Gajakesari Yoga",
      "category": "Raj Yoga",
      "planets": ["Jupiter", "Moon"],
      "houses": [1, 4],
      "strength": "strong",
      "description": "Jupiter and Moon in mutual kendras create wealth, wisdom, and fame.",
      "effects": [
        "High intelligence and wisdom",
        "Wealth and prosperity",
        "Good reputation and respect",
        "Success in education"
      ],
      "active": true,
      "activeFrom": "2025-01-15",
      "activeTo": "2035-01-15"
    },
    {
      "name": "Neecha Bhanga Raja Yoga",
      "category": "Cancellation",
      "planets": ["Saturn"],
      "description": "Debilitated planet whose debilitation is cancelled, creating unexpected success.",
      "strength": "moderate",
      "active": true
    },
    {
      "name": "Vipareeta Raja Yoga",
      "category": "Reversal",
      "houses": [6, 8, 12],
      "description": "Lords of dusthana houses in dusthanas create success through adversity.",
      "strength": "weak",
      "active": false
    }
  ],
  "summary": {
    "totalYogas": 18,
    "rajYogas": 3,
    "dhanaYogas": 5,
    "activeYogas": 12
  }
}

Major Yoga Categories

  1. Raj Yogas - Power and authority
  2. Dhana Yogas - Wealth and prosperity
  3. Mahapurusha Yogas - Great personality traits
  4. Neecha Bhanga - Debilitation cancellations
  5. Vipareeta Raja - Success through reversals
  6. Parivartan Yogas - House exchange benefits

Implementation

async function analyzeYogas(birthData: BirthData) {
  const yogas = await api.getYogas(birthData);
  
  // Filter by category
  const rajYogas = yogas.yogas.filter(y => y.category === 'Raj Yoga');
  const dhanaYogas = yogas.yogas.filter(y => y.category === 'Dhana Yoga');
  
  // Get only active yogas
  const activeYogas = yogas.yogas.filter(y => y.active);
  
  return {
    powerYogas: rajYogas,
    wealthYogas: dhanaYogas,
    currentlyActive: activeYogas,
  };
}

6. Panchang API

Daily Vedic calendar with Tithi, Nakshatra, Yoga, Karana.

Endpoint

POST /panchang/basic

Request

{
  "year": 2026,
  "month": 1,
  "day": 9,
  "hour": 14.5,
  "latitude": 28.6139,
  "longitude": 77.209
}

Response

{
  "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"
}

Muhurat Selection

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;
}

7. Dasha Systems API

Current Dasha

POST /dasha/current

Response

{
  "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
  }
}

Complete Timeline

POST /dasha/complete

Returns all 9 Mahadashas spanning 120 years.

Antardasha List

POST /dasha/antardashas

Get all 9 Antardashas for a specific Mahadasha.

8. Compatibility API (Ashtakoot)

Gun milan scoring for marriage matching.

Endpoint

POST /compatibility

Request

{
  "person1": {
    "year": 1990,
    "month": 7,
    "day": 15,
    "hour": 14.5,
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "person2": {
    "year": 1992,
    "month": 3,
    "day": 20,
    "hour": 10.0,
    "latitude": 19.076,
    "longitude": 72.8777
  }
}

Response

{
  "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."
}

Compatibility Thresholds

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';
}

9. Dosha Detection APIs

Manglik Dosha

POST /dosha/manglik

Response

{
  "isManglik": true,
  "severity": "Moderate",
  "affectedHouses": [1, 4, 7, 8, 12],
  "marsPosition": {
    "house": 7,
    "rashi": "Leo",
    "strength": "strong"
  },
  "interpretation": "Mars in 7th house creates Manglik dosha affecting marriage. Recommended to marry another Manglik or after age 28.",
  "remedies": [
    "Perform Mangal Shanti puja",
    "Donate red lentils on Tuesdays",
    "Wear red coral after consultation",
    "Kumbh Vivah ritual before marriage"
  ],
  "cancellations": []
}

Kalsarpa Dosha

POST /dosha/kalsarpa

Response

{
  "hasKalsarpaDosha": true,
  "type": "Anant Kalsarpa Yoga",
  "severity": "Full",
  "rahuPosition": {
    "house": 1,
    "rashi": "Aries"
  },
  "ketuPosition": {
    "house": 7,
    "rashi": "Libra"
  },
  "interpretation": "All planets between Rahu and Ketu axis. Creates obstacles but also spiritual inclination.",
  "remedies": [
    "Visit Trimbakeshwar temple",
    "Perform Rahu-Ketu Shanti puja",
    "Donate to snake sanctuaries",
    "Chant Rahu-Ketu mantras"
  ],
  "positiveEffects": [
    "Strong spiritual inclinations",
    "Ability to overcome obstacles",
    "Success after struggles"
  ]
}

Sadhesati

POST /dosha/sadhesati

Detect Saturn's 7.5 year transit period.

10. KP Astrology Endpoints

Krishnamurti Paddhati system for precise predictions.

KP Birth Chart

POST /kp/birth-chart

Response

{
  "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"]
  }
}

Complete Integration Example

Here is a production-ready service class integrating all endpoints:

// 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.getYogas(birthData),
      this.getPlanetaryStrengths(birthData),
      this.getCurrentDasha(birthData),
      this.getPanchang(birthData),
      this.getManglikDosha(birthData),
      this.getKalsarpaDosha(birthData),
    ]);

    const kundli = {
      birthChart,
      navamsa,
      yogas,
      strengths,
      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,
        yogas: person1Kundli.yogas.yogas.filter(y => y.active),
      },
      person2: {
        chart: person2Kundli.birthChart,
        doshas: person2Kundli.doshas,
        yogas: person2Kundli.yogas.yogas.filter(y => y.active),
      },
      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 });
  }

  getYogas(data: BirthData) {
    return this.request('/yogas', data);
  }

  getPlanetaryStrengths(data: BirthData) {
    return this.request('/planetary-strengths', data);
  }

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

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

  getCompleteDashaTimeline(data: BirthData) {
    return this.request('/dasha/complete', 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);
  }

  getKPBirthChart(data: BirthData) {
    return this.request('/kp/birth-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.isManglik && p2.doshas.manglik.isManglik;
    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.';
  }
}

Error Handling

Implement comprehensive error handling:

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;
  }
}

Rate Limiting Best Practices

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)
);

Caching Strategy

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
};

Production Deployment Checklist

  • Store API key in environment variables (never commit)
  • Implement Redis caching for static data (birth charts, yogas)
  • Add rate limiting to prevent quota exhaustion
  • Set up error monitoring (Sentry, Rollbar)
  • Log API usage for billing verification
  • Implement retry logic with exponential backoff
  • Validate all user inputs before API calls
  • Handle timezone conversions properly
  • Add loading states for better UX
  • Cache divisional charts (they never change)
  • Monitor API response times
  • Set up webhook for API status updates

Common Pitfalls

1. Incorrect Time Format

// ❌ Wrong
const hour = "14:30"; // String won't work

// ✅ Correct
const hour = 14.5; // Decimal format

2. Missing Timezone Handling

// ❌ Wrong - assuming local time
const birthData = {
  year: 1990,
  month: 7,
  day: 15,
  hour: 14.5,
  // Missing timezone consideration
};

// ✅ Correct - UTC conversion
import { DateTime } from 'luxon';

const localTime = DateTime.fromObject(
  { year: 1990, month: 7, day: 15, hour: 14, minute: 30 },
  { zone: 'Asia/Kolkata' }
);

const utcTime = localTime.toUTC();
const birthData = {
  year: utcTime.year,
  month: utcTime.month,
  day: utcTime.day,
  hour: utcTime.hour + utcTime.minute / 60,
};

3. Not Caching Static Data

// ❌ 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;
}

Conclusion

You now have a complete reference for building professional Vedic astrology applications using the RoxyAPI Kundli API. From basic birth charts to advanced divisional chart analysis, yoga detection, and compatibility matching - everything you need is at your fingertips.

Key endpoints covered:

  • Birth Chart (D1 Rashi)
  • Divisional Charts (D1-D60)
  • Navamsa Chart (D9)
  • Planetary Strengths (Shadbala)
  • Planetary Yogas (300+ combinations)
  • Panchang (Tithi, Nakshatra, Yoga, Karana)
  • Dasha Systems (Vimshottari)
  • Compatibility (Ashtakoot Gun Milan)
  • Dosha Detection (Manglik, Kalsarpa, Sadhesati)
  • KP Astrology (Cusps, Sub-lords)

Ready to build your kundli application? Sign up for RoxyAPI and get instant access to all endpoints. Complete interactive documentation at roxyapi.com/docs.

Need help? Check out our other guides: