VedAstro 1.23.30

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

🎯 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: "Is there a request timeout?"

A: No, and that is deliberate. A VedAstro calculation can take milliseconds or minutes depending on the endpoint and the load on the service, and this library has no way to know what is acceptable for your workload. A built-in deadline would be exactly the kind of brittle logic that silently truncates a valid answer, so none is applied. If a call is still running, it is still working.

When you want a deadline — because your own request or job budget demands one — set it explicitly:

Calculate.SetTimeout(30)     # seconds; only because *you* decided 30s is too long
print(Calculate.GetTimeout())  # 30

Calculate.SetTimeout(None)   # remove it again

SetTimeout takes seconds and rejects a non-positive value or a non-number. Without it, the library passes no timeout to requests at all, so your process is bounded only by whatever your own framework, task runner or shell imposes — which is usually the right place to express the limit.

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!

🚀 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.

📖 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