Astrology API Python SDK (DivineAPI)

from divineapi import DivineApi

client = DivineApi(api_key="YOUR_API_KEY", auth_token="YOUR_AUTH_TOKEN")

# Panchang for Mumbai on 2 October 2026; tzone is a decimal UTC offset
result = client.indian.panchang.find_panchang(
    day=2, month=10, year=2026,
    place="mumbai", lat=19.076, lon=72.8777, tzone=5.5,
)

data = result["data"]
print("Sunrise:", data["sunrise"], "| Sunset:", data["sunset"])
for t in data["tithis"]:
    print("Tithi:", t["paksha"], t["tithi"], "until", t["end_time"])
# Sunrise: 2026-10-02 06:29:07 | Sunset: 2026-10-02 18:27:01
# Tithi: Krishna Shasthi until 2026-10-02 10:15:42
# Tithi: Krishna Saptami until 2026-10-03 06:28:42

# Daily / Weekly / Monthly / Yearly Horoscope
# daily h_day = today / tomorrow / yesterday; weekly/monthly/yearly = current / prev / next
client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
client.horoscope.weekly(sign="leo", week="current", tzone=5.5)
client.horoscope.monthly(sign="cancer", month="current", tzone=5.5)
client.horoscope.yearly(sign="virgo", year="current", tzone=5.5)

# Chinese & Numerology Horoscope
client.horoscope.chinese(sign="rat", h_day="today", tzone=5.5)
client.horoscope.numerology(number=7, day=10, month=3, year=2024, tzone=5.5)

# Tarot & Readings
client.horoscope.yes_or_no_tarot()
client.horoscope.daily_tarot()
client.horoscope.fortune_cookie()
client.horoscope.coffee_cup_reading()
client.horoscope.love_compatibility(sign_1="aries", sign_2="leo")

# Panchang, Nakshatra, Tithi, Yoga, Karana
client.indian.panchang.find_panchang(
    day=10, month=3, year=2024,
    place="delhi", lat=28.6139, lon=77.2090, tzone=5.5
)
client.indian.panchang.find_nakshatra(
    day=10, month=3, year=2024,
    place="mumbai", lat=19.076, lon=72.8777, tzone=5.5
)
client.indian.panchang.auspicious_timings(
    day=10, month=3, year=2024,
    place="delhi", lat=28.6139, lon=77.2090, tzone=5.5
)
client.indian.panchang.find_gowri_panchangam(
    day=10, month=3, year=2024,
    place="chennai", lat=13.0827, lon=80.2707, tzone=5.5
)

# Planetary transits
client.indian.panchang.grah_gochar(
    planet="jupiter", month=3, year=2024,
    place="delhi", lat=28.6139, lon=77.2090, tzone=5.5
)

birth = dict(
    full_name="John Doe", day=1, month=1, year=1990,
    hour=10, min=30, sec=0, gender="male",
    place="mumbai", lat=19.076, lon=72.8777, tzone=5.5,
)

client.indian.kundli.basic_astro_details(**birth)
client.indian.kundli.planetary_positions(**birth)
client.indian.kundli.manglik_dosha(**birth)
client.indian.kundli.vimshottari_dasha(**birth)
client.indian.kundli.sadhe_sati(**birth)
client.indian.kundli.yogas(**birth)
client.indian.kundli.horoscope_chart("D1", **birth)

# Jaimini
client.indian.kundli.jaimini_planetary_positions(**birth)
client.indian.kundli.jaimini_padas(**birth)
client.indian.kundli.jaimini_karakamsha_lagna(**birth)   # D1 recast from the Karakamsha sign
client.indian.kundli.jaimini_chara_dasha(**birth)
client.indian.kundli.jaimini_swamsa_chart(**birth)       # D9 recast from the Karakamsha sign

# jaimini_swamsa_chart returns atmakaraka, swamsha_sign_no, swamsha_sign,
# lagnamsha_sign_no, lagnamsha_sign and the chart as svg plus base64_image
# (~10 KB in all). With lan="hi" the names are translated, the numbers are not.

# Dasha analysis (no birth data needed)
client.indian.kundli.maha_dasha_analysis(maha_dasha="Sun")

# Lal Kitab
client.indian.kundli.lal_kitab_planetary_positions(**birth)
client.indian.kundli.lal_kitab_teva(**birth)
client.indian.kundli.lal_kitab_debts(**birth)
client.indian.kundli.lal_kitab_planet_analysis("sun", **birth)
client.indian.kundli.lal_kitab_house_signification(1, **birth)
client.indian.kundli.lal_kitab_varshphal_chart(2026, **birth)

# Lal Kitab dasha content (no birth data needed)
client.indian.kundli.lal_kitab_mahadasha_content(maha_dasha="saturn")
client.indian.kundli.lal_kitab_antardasha_content(maha_dasha="saturn", antar_dasha="mercury")

# Additional kundli analysis
client.indian.kundli.vargottama_planets(**birth)
client.indian.kundli.bhav_bala(**birth)
client.indian.kundli.shani_ashtam_shani(**birth)
client.indian.kundli.bhava_analysis(**birth)
client.indian.kundli.bhava_group_predictions(**birth)
client.indian.kundli.planet_remedies("sun", **birth)   # analysis_planet + birth

client.indian.match_making.ashtakoot_milan(
    p1_full_name="Groom", p1_day=1, p1_month=1, p1_year=1990,
    p1_hour=10, p1_min=0, p1_sec=0, p1_gender="male",
    p1_place="delhi", p1_lat=28.6, p1_lon=77.2, p1_tzone=5.5,
    p2_full_name="Bride", p2_day=5, p2_month=5, p2_year=1992,
    p2_hour=14, p2_min=0, p2_sec=0, p2_gender="female",
    p2_place="mumbai", p2_lat=19.07, p2_lon=72.87, p2_tzone=5.5,
)

client.indian.festival.chaitra_festivals(
    year=2024, place="delhi", lat=28.6, lon=77.2, tzone=5.5
)
client.indian.festival.english_calendar(
    year=2024, month=3, place="delhi", lat=28.6, lon=77.2, tzone=5.5
)
# festival is a lowercase snake_case slug from the DivineAPI festival list
client.indian.festival.find_festival(
    festival="maha_shivratri", year=2024,
    place="delhi", lat=28.6, lon=77.2, tzone=5.5
)
client.indian.festival.malayalam_festivals(
    year=2027, place="kochi", lat=9.9312, lon=76.2673, tzone=5.5
)
client.indian.festival.tamil_festivals(
    year=2027, place="chennai", lat=13.0827, lon=80.2707, tzone=5.5
)
client.indian.festival.sankranti_festivals(
    year=2027, place="new delhi", lat=28.6139, lon=77.2090, tzone=5.5
)

birth_w = dict(
    full_name="Jane Smith", day=15, month=6, year=1995,
    hour=8, min=0, sec=0, gender="female",
    place="new york", lat=40.7128, lon=-74.0060, tzone=-5.0,
)

client.western.natal.planetary_positions(**birth_w)  # 18 bodies incl. Vertex; see note below
client.western.natal.house_cusps(**birth_w)
client.western.natal.aspect_table(**birth_w)
client.western.natal.natal_wheel_chart(**birth_w)
client.western.natal.natal_insights(**birth_w)
client.western.natal.dominants(method="TRADITIONAL", **birth_w)
client.western.natal.persona_chart(persona_planet="moon", **birth_w)

# persona_chart: chart for the moment, within the first year of life, that the
# transiting Sun reaches the natal degree of persona_planet. output_include
# defaults to "raw_data" (~21 KB); image tokens are ~0.5 MB per SVG and
# output_include="all" returns ~4.3 MB.

client.western.synastry.planetary_positions(
    p1_full_name="Person A", p1_day=1, p1_month=1, p1_year=1990,
    p1_hour=10, p1_min=0, p1_sec=0, p1_gender="male",
    p1_place="london", p1_lat=51.5, p1_lon=-0.12, p1_tzone=0,
    p2_full_name="Person B", p2_day=15, p2_month=6, p2_year=1992,
    p2_hour=14, p2_min=0, p2_sec=0, p2_gender="female",
    p2_place="paris", p2_lat=48.85, p2_lon=2.35, p2_tzone=1,
)
client.western.synastry.emotional_compatibility(...)

client.western.transit.daily(**birth_w)
client.western.transit.planet_retrograde(
    planet="mercury", month=3, year=2024,
    place="new york", lat=40.71, lon=-74.0, tzone=-5.0,
)

# Chaldean numerology
client.numerology.loshu_grid(fname="John", lname="Doe", day=1, month=1, year=1990)
client.numerology.name_number(fname="John", lname="Doe", day=1, month=1, year=1990)
client.numerology.name_correction(full_name="John Doe", day=1, month=1, year=1990)

# Core numbers
client.numerology.core_numbers(
    full_name="John Doe", day=1, month=1, year=1990,
    gender="male", method="pythagorean",
)

# Mobile number analysis
client.numerology.new_mobile_number(fname="John", lname="Doe", day=1, month=1, year=1990)
client.numerology.analyze_mobile_number(
    fname="John", lname="Doe", day=1, month=1, year=1990,
    mobile_number="9876543210",
)

client.lifestyle.zodiac_gift_guru(sign="aries", h_day="today", tzone=5.5)
client.lifestyle.beauty_by_the_stars(sign="leo", h_day="today", tzone=5.5)
client.lifestyle.astro_chic_picks(sign="virgo", h_day="today", tzone=5.5)

client.calculators.flames(your_name="John", partner_name="Jane")
client.calculators.love_calculator(
    your_name="John", partner_name="Jane",
    your_gender="male", partner_gender="female",
)

# The API requires seven branding fields on every PDF request: company_name,
# company_url, company_email, company_mobile, company_bio, logo_url and
# footer_text (a few legacy reports also need company_landline).
# Pass company_mobile even though the SDK treats it as optional.
client.pdf.kundali_sampoorna(
    full_name="John", day=1, month=1, year=1990,
    hour=10, min=30, sec=0, gender="male",
    place="mumbai", lat=19.07, lon=72.87, tzone=5.5,
    company_name="YOUR_COMPANY_NAME", company_url="YOUR_COMPANY_URL",
    company_email="YOUR_COMPANY_EMAIL", company_mobile="YOUR_COMPANY_MOBILE",
    company_bio="YOUR_COMPANY_BIO",
    logo_url="YOUR_LOGO_URL", footer_text="YOUR_FOOTER_TEXT",
)

from divineapi import DivineApi, AuthenticationError, ValidationError, RateLimitError

client = DivineApi(api_key="...", auth_token="...")

try:
    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except ValidationError as e:
    print(f"Bad request: {e}")
except RateLimitError as e:
    print(f"Rate limited: {e}")

with DivineApi(api_key="...", auth_token="...") as client:
    result = client.horoscope.daily(sign="aries", h_day="today", tzone=5.5)