asterwise-python

The official Python library for Asterwise — Vedic + Western astrology, numerology, tarot, crystals, and dreams. 131 endpoints, generated from the API's OpenAPI document so the types match what the server sends. Every position is checked against NASA JPL Horizons, median 0.050 arcseconds over 80 positions from 1950 to 2050. Compared row by row with seven other astrology APIs, every claim sourced, at asterwise.com/compare.

Documentation · API Reference · Pricing · MCP server · Postman collection

Installation

pip install asterwise

Quickstart

import asterwise
from asterwise.api.astrology_api import AstrologyApi

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

with asterwise.ApiClient(configuration) as client:
    api = AstrologyApi(client)
    result = api.natal_chart(
        asterwise.NatalRequest(
            date="1985-11-12",
            time="06:45",
            location="Mumbai, India",
            ayanamsa="lahiri",
        )
    )
    print(result)

Get a free API key at asterwise.com.

What you can build

143 typed SDK methods across 13 API classes covering 131 REST endpoints (5 endpoints keep a deprecated GET method next to the POST one; 7 place-and-date endpoints have a cacheable GET twin).

What makes Asterwise different

• Classical interpretation text alongside the calculations on chart endpoints (natal chart, dasha, yogas, doshas)
• 5-level Vimshottari Dasha (Maha → Antar → Pratyantar → Sookshma → Prana) — most APIs return two
• Rajju and Vedha as hard vetoes in matchmaking — not just point scores
• HMAC-signed responses for auditability
• Panchanga as printed panchangs show it: every tithi, nakshatra, yoga and karana of the day with start and end times, the festival and vrat calendar, and muhurta search with exact ISO times
• Typed responses: every method returns a model generated from the OpenAPI document (.to_dict() gives a plain dict)
• MCP server with 108 tools for Claude and Cursor integration

Examples

from datetime import date
from asterwise.api.western_astrology_api import WesternAstrologyApi
from asterwise.api.numerology_api import NumerologyApi
from asterwise.api.tarot_api import TarotApi

with asterwise.ApiClient(configuration) as client:
    western = WesternAstrologyApi(client)
    chart = western.western_natal_chart(
        asterwise.WesternNatalRequest(
            date="1985-11-12",
            time="06:45",
            location="Mumbai, India",
        )
    )

    numerology = NumerologyApi(client)
    path = numerology.life_path_post(asterwise.LifePathRequest(date=date(1985, 11, 12)))

    tarot = TarotApi(client)
    spread = tarot.tarot_three_card(
        asterwise.SpreadRequest(question="What should I focus on this month?")
    )

Requirements

Python 3.10+. An API key from asterwise.com.

Documentation

Full API reference: docs.asterwise.com

Development

Regenerate from https://api.asterwise.com/openapi-sdk.json (see asterwise-api/_docs/SDK_CONTRACT.md).

Requirements: Node.js/npm (for npx), Java 11+ for OpenAPI Generator.

bash scripts/generate.sh

Releasing: bump version in pyproject.toml (the only place it is set) → bash scripts/generate.sh (writes that version into __version__ and the User-Agent) → update CHANGELOG.md → pytest → commit → push a python-v<version> tag. The publish workflow checks the tag against pyproject.toml, runs the tests, builds, runs twine check and uploads to PyPI.

Support

support@asterwise.com

License

MIT. See LICENSE.