# 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

```bash
# 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
  }'
```

## Common Parameters

All endpoints requiring birth data accept these parameters:

| Parameter | Type | Range | Description |
|-----------|------|-------|-------------|
| `date` | string | YYYY-MM-DD | Birth date in ISO format |
| `time` | string | HH:MM:SS | Birth time in 24-hour format |
| `latitude` | float | -90 to 90 | Birth location latitude |
| `longitude` | float | -180 to 180 | Birth location longitude |
| `timezone` | float | -12 to 14 | Optional: timezone offset in decimal hours (defaults to 5.5 IST) |

### Time Format Examples

```javascript
// 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
```

## 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

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

### Response Structure

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

### TypeScript Types

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

### 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

```json
{
  "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

```typescript
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

```json
{
  "date": "1990-07-15",
  "time": "14:30:00",
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": 5.5,
  "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

```typescript
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. Shadbala API (Planetary Strengths)

Calculate Shadbala (six-fold strength) for all 7 classical planets.

### Endpoint

```
POST /shadbala
```

### Response

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

### Strength Interpretation

```typescript
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 (Reference Data)

Browse over 300 classical yoga definitions. These are GET endpoints returning reference data (formation rules and effects), not birth-chart analysis endpoints.

### List All Yogas

```
GET /yoga
```

### Response

```json
{
  "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 Details

```
GET /yoga/{id}
```

### Response

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

### 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

```typescript
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,
  };
}
```

## 6. Panchang API

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

### Endpoint

```
POST /panchang/basic
```

### Request

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

### Response

```json
{
  "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

```typescript
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

```json
{
  "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/major
```

Returns all 9 Mahadashas spanning 120 years.

### Antardasha List

```
POST /dasha/sub/{mahadasha}
```

Get all 9 Antardashas for a specific Mahadasha (e.g., `/dasha/sub/Jupiter`).

## 8. Compatibility API (Ashtakoot)

Gun milan scoring for marriage matching.

### Endpoint

```
POST /compatibility
```

### Request

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

### Response

```json
{
  "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

```typescript
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

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

### Kalsarpa Dosha

```
POST /dosha/kalsarpa
```

### Response

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

### Sadhesati

```
POST /dosha/sadhesati
```

Detect Saturn's 7.5 year transit period.

## 10. KP Astrology Endpoints

Krishnamurti Paddhati system for precise predictions.

### KP Chart

```
POST /kp/chart
```

### Response

```json
{
  "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:

```typescript
// 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.';
  }
}
```

## Error Handling

Implement comprehensive error handling:

```typescript
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

```typescript
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

```typescript
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

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

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

### 2. Missing Timezone Handling

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

### 3. Not Caching Static Data

```typescript
// ❌ 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)
- Shadbala (Six-fold Planetary Strength)
- Planetary Yogas Reference (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](https://roxyapi.com/pricing) and get instant access to all endpoints. Complete interactive documentation at [roxyapi.com/docs](https://roxyapi.com/docs).

Need help? Check out our other guides:
- [How to Build a Kundli Generator App in React Native](https://roxyapi.com/blog/build-kundli-generator-react-native)
- [Vedic Astrology API Integration Guide](https://roxyapi.com/blog/vedic-astrology-api-integration-guide)
- [Building a Kundli Matching Feature](https://roxyapi.com/blog/kundli-matching-feature-matrimonial-app)