VedAstro 1.23.29

The most comprehensive Vedic astrology library for Python — 684 calculations, one line of code.

🚀 Why VedAstro? The Simplest & Most Affordable Vedic Astrology API

✨ Unbeatable Value

The Bottom Line: Get 10x more features at 1/50th the price. No credit card needed to start.

💰 Pricing That Makes Sense

Indian Developers: ₹79/month or ₹758/year (₹63/month, most popular)

All 684 calculations included in both tiers. The only difference is rate limits.

🎯 Built for Real Apps

Perfect for:

• 📱 Horoscope mobile apps - Get 200+ life predictions instantly
• 💑 Marriage matching services - 16-factor Kuta compatibility analysis
• 📅 Daily panchanga widgets - Tithi, Nakshatra, Yoga, Karana
• 🔮 AI astrology chatbots - Natural language birth chart queries
• 📊 Astrological research - Batch process thousands of charts
• 🌟 Numerology calculators - Chaldean system with life aspect scores

🏃 Quick Start (3 minutes to your first calculation)

Installation (10 seconds)

pip install vedastro

That's it! No C++ compilers, no ephemeris files, no system dependencies.

Your First Calculation (20 seconds)

from vedastro import *

# Set API key (use 'FreeAPIUser' for free tier)
Calculate.SetAPIKey('FreeAPIUser')

# Define birth time and location
birth = Time("14:30 25/10/1992 +05:30",
             GeoLocation("Mumbai", 72.8777, 19.0760))

# Get Sun sign (one line!)
sun_sign = Calculate.PlanetRasiD1Sign(PlanetName.Sun, birth)['Name']

print(f"Sun Sign: {sun_sign}")  # Output: "Libra"

That's it! You just made your first Vedic astrology calculation. 🎉

📚 Beginner-Friendly Examples

Example 1: Get Birth Chart Basics

Use Case: Display Sun, Moon, and Ascendant signs

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

# Birth details
birth = Time("14:30 25/10/1992 +05:30",
             GeoLocation("Mumbai", 72.8777, 19.0760))

# Get the big three
sun_sign = Calculate.PlanetRasiD1Sign(PlanetName.Sun, birth)['Name']
moon_sign = Calculate.PlanetRasiD1Sign(PlanetName.Moon, birth)['Name']
ascendant = Calculate.HouseSignName(HouseName.House1, birth)

print(f"Sun: {sun_sign}")        # e.g., "Libra"
print(f"Moon: {moon_sign}")       # e.g., "Scorpio"
print(f"^Rising: {ascendant}")     # e.g., "Capricorn"

👉 See full example: demo_birth_chart_basics.py

Example 2: Marriage Compatibility

Use Case: Check if two people are compatible for marriage

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

# Person 1
person1 = Time("23:40 31/12/1996 +08:00",
               GeoLocation("Tokyo", 139.83, 35.65))

# Person 2
person2 = Time("14:30 15/06/1997 -05:00",
               GeoLocation("NYC", -74.006, 40.7128))

# Get compatibility report (16-factor Kuta analysis)
match = Calculate.MatchReport(person1, person2)

# Check overall compatibility
print(f"Compatibility Score: {match['KutaScore']}/100")
print(f"{match['Summary']['ScoreSummary']}")

# Show predictions
for prediction in match['PredictionList'][:5]:
    print(f"  • {prediction['Name']}: {prediction['Nature']}")

Output:

Compatibility Score: 65/100
Near perfect match, overall happiness
  • Graha Maitram: Good
  • Rajju: Good
  • Nadi Kuta: Good
  • Vasya Kuta: Bad
  • Dina Kuta: Good

👉 See full example: demo_marriage_compatibility.py

Example 3: Current Planetary Positions

Use Case: Get today's planetary positions for any location

from vedastro import *
from datetime import datetime

Calculate.SetAPIKey('FreeAPIUser')

# Current moment
now = datetime.now()
location = GeoLocation("London", -0.1278, 51.5074)
current_time = Time(
    hour=now.hour, minute=now.minute,
    day=now.day, month=now.month, year=now.year,
    offset="+00:00", geolocation=location
)

# Get all 9 planets
planets = [PlanetName.Sun, PlanetName.Moon, PlanetName.Mars,
           PlanetName.Mercury, PlanetName.Jupiter, PlanetName.Venus,
           PlanetName.Saturn, PlanetName.Rahu, PlanetName.Ketu]

print("Current Planetary Positions:")
for planet in planets:
    sign = Calculate.PlanetRasiD1Sign(planet, current_time)['Name']
    constellation = Calculate.PlanetConstellation(planet, current_time)
    print(f"  {planet}: {sign} in {constellation}")

Output:

Current Planetary Positions:
  Sun: Taurus in Rohini
  Moon: Sagittarius in Moola
  Mars: Pisces in Revathi
  Mercury: Aries in Bharani
  ...

👉 See full example: demo_current_planets.py

Example 4: Daily Panchanga

Use Case: Get today's Tithi, Nakshatra, Yoga for a location

from vedastro import *
from datetime import datetime

Calculate.SetAPIKey('FreeAPIUser')

# Today in Mumbai
now = datetime.now()
location = GeoLocation("Mumbai", 72.8777, 19.0760)
today = Time(
    hour=now.hour, minute=now.minute,
    day=now.day, month=now.month, year=now.year,
    offset="+05:30", geolocation=location
)

# Get panchanga elements
tithi = Calculate.LunarDay(today)
nakshatra = Calculate.MoonConstellation(today)
yoga = Calculate.NithyaYoga(today)
karana = Calculate.Karana(today)

print(f"Panchanga for {now.strftime('%d %B %Y')}")
print(f"Tithi: {tithi}")
print(f"* Nakshatra: {nakshatra}")
print(f"Yoga: {yoga}")
print(f"!! Karana: {karana}")

Output:

Panchanga for 18 May 2026
Tithi: Shukla Dwadashi
* Nakshatra: Pushya
Yoga: Ganda
!! Karana: Vishti

👉 See full example: demo_daily_panchanga.py

Example 5: Vimshottari Dasa Timeline

Use Case: Get planetary periods (Mahadasa → Bhukti → Antaram)

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

# Birth details
birth = Time("14:30 25/10/1992 +05:30",
             GeoLocation("Mumbai", 72.8777, 19.0760))

# Get dasa from 2020-2030
start = Time("00:00 01/01/2020 +05:30",
             GeoLocation("Mumbai", 72.8777, 19.0760))
end = Time("23:59 31/12/2030 +05:30",
           GeoLocation("Mumbai", 72.8777, 19.0760))

# Calculate with 3 levels of depth
dasa = Calculate.DasaAtRange(birth, start, end, levels=3, precisionHours=100)

# Print Mahadasa -> Bhukti -> Antaram
import json
print(json.dumps(dasa, indent=2))

👉 See full example: demo_vimshottari_dasa.py

Example 6: Numerology Calculator

Use Case: Get Chaldean numerology analysis for a name

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

# Person details
name = "John Doe"
dob = Time("14:30 25/10/1992 +05:30",
           GeoLocation("NYC", -74.006, 40.7128))

# Numbers taken from the birth date
print("Birth number:  ", Calculate.BirthNumber(dob))
print("Destiny number:", Calculate.DestinyNumber(dob))

# Name number (Chaldean system), with its ruling planet and interpretation
prediction = Calculate.NameNumberPrediction(name)
print(f"{name}: number {prediction['Number']} "
      f"(root {prediction['RootNumber']}, ruling planet {prediction['Planet']})")
print(prediction['Prediction'])

Output:

Birth number:   7
Destiny number: 2
John Doe: number 34 (root 7, ruling planet Ketu)
This number has the potential to be seen as lucky, ...

Prediction is HTML-formatted interpretation text - render it or strip the tags before display.

👉 See full example: demo_numerology_calculator.py

Example 7: Semantic Search of Classical Texts (RAG)

Use Case: Ask a plain-English question and get the most relevant passages from classical Vedic books (BPHS, Phaladeepika, Hindu Predictive Astrology, …) — no exact keywords needed

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

# See which classical texts are searchable
print(Calculate.GetAvailableSourceTexts())

# Natural-language semantic search across all texts
passages = Calculate.SearchSourceText("effects of Saturn in the 7th house")

for p in passages:
    # lower score = closer match -> convert to a relevance %
    relevance = (1 - p.get("score", 1)) * 100
    print(f"{p['sourceName']} p.{p['pageNumber']} ({relevance:.0f}%)")
    print(f"   {p['text']}\n")

# Narrow to one book and tune the knobs
focused = Calculate.SearchSourceText(
    "results of Jupiter aspecting the Moon",
    topK=3,
    sourceName="Hindu-Predictive-Astrology",
    contextSize=800,
)

Output:

['Brihat-Parashara-Hora-Shastra', 'Hindu-Predictive-Astrology', 'Phaladeepika', ...]
Hindu-Predictive-Astrology p.142 (71%)
   Saturn in the 7th house makes the native ...
Phaladeepika p.88 (66%)
   The seventh house governs marriage and partnership ...

🤖 This is the same retrieval step that powers VedAstro's RAG/AI features — feed the returned passages into an LLM prompt to build a cited astrology chatbot.

👉 See full example: demo_rag_vedic_books.py

🎓 Step-by-Step Tutorials

Tutorial 1: Understanding Time Format

The Most Common Beginner Issue: Time Format

Format: "HH:MM DD/MM/YYYY +TZ:TZ"

Two Ways to Create Time:

from vedastro import *

# Method 1: String format (easiest for beginners)
time1 = Time("14:30 25/10/1992 +05:30",
             GeoLocation("Mumbai", 72.8777, 19.0760))

# Method 2: Individual parameters (more explicit)
time2 = Time(
    hour=14, minute=30,
    day=25, month=10, year=1992,
    offset="+05:30",
    geolocation=GeoLocation("Mumbai", 72.8777, 19.0760)
)

# Both are equivalent!

Common Mistakes:

# [x] Wrong - Wrong date format (YYYY-MM-DD not supported)
Time("14:30 1992-10-25 +05:30", location)

# [x] Wrong - AM/PM format not supported (use 24-hour)
Time("2:30 PM 25/10/1992 +05:30", location)

# [x] Wrong - Missing timezone offset
Time("14:30 25/10/1992", location)

# [ok] Correct
Time("14:30 25/10/1992 +05:30", location)

Tutorial 2: Choosing the Right Ayanamsa

What is Ayanamsa?

Ayanamsa is the difference between tropical (Western) and sidereal (Vedic) zodiacs. Different ayanamsa systems can shift planet positions by 0-3 degrees.

47 Systems Available (most comprehensive library):

How to Switch:

from vedastro import *

Calculate.SetAPIKey('FreeAPIUser')

birth = Time("14:30 25/10/1992 +05:30", GeoLocation("Mumbai", 72.8777, 19.0760))

# Nothing set: the API applies its own default, which measures as Lahiri
print(Calculate.GetAyanamsa())                                  # None
print(Calculate.AyanamsaDegree(birth)['DegreeMinuteSecond'])     # 23° 45' 39

# Set it for the rest of the script
Calculate.SetAyanamsa(Ayanamsa.Raman)
print(Calculate.AyanamsaDegree(birth)['DegreeMinuteSecond'])     # 22° 18' 2

# ...or scope it to a block - it reverts automatically on exit
with Calculate.use_ayanamsa(Ayanamsa.Krishnamurti):
    print(Calculate.AyanamsaDegree(birth)['DegreeMinuteSecond']) # 23° 39' 52

print(Calculate.GetAyanamsa())                                  # Raman again

Values above are measured output, not illustrations: ayanamsa choice shifts positions by up to ~3°, so a planet near a sign boundary can change sign. Any calculator call made inside the block also uses the scoped ayanamsa.

Recommendation:

• 🇮🇳 Indian astrology → Use Ayanamsa.Lahiri
• 🌏 API default → Use Ayanamsa.Lahiri (measured server default)
• 📐 KP system → Use Ayanamsa.Krishnamurti
• 🌍 Western sidereal → Use Ayanamsa.Fagan_Bradley

Tutorial 3: Interpreting Match Reports

Understanding Kuta Score:

The 16 Kutas Explained:

1. Graha Maitram (5 pts) - Mental compatibility, happiness
2. Gana (6 pts) - Temperament match (Deva/Manushya/Rakshasa)
3. Yoni (4 pts) - Sexual compatibility
4. Nadi (8 pts) - Health & progeny (most important!)
5. Varna (1 pt) - Spiritual/ego compatibility
6. ...and 11 more factors

Reading the Report:

match = Calculate.MatchReport(person1, person2)

# Overall score
print(f"Score: {match['KutaScore']}/36")  # e.g., 25/36

# Summary
print(match['Summary']['ScoreSummary'])  # e.g., "Good compatibility"

# Individual Kutas
for kuta in match['PredictionList']:
    print(f"{kuta['Name']}: {kuta['Nature']}")  # Good/Bad/Neutral
    print(f"  Info: {kuta['Info']}")

🔧 Common Use Cases & Demo Files

🐛 Troubleshooting & FAQ

Q: "I'm getting rate limit errors"

A: Free tier allows 5 requests per minute. Solutions:

import time

# Solution 1: Add delays between requests (12 seconds = 5 req/min)
for i in range(10):
    result = Calculate.PlanetRasiD1Sign(PlanetName.Sun, birth)['Name']
    time.sleep(12)  # Wait 12 seconds between requests

# Solution 2: Upgrade to premium ($1/month unlimited)
Calculate.SetAPIKey('your-premium-key-here')  # No more rate limits!

Q: "Time format errors - what am I doing wrong?"

A: Use format: "HH:MM DD/MM/YYYY +TZ:TZ" (24-hour format, DD/MM/YYYY order)

# [ok] Correct examples
Time("14:30 25/10/1992 +05:30", location)  # 2:30 PM IST
Time("09:00 01/01/2000 -05:00", location)  # 9 AM EST
Time("23:45 15/08/1985 +09:00", location)  # 11:45 PM JST

# [x] Wrong examples
Time("2:30 PM 25/10/1992 +05:30", location)  # No AM/PM
Time("14:30 1992-10-25 +05:30", location)   # Wrong date format
Time("14:30 25/10/1992", location)          # Missing timezone

Q: "Which ayanamsa should I use?"

A: Quick guide:

• 🇮🇳 You're in India → Ayanamsa.Lahiri (govt standard)
• 🌐 You're unsure → Ayanamsa.Lahiri (API default)
• 📐 You use KP → Ayanamsa.Krishnamurti
• 🌍 You're Western sidereal → Ayanamsa.Fagan_Bradley

Calculate.SetAyanamsa(Ayanamsa.Lahiri)  # Most common choice

Q: "API returns error or 'Fail' status - why?"

A: Common causes:

1. Invalid API key → Use 'FreeAPIUser' for free tier
2. Wrong time format → Use "HH:MM DD/MM/YYYY +TZ:TZ"
3. Invalid coordinates → Latitude: -90 to 90, Longitude: -180 to 180
4. Rate limit exceeded → Wait 60 seconds or upgrade to premium

# Proper error handling
try:
    result = Calculate.PlanetRasiD1Sign(PlanetName.Sun, birth)['Name']
    print(result)
except Exception as e:
    print(f"Error: {e}")
    # Check: API key, time format, coordinates, rate limits

Q: "What's the difference between longitude and degree?"

A:

• Niravana Longitude → 0-360° continuous across zodiac (e.g., 217.45°)
• Degree → 0-30° within current sign (e.g., 7° 27' Scorpio)

longitude = Calculate.PlanetNirayanaLongitude(PlanetName.Sun, birth)
# Returns: 217.45 (continuous)

degree = Calculate.PlanetRasiD1Sign(PlanetName.Sun, birth)['DegreesIn']
# Returns: "7° 27' 15\"" (within Scorpio)

Q: "Can I use this commercially?"

A: Yes! Both free and premium tiers allow commercial use. MIT license.

• ✅ Build and sell horoscope apps
• ✅ Offer paid astrology services
• ✅ Use in commercial websites
• ✅ Integrate into SaaS products

No attribution required (but appreciated!).

Q: "What's included in free vs premium?"

A: All 684 calculations included in both! Only difference is rate limits:

Q: "How do I get premium API key?"

A:

1. Go to vedastro.org/API.html
2. Choose plan: $1/month or ₹758/year (India)
3. Payment via: Card, UPI, Google Pay, PayPal
4. Get API key instantly from vedastro.org/Account.html

Calculate.SetAPIKey('your-premium-key-here')
# Now unlimited requests!

📖 What Can You Calculate? (684 Methods)

Full API reference: vedastro.org/API.html

Planets (120 methods)

PlanetSignName, PlanetConstellation, PlanetNirayanaLongitude, PlanetHouseName, PlanetShadbala, PlanetRetrograde, PlanetsInSign, PlanetsInConjunction, PlanetAspectPlanet, AllPlanetData, +110 more

Houses (85 methods)

HouseSignName, HouseLord, HouseStrength, AllHouseData, AllHouseRasiSigns, AllHouseNavamshaSigns, HousePlanetsNames, +78 more

Zodiac (42 methods)

AllZodiacSignData, IsPlanetInSign, SignLord, SignElement, SignNature, +37 more

Matching (15 methods)

MatchReport, MatchReportWithBazi, MatchChat, KutaCheck, GrahamaitramKuta, YoniKuta, NadiKuta, +8 more

Events & Predictions (180 methods)

HoroscopePredictions, EventsAtTime, EventsAtRange, EventStartTime, MuhurthaFinder, +175 more

Dasa (8 methods)

DasaAtRange, CurrentDasa, VimshottariDasaMahadasa, VimshottariBhukti, +4 more

Divisional Charts (60 methods)

AllHouseNavamshaSigns (D9), AllHouseDrekkana Signs (D3), AllHouseChaturthamsaSigns (D4), D1-D60 vargas

Ashtakvarga (45 methods)

AllPlanetAshtakvarga, SarvaAshtakvarga, BhinnaAshtakvarga, +42 more

AI Features (8 methods)

BirthTimeAutoAIFill, HoroscopeLLMSearch, MatchChat, SearchSourceText (RAG over classical texts), GetAvailableSourceTexts, +3 more

Numerology (10 methods)

NumerologyReport, NameNumber, LifePathNumber, DestinyNumber, +6 more

🎯 Next Steps

1. Install: pip install vedastro (10 seconds)
2. Try examples above: Copy, paste, run! (5 minutes)
3. Explore demos: Run 20+ example files (30 minutes)
4. Read tutorials: TUTORIALS.md (optional)
5. Build something: Your first horoscope app! (1-2 hours)
6. Upgrade when ready: $1/month at vedastro.org/API.html

💡 Why Developers Love VedAstro

"I was paying $150/month for a competing API. VedAstro is $1/month with more features and better docs. Absolute no-brainer." — Rahul, India

"Setup took 2 minutes. First calculation worked immediately. No configuration hell. This is how all APIs should be." — Sarah, USA

"684 calculations, 47 ayanamsas, Swiss Ephemeris accuracy, $1/month. I thought there was a catch. There isn't." — Yuki, Japan

"The free tier is generous enough for my personal app with 50 users. When I scale up, $1/month won't break the bank." — Carlos, Brazil

🏗️ How It Works (Architecture)

Your Python Code
      v
vedastro pip library (this package)
      v
REST API (vedastro.zaishi.net)
      v
VedAstro Engine (Azure Cloud)
      v
Swiss Ephemeris (NASA JPL data)

Why cloud-powered?

• ✅ Zero local dependencies (no DLLs, no native code)
• ✅ Instant updates (684 calculations, always latest)
• ✅ Blazing fast (< 500ms average response)
• ✅ No setup complexity (works on Windows/Mac/Linux)
• ✅ Scales automatically (handles any load)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md

Note: vedastro/calculate.py is auto-generated by StaticTableGenerator in the main repo. Do not edit it directly.

📄 License

MIT License - Use freely in commercial and personal projects.

🙏 Support the Project

VedAstro is non-profit and user-funded. If it saves you time and money:

• ⭐ Star on GitHub (helps others discover us)
• 💰 Subscribe $1/month at vedastro.org/API.html
• 🎁 Donate at vedastro.org/Donate
• 📢 Share with other developers

Every subscription helps keep VedAstro free and open-source! 🙏

📚 Additional Resources

• 📖 Full API Docs: vedastro.org/API.html
• 🚀 Quick Start: QUICKSTART.md
• 🎓 Tutorials: TUTORIALS.md
• ❓ FAQ: FAQ.md
• 💬 Telegram: t.me/vedastro_org
• 🐛 Issues: GitHub Issues
• 🌐 Website: vedastro.org

Made with ❤️ by users, for users
Website • API Docs • GitHub • Telegram • Donate

🪐 Empowering developers to build amazing astrology apps since 2020