DEV Community

Cover image for How to Build a Kundali App with Free Vedic Astrology API — Step by Step
AstroAsk
AstroAsk

Posted on

How to Build a Kundali App with Free Vedic Astrology API — Step by Step

#api #python #tutorial #webdev

Complete Vedic birth chart (Kundali) with nakshatras, dashas, and gun milan — one API call, 75ms.

Table of Contents

The Problem

You're building an astrology app for Indian users. They want:

  • Kundali (birth chart) with all 9 planets
  • Nakshatras (lunar mansions)
  • Dasha periods (planetary timing)
  • Gun Milan (compatibility matching)
  • Charts in Hindi, Tamil, Telugu, or their language

You search for a Vedic astrology API and find:

  • APIs that only do Western astrology
  • APIs that need 6-10 calls for one chart
  • APIs with 500ms+ latency
  • APIs that cost ₹4000/month before testing
  • APIs that don't support Indian languages

What if one API did everything?

Meet AstroAsk — Free Vedic Astrology API

AstroAsk is a free API built specifically for developers adding Vedic astrology to their apps.

Why developers love it:

  • ✅ Complete Kundali in one API call
  • ✅ 9 planets + 12 houses + 27 nakshatras
  • ✅ Dasha system (Mahadasha, Antardasha)
  • ✅ Gun Milan for compatibility (36-point system)
  • ✅ SVG chart rendering (ready to display)
  • ✅ 21 languages (Hindi, Tamil, Telugu, Bengali, more)
  • ✅ Auto-timezone from coordinates (no UTC conversion!)
  • ✅ 75ms average latency (10x faster than alternatives)
  • ✅ Free tier: 500 requests/month
  • ✅ NASA JPL-precision calculations

What We're Building

A simple Kundali feature that:

  1. Takes birth details (date, time, place)
  2. Returns complete Vedic birth chart
  3. Shows nakshatras and dashas
  4. Renders as an SVG chart image
  5. Works in Hindi or English

Time to build: 10 minutes

Step 1: Get Your Free API Key

  1. Go to AstroAsk on RapidAPI
  2. Click "Subscribe to Test"
  3. Select the Basic (Free) plan
  4. Copy your API key from the dashboard

No credit card needed.

Step 2: Your First Kundali API Call

Let's get a Vedic birth chart for someone born on November 11, 2002 at midnight in New Delhi.

Python 

import requests

url = "https://astroask-vedic-western-astrology-api.p.rapidapi.com/api/v1/kundali"

payload = {
    "date": "2002-11-11T00:00:00",
    "lat": 28.6139,  # New Delhi latitude
    "lng": 77.2090,  # New Delhi longitude
    "lang": "hi"     # Hindi output
}

headers = {
    "x-rapidapi-key": "YOUR_API_KEY",
    "x-rapidapi-host": "astroask-vedic-western-astrology-api.p.rapidapi.com",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(data)
Enter fullscreen mode Exit fullscreen mode

JavaScript (Node.js) 

const url = "https://astroask-vedic-western-astrology-api.p.rapidapi.com/api/v1/kundali";

const payload = {
    date: "2002-11-11T00:00:00",
    lat: 28.6139,
    lng: 77.2090,
    lang: "hi"
};

const response = await fetch(url, {
    method: "POST",
    headers: {
        "x-rapidapi-key": "YOUR_API_KEY",
        "x-rapidapi-host": "astroask-vedic-western-astrology-api.p.rapidapi.com",
        "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
});

const data = await response.json();
console.log(data);
Enter fullscreen mode Exit fullscreen mode

cURL 

curl -X POST "https://astroask-vedic-western-astrology-api.p.rapidapi.com/api/v1/kundali" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: astroask-vedic-western-astrology-api.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{"date": "2002-11-11T00:00:00", "lat": 28.6139, "lng": 77.2090, "lang": "hi"}'
Enter fullscreen mode Exit fullscreen mode

Step 3: Understanding the Kundali Response

Here's what you get back:

{
  "success": true,
  "data": {
    "birth_chart": {
      "ascendant": {
        "sign": "कर्क",        // Cancer in Hindi
        "degree": 12.45,
        "nakshatra": "पुष्य"   // Pushya nakshatra
      },
      "planets": [
        {
          "name": "सूर्य",      // Sun
          "sign": "तुला",      // Libra
          "degree": 24.32,
          "house": 4,
          "nakshatra": "विशाखा", // Vishakha
          "retrograde": false
        },
        {
          "name": "चंद्र",      // Moon
          "sign": "वृषभ",      // Taurus
          "degree": 8.67,
          "house": 11,
          "nakshatra": "कृत्तिका", // Krittika
          "retrograde": false
        }
        // ... all 9 Vedic planets
      ],
      "houses": [
        {"number": 1, "sign": "कर्क", "lord": "चंद्र"},
        {"number": 2, "sign": "सिंह", "lord": "सूर्य"}
        // ... all 12 houses
      ]
    },
    "chart_svg": "<svg>...</svg>",
    "dashas": {
      "current_mahadasha": "राहु",    // Rahu
      "current_antardasha": "गुरु",   // Jupiter
      "period": "2020-2038"
    },
    "nakshatras": {
      "moon_nakshatra": "कृत्तिका",
      "pada": 2,
      "rashi": "वृषभ"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Key Vedic fields:

  • birth_chart — All 9 planets with signs, degrees, houses
  • nakshatras — Lunar mansions (27 nakshatras, 4 padas each)
  • dashas — Current planetary period (Mahadasha + Antardasha)
  • chart_svg — Ready-to-display SVG chart image

Step 4: Display the Kundali Chart

The API returns an SVG image. Just embed it:

HTML 

<div id="kundali-chart"></div>

<script>
// After fetching the API response
const chartSvg = data.data.chart_svg;
document.getElementById('kundali-chart').innerHTML = chartSvg;
</script>
Enter fullscreen mode Exit fullscreen mode

React 

function KundaliChart({ birthData }) {
  const [chartSvg, setChartSvg] = useState('');

  useEffect(() => {
    fetch('/api/kundali', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(birthData)
    })
    .then(res => res.json())
    .then(data => setChartSvg(data.data.chart_svg));
  }, [birthData]);

  return (
    <div 
      className="kundali-container"
      dangerouslySetInnerHTML={{ __html: chartSvg }} 
    />
  );
}
Enter fullscreen mode Exit fullscreen mode

That's it. No need to build a chart renderer. The SVG is ready to display.

Step 5: Nakshatras Explained

Nakshatras are lunar mansions — unique to Vedic astrology. Each person has a birth nakshatra based on Moon's position.

Why nakshatras matter:

  • Determines personality traits
  • Used for naming babies (first letter based on nakshatra)
  • Critical for marriage matching (kundali milan)
  • Predicts life events and timing

The 27 Nakshatras:

# Nakshatra Ruling Planet Symbol
1 Ashwini Ketu Horse head
2 Bharani Venus Yoni
3 Krittika Sun Razor
4 Rohini Moon Chariot
5 Mrigashira Mars Deer head
... ... ... ...

Using nakshatras in your app:

def get_nakshatra_info(birth_data):
    chart = get_kundali(birth_data)
    moon_nakshatra = chart['nakshatras']['moon_nakshatra']
    pada = chart['nakshatras']['pada']

    return {
        "nakshatra": moon_nakshatra,
        "pada": pada,
        "first_letter": get_nakshatra_letter(moon_nakshatra, pada)
    }
Enter fullscreen mode Exit fullscreen mode

Step 6: Dasha System (Planetary Timing)

Dashas are Vedic astrology's timing system. They predict which planet influences your life during different periods.

The Vimshottari Dasha system:

  • Total cycle: 120 years
  • Each planet rules for a specific period
  • Current Mahadasha = major life theme
  • Current Antardasha = sub-period influence

Planet Dasha periods:

Planet Years
Ketu 7
Venus 20
Sun 6
Moon 10
Mars 7
Rahu 18
Jupiter 16
Saturn 19
Mercury 17

Using dashas in your app:

def get_current_dasha(birth_data):
    chart = get_kundali(birth_data)
    dashas = chart['dashas']

    return {
        "mahadasha": dashas['current_mahadasha'],
        "antardasha": dashas['current_antardasha'],
        "period": dashas['period'],
        "description": get_dasha_effects(
            dashas['current_mahadasha'],
            dashas['current_antardasha']
        )
    }
Enter fullscreen mode Exit fullscreen mode

Step 7: Gun Milan (Compatibility Matching)

For matrimonial apps, Gun Milan is essential. It's a 36-point compatibility system.

The 8 Gunas (Koots):

# .Guna Points What it measures
1 Varna 4 Spiritual compatibility
2 Vashya 2 Mutual attraction
3 Tara 3 Health & well-being
4 Yoni 4 Nature & temperament
5 Graha Maitri 5 Planetary friendship
6 Gana 6 Behavior & attitude
7 Bhakoot 7 Health & happiness
8 Nadi 8 Genetic compatibility

Total: 36 points

Scoring:

  • 18+ points: Acceptable match
  • 25+ points: Good match
  • 30+ points: Excellent match

API call for Gun Milan:

url = "https://astroask-vedic-western-astrology-api.p.rapidapi.com/api/v1/compatibility"

payload = {
    "person1": {
        "date": "2002-11-11T00:00:00",
        "lat": 28.6139,
        "lng": 77.2090
    },
    "person2": {
        "date": "1999-05-15T14:30:00",
        "lat": 19.0760,
        "lng": 72.8777
    },
    "system": "vedic"
}

response = requests.post(url, json=payload, headers=headers)
compatibility = response.json()

print(f"Total Score: {compatibility['data']['total_score']}/36")
print(f"Recommendation: {compatibility['data']['recommendation']}")
Enter fullscreen mode Exit fullscreen mode

Real-World Use Cases

1. Matrimonial App 

@app.route('/api/match-compatibility')
def match_compatibility():
    result = get_gun_milan(boy.birth_data, girl.birth_data)

    return {
        "total_score": result['total_score'],
        "max_score": 36,
        "gunas": result['gunas'],  # Individual scores
        "recommendation": result['recommendation'],
        "is_compatible": result['total_score'] >= 18
    }
Enter fullscreen mode Exit fullscreen mode

2. Kundali Generation Service 

@app.route('/api/generate-kundali')
def generate_kundali():
    chart = get_kundali(user.birth_data)

    return {
        "planets": chart['birth_chart']['planets'],
        "houses": chart['birth_chart']['houses'],
        "nakshatras": chart['nakshatras'],
        "dashas": chart['dashas'],
        "chart_image": chart['chart_svg'],
        "language": user.preferred_language
    }
Enter fullscreen mode Exit fullscreen mode

3. Baby Naming App 

@app.route('/api/baby-name-suggestions')
def baby_names():
    # Get birth nakshatra
    chart = get_kundali(baby.birth_data)
    nakshatra = chart['nakshatras']['moon_nakshatra']
    pada = chart['nakshatras']['pada']

    # Get starting letter based on nakshatra
    first_letter = get_nakshatra_letter(nakshatra, pada)

    # Suggest names starting with that letter
    names = get_names_starting_with(first_letter, user.language)

    return {
        "nakshatra": nakshatra,
        "pada": pada,
        "starting_letter": first_letter,
        "suggested_names": names
    }
Enter fullscreen mode Exit fullscreen mode

4. Astrology Chatbot 

def handle_message(user_message, user_birth_data):
    # Get user's kundali
    chart = get_kundali(user_birth_data)

    # Use chart context in AI prompt
    prompt = f"""
    User's Kundali:
    - Nakshatra: {chart['nakshatras']['moon_nakshatra']}
    - Current Dasha: {chart['dashas']['current_mahadasha']}
    - Ascendant: {chart['birth_chart']['ascendant']['sign']}

    User's question: {user_message}

    Provide personalized Vedic astrology advice based on their chart.
    """

    return ai_generate(prompt)
Enter fullscreen mode Exit fullscreen mode

Gotchas & Tips

1. Timezone Handling

Don't convert to UTC! The API auto-derives timezone from coordinates.

# ✅ CORRECT — use local birth time
{"date": "2002-11-11T14:30:00", "lat": 28.6139, "lng": 77.2090}

# ❌ WRONG — don't convert to UTC yourself
{"date": "2002-11-11T09:00:00Z", "lat": 28.6139, "lng": 77.2090}
Enter fullscreen mode Exit fullscreen mode

2. Language Support

Pass lang parameter for localized output:

{"lang": "hi"}  # Hindi
{"lang": "ta"}  # Tamil
{"lang": "te"}  # Telugu
{"lang": "bn"}  # Bengali
{"lang": "mr"}  # Marathi
{"lang": "gu"}  # Gujarati
{"lang": "kn"}  # Kannada
{"lang": "ml"}  # Malayalam
{"lang": "pa"}  # Punjabi
{"lang": "en"}  # English
Enter fullscreen mode Exit fullscreen mode

21 languages supported total.

3. Coordinate Accuracy

For accurate charts, use precise coordinates:

# ❌ WRONG — city center approximation
{"lat": 28.6, "lng": 77.2}

# ✅ CORRECT — precise coordinates
{"lat": 28.6139, "lng": 77.2090}
Enter fullscreen mode Exit fullscreen mode

Use Google Maps or a geocoding API to get exact coordinates.

4. Rate Limiting

Free tier: 500 requests/month. Cache results!

from functools import lru_cache

@lru_cache(maxsize=1000)
def get_kundali(date, lat, lng):
    # Only calls API once per unique birth data
    return api_call(date, lat, lng)
Enter fullscreen mode Exit fullscreen mode

5. Error Handling

Always check for errors:

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if not data.get('success'):
    error = data.get('error', 'Unknown error')
    print(f"API Error: {error}")
    return None
Enter fullscreen mode Exit fullscreen mode

What to Build Next

Now that you have the basics, here are ideas:

  1. Matrimonial Matching — Gun Milan for arranged marriages
  2. Kundali PDF Generator — Downloadable birth charts
  3. Baby Naming App — Names based on nakshatra
  4. Daily Panchang — Tithi, nakshatra, muhurta
  5. Astrology Consultation Platform — Connect users with astrologers
  6. Horoscope Newsletter — Personalized daily predictions
  7. Kundali Matching Widget — Embeddable for wedding websites

Links & Resources

Conclusion

Building a Kundali app doesn't have to be hard. With AstroAsk:

  • One API call gets you a complete Vedic birth chart
  • SVG rendering means no chart-building code
  • 21 languages serves all Indian users
  • Free tier lets you test without commitment
  • 75ms latency keeps your app fast

Try it today. Your users will thank you.

Have questions? Drop a comment below or email us at intelligence@astroask.app

About the Author
Building AstroAsk — making Vedic astrology accessible to developers. NASA JPL-precision calculations, 21 languages, one API.

Top comments (0)