The most comprehensive Vedic astrology library for Python — 684 calculations, one line of code.
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
pip install vedastroThat's it! No C++ compilers, no ephemeris files, no system dependencies.
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. 🎉
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
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
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
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
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
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
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
The Most Common Beginner Issue: Time Format
Format: "HH:MM DD/MM/YYYY +TZ:TZ"
| Location | Example | Timezone Offset |
|---|---|---|
| India | "14:30 25/10/1992 +05:30" |
IST = UTC+5:30 |
| USA (East) | "09:30 25/10/1992 -05:00" |
EST = UTC-5:00 |
| USA (West) | "06:30 25/10/1992 -08:00" |
PST = UTC-8:00 |
| Japan | "23:30 25/10/1992 +09:00" |
JST = UTC+9:00 |
| UK | "14:30 25/10/1992 +00:00" |
GMT = UTC+0:00 |
| Australia | "00:30 26/10/1992 +10:00" |
AEST = UTC+10:00 |
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)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):
| System | When to Use |
|---|---|
| Lahiri | Indian government standard, most widely used - the API default when none is set |
| Raman | popular in South India |
| Krishnamurti | KP (Krishnamurti Paddhati) system |
| Fagan-Bradley | Western sidereal astrology |
| Yukteswar | Sri Yukteswar's calculation |
| ...42 more | See full list at vedastro.org/API.html |
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 againValues 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
Understanding Kuta Score:
| Score Range | Compatibility | Recommendation |
|---|---|---|
| 33-36 points | Excellent | Highly compatible |
| 25-32 points | Good | Compatible, proceed with confidence |
| 18-24 points | Average | Requires careful consideration |
| Below 18 | Poor | Not recommended without other factors |
The 16 Kutas Explained:
- Graha Maitram (5 pts) - Mental compatibility, happiness
- Gana (6 pts) - Temperament match (Deva/Manushya/Rakshasa)
- Yoni (4 pts) - Sexual compatibility
- Nadi (8 pts) - Health & progeny (most important!)
- Varna (1 pt) - Spiritual/ego compatibility
- ...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']}")| Demo File | Use Case | Skill Level |
|---|---|---|
demo_quick_start.py |
Absolute simplest example (5 lines) | Beginner |
demo_birth_chart_basics.py |
Sun/Moon/Ascendant signs | Beginner |
demo_marriage_compatibility.py |
Full match report with interpretation | Beginner |
demo_current_planets.py |
Today's planetary positions | Beginner |
demo_daily_panchanga.py |
Tithi, Nakshatra, Yoga | Beginner |
demo_numerology_calculator.py |
Name analysis with life aspects | Beginner |
demo_vimshottari_dasa.py |
Planetary periods timeline | Intermediate |
demo_all_planet_data.py |
Complete planet information | Intermediate |
demo_divisional_charts.py |
D9, D10, D12 varga charts | Intermediate |
demo_transit_analysis.py |
Current transits vs birth chart | Intermediate |
demo_custom_ayanamsa.py |
Switching between 47 systems | Intermediate |
demo_error_handling.py |
Proper API error handling | Intermediate |
demo_batch_processing.py |
Process multiple charts efficiently | Advanced |
demo_all_astro_data.py |
All planet and house data | Intermediate |
demo_all_astro_data_csv.py |
Export to CSV with pandas | Intermediate |
demo_bhava_chart_data.py |
Bhava house analysis | Intermediate |
demo_rag_vedic_books.py |
Semantic search of classical Vedic texts (RAG) | Intermediate |
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!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 timezoneA: 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 choiceA: 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 againSetTimeout 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.
A: Common causes:
- Invalid API key → Use
'FreeAPIUser'for free tier - Wrong time format → Use
"HH:MM DD/MM/YYYY +TZ:TZ" - Invalid coordinates → Latitude: -90 to 90, Longitude: -180 to 180
- 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 limitsA:
- 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)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!).
A: All 684 calculations included in both! Only difference is rate limits:
| Feature | Free | Premium |
|---|---|---|
| All calculations | ✅ | ✅ |
| All 47 ayanamsa | ✅ | ✅ |
| Commercial use | ✅ | ✅ |
| Swiss Ephemeris | ✅ | ✅ |
| Rate limit | 5 req/min | Unlimited |
| Cost | $0/month | $1/month |
A:
- Go to vedastro.org/API.html
- Choose plan: $1/month or ₹758/year (India)
- Payment via: Card, UPI, Google Pay, PayPal
- Get API key instantly from vedastro.org/Account.html
Calculate.SetAPIKey('your-premium-key-here')
# Now unlimited requests!| What You Get | VedAstro | Competitors |
|---|---|---|
| Monthly Cost | $1/month | $50-$200/month |
| Free Tier | ✅ 5 req/min | ❌ None or very limited |
| Calculations | 684+ methods | 50-200 methods |
| Ayanamsa Systems | 47 systems | 3-10 systems |
| Setup Complexity | Zero setup | Complex (DLLs, ephemeris files) |
| Commercial Use | ✅ Both tiers | ❌ Enterprise only |
The Bottom Line: Get 10x more features at 1/50th the price. No credit card needed to start.
| Tier | Price | Rate Limit | Best For |
|---|---|---|---|
| Free | $0/month | 5 req/min | Learning, testing, personal projects |
| Premium | $1/month | Unlimited | Production apps, commercial use |
Indian Developers: ₹79/month or ₹758/year (₹63/month, most popular)
All 684 calculations included in both tiers. The only difference is rate limits.
Full API reference: vedastro.org/API.html
PlanetSignName, PlanetConstellation, PlanetNirayanaLongitude, PlanetHouseName, PlanetShadbala, PlanetRetrograde, PlanetsInSign, PlanetsInConjunction, PlanetAspectPlanet, AllPlanetData, +110 more
HouseSignName, HouseLord, HouseStrength, AllHouseData, AllHouseRasiSigns, AllHouseNavamshaSigns, HousePlanetsNames, +78 more
AllZodiacSignData, IsPlanetInSign, SignLord, SignElement, SignNature, +37 more
MatchReport, MatchReportWithBazi, MatchChat, KutaCheck, GrahamaitramKuta, YoniKuta, NadiKuta, +8 more
HoroscopePredictions, EventsAtTime, EventsAtRange, EventStartTime, MuhurthaFinder, +175 more
DasaAtRange, CurrentDasa, VimshottariDasaMahadasa, VimshottariBhukti, +4 more
AllHouseNavamshaSigns (D9), AllHouseDrekkana Signs (D3), AllHouseChaturthamsaSigns (D4), D1-D60 vargas
AllPlanetAshtakvarga, SarvaAshtakvarga, BhinnaAshtakvarga, +42 more
BirthTimeAutoAIFill, HoroscopeLLMSearch, MatchChat, SearchSourceText (RAG over classical texts), GetAvailableSourceTexts, +3 more
NumerologyReport, NameNumber, LifePathNumber, DestinyNumber, +6 more
- Install:
pip install vedastro(10 seconds) - Try examples above: Copy, paste, run! (5 minutes)
- Explore demos: Run 20+ example files (30 minutes)
- Read tutorials: TUTORIALS.md (optional)
- Build something: Your first horoscope app! (1-2 hours)
- Upgrade when ready: $1/month at vedastro.org/API.html
"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
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)
We welcome contributions! See CONTRIBUTING.md
Note:
vedastro/calculate.pyis auto-generated by StaticTableGenerator in the main repo. Do not edit it directly.
MIT License - Use freely in commercial and personal projects.
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! 🙏
- 📖 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
