Metadata-Version: 2.4
Name: astromool
Version: 1.1.0
Summary: Official client for the AstroMool Vedic astrology API (Swiss Ephemeris charts, 90 calculators, PDF reports).
Author-email: AstroMool <developers@astromool.com>
License: MIT
Project-URL: Documentation, https://developers.astromool.com/docs
Project-URL: Homepage, https://developers.astromool.com
Project-URL: Source, https://github.com/astromool/astromool-python
Project-URL: Issues, https://github.com/astromool/astromool-python/issues
Keywords: astrology,vedic,kundli,jyotish,swiss-ephemeris,panchang,api
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# astromool (Python)

Official client for the [AstroMool API](https://developers.astromool.com/docs): Vedic charts computed from the
Swiss Ephemeris, the 90 astromool.com calculators, and the full PDF reports. Python 3.8+, standard library only.

```python
import os
from astromool import AstroMool, AstroMoolError

am = AstroMool(os.environ["ASTROMOOL_KEY"])     # am_test_... while you build, am_live_... in production

birth = {"date": "1995-08-14", "time": "10:35", "tz_id": "Asia/Kolkata", "lat": 25.5941, "lon": 85.1376}
chart = am.planets(birth)                         # {"data": ..., "meta": ...}
print(chart["data"]["ascendant"]["sign"], chart["meta"]["ayanamsa"])

m = am.calculators.run("manglik-dosha-calculator-by-date-of-birth", birth)
print(m["data"]["summary"])                       # "Manglik - intensity 18/100"
```

Every method returns the API's envelope. `meta` states the ayanamsa, the UTC offset used and the engine version;
read `meta["warnings"]` - it flags things like a birth time that did not exist because of a DST change.

## Methods

| Method | API |
|---|---|
| `planets(birth, ayanamsa=, node=)` | `POST /v1/vedic/planets` |
| `calculators.list()` / `calculators.run(slug, person, partner=, params=, detail=)` | `/v1/calculators` |
| `reports.create(slug, person, partner=, params=, lang=, webhook_url=, idempotency_key=)` | `POST /v1/reports/{slug}` |
| `reports.get(id)` / `reports.wait_until_ready(id, timeout=300)` / `reports.download(url)` | |
| `geo.search(q, limit)` / `geo.timezone(tz_id, date, time)` | `/v1/geo/*` |
| `meta.ayanamsas(date)`, `usage()`, `health()` | |

## Charts, dasha, panchang, matching and more (1.1.0)

```python
b = {"date": "1995-08-14", "time": "10:35", "place": "Patna"}   # or lat/lon/tz_id; "birth_time_unknown": True for a noon chart
am.vedic.chart(b); am.vedic.divisional(b, "D9"); am.vedic.ashtakavarga(b)
svg = am.vedic.chart_image(b, style="south", chart="D9")        # format="png" -> bytes
am.dasha.vimshottari(b); am.dasha.yogini(b)
am.panchang.day({"place": "Delhi"}, "2026-10-11")                # .rahu_kaal / .choghadiya / .hora
am.match.ashtakoot(groom, bride); am.numerology.core("Asha Verma", "1995-08-14")
am.dosha.check("mangal", b); am.dosha.summary(b); am.remedies.get("gemstone", b)
am.transit.natal(b); am.kp.chart(b); am.western.natal(b)
am.batch([{"path": "/v1/vedic/houses", "body": b}, {"method": "GET", "path": "/v1/usage"}])
am.topic("/v1/muhurat/vivah", {"person": {"place": "Delhi"}, "params": {"year": 2027}})   # any topic endpoint
```

## Reports

```python
r = am.reports.create("kundli-matching-by-date-of-birth", groom, partner=bride, lang="both")
ready = am.reports.wait_until_ready(r["data"]["report_id"])
open("report.pdf", "wb").write(am.reports.download(ready["data"]["download_url"]))
```

`reports.create` sends an `Idempotency-Key` (generated if you do not pass one), so a retry never creates a second report.

## Errors and retries

Failures raise `AstroMoolError` with `status`, `code` (stable - see the [errors page](https://developers.astromool.com/errors)),
`detail`, `request_id` and `field`. The client retries `rate_limited` (waiting `Retry-After`), 5xx answers and
network errors (`max_retries=2`). `quota_exceeded` is never retried.

## Webhooks

```python
from astromool import verify_webhook

@app.post("/astromool-hook")                       # Flask
def hook():
    event = verify_webhook(request.get_data(), request.headers.get("X-AstroMool-Signature"), os.environ["ASTROMOOL_WEBHOOK_SECRET"])
    return "", 200
```

Use the raw request bytes. The webhook secret is in the dashboard under Keys.

MIT licence.
