Astro Insight Python SDK

Official, strongly-typed Python 3.9+ SDK for the Astro Insight API. Supports both Synchronous (requests) and Asynchronous (httpx / asyncio) execution modes to easily integrate Vedic Astrology, Western Astrology, Matchmaking, Panchang, Muhurta, Tarot, Numerology, Chinese Astrology, and Geolocation calculations into your Python applications.

Features

• 🪐 Vedic Astrology: Ashtakvarga, Vimshottari / Char / Yogini Dashas, KP System, Jaimini, Lal Kitab, Varshaphal, Ghat Chakra, Horoscope Charts & Doshas.
• 💍 Matchmaking: Guna Milan, Kundali Compatibility, Manglik Matching.
• 🗓️ Panchang & Muhurta: Daily Panchang, Choghadiya, Hora, Shubh Muhurta timing.
• 🔮 Western Astrology & Tarot: Natal Charts, Solar Return, Daily/Weekly/Monthly Transits, Synastry, Tarot spreads (One-card, Three-card, Celtic Cross, Love, Career).
• 🔢 Numerology: Vedic & Western Numerology (Life Path, Destiny, Soul Urge).
• ☯️ Chinese Astrology & Biorhythm: Zodiac sign compatibility & biorhythm calculations.
• 🌍 Geo Utilities: Place search, timezone lookup by coordinates or ID.
• ⚡ Dual Execution Modes: Synchronous (AstroClient) and Async (AsyncAstroClient) with asyncio.
• 🛡️ Strongly Typed Dataclasses: BirthDetails, MatchInput, and GeoLocation models.

Installation

Install the package via pip:

pip install astroinsight-python-sdk

Quick Start

1. Synchronous Client (AstroClient)

from astroinsight import AstroClient, BirthDetails

client = AstroClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

birth = BirthDetails(
    day=15, month=8, year=1995,
    hour=10, min=30, sec=0,
    tzone=5.5, lat=28.6139, lon=77.2090
)

# Fetch Birth Details
details = client.vedic.astro_details.get_birth_details(birth)
print(details["data"]["birth_details"]["day"]) # Tuesday

# Fetch Sun Bhinnashtakavarga
ashtak = client.vedic.ashtakvarga.get_planet_ashtak("sun", birth)

# One Card Tarot Reading
tarot = client.tarot.get_one_card_reading()

2. Asynchronous Client (AsyncAstroClient)

import asyncio
from astroinsight import AsyncAstroClient, BirthDetails

async def main():
    async with AsyncAstroClient(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    ) as async_client:
        
        birth = BirthDetails(day=15, month=8, year=1995, hour=10, min=30)
        
        # Async call
        details = await async_client.vedic.astro_details.get_birth_details(birth)
        print(details["message"])

asyncio.run(main())

Code Examples

🪐 Vedic Astrology & Dashas

# Major Vimshottari Dasha
dasha = client.vedic.vimshottari_dasha.get_major_dasha(birth)

# Gemstone Suggestions
remedies = client.vedic.suggestions.get_gemstone_suggestions(birth)

# Manglik Dosha Check
manglik = client.vedic.horoscope_dosha.get_manglik_dosha(birth)

💍 Matchmaking (Guna Milan)

from astroinsight import MatchInput

male = BirthDetails(15, 8, 1995, 10, 30, lat=28.6139, lon=77.2090)
female = BirthDetails(20, 11, 1997, 14, 15, lat=19.0760, lon=72.8777)

match_input = MatchInput(male=male, female=female)

# Calculate Guna Milan
score = client.vedic.match_making.get_guna_milan(match_input)

🗓️ Daily Panchang & Muhurta

panchang = client.vedic.panchang.get_daily_panchang(birth)
choghadiya = client.vedic.muhurta.get_choghadiya(birth)

📊 Horoscope & Geo Services

# Daily Horoscope for Leo
leo_daily = client.horoscope.get_daily_horoscope("leo")

# Search Place Coordinates
place_info = client.geo.search_place("Delhi")

Dynamic Configuration & Headers

# Switch language dynamically
client.set_language("hi")

# Switch Ayanamsha system
client.set_ayanamsha("raman")

Exception Handling

from astroinsight import (
    AstroClient, BirthDetails,
    AuthenticationError, ValidationError, RateLimitError, AstroException
)

client = AstroClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
birth = BirthDetails(15, 8, 1995, 10, 30)

try:
    response = client.vedic.astro_details.get_birth_details(birth)
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except ValidationError as e:
    print(f"Validation failed: {e.message}, Errors: {e.errors}")
except RateLimitError as e:
    print("Rate limit exceeded. Retry later.")
except AstroException as e:
    print(f"API Error [{e.status_code}]: {e.message}")

Running Tests

Run unit tests using pytest:

pip install -e .[dev]
python3 -m pytest

License

This SDK is open-sourced software licensed under the MIT License.