# AstroAsk

> Astrology calculation API: Vedic (planets, houses, nakshatra, dasha, doshas, panchanga, muhurta), Western (natal, aspects, synastry, transits, progressions), compatibility scoring, and chart rendering (SVG/PNG). 94 documented endpoints, each computing exactly one thing — including numerology (Pythagorean + Chaldean) and Western composite/Davison charts, Arabic lots, midpoints, and retrograde calendars. Returns structured JSON with full double-precision numbers computed via Swiss Ephemeris. 21 languages. One unified plan — every call to every endpoint costs exactly 1 request.

## Essentials

- Base URL: https://api.astroask.app/v1 (alias: /api/v1)
- Auth: `X-API-Key: ak_...` or `Authorization: Bearer ak_...`
- Envelope: `{ "success": true, "data": ... }` on 2xx; `{ "success": false, "error": "CODE", "message": "..." }` otherwise
- Input: POST JSON `{ "date": "1990-01-15T10:30:00", "lat": 28.6139, "lng": 77.2090 }` — date is local time at the coordinates; timezone is resolved server-side
- OpenAPI spec: https://api.astroask.app/openapi.json
- Full docs text (every guide, for deep context): https://developers.astroask.app/llms-full.txt
- Trial: signup at https://developers.astroask.app/signup issues a key instantly (5,000 requests / 14 days, no card)

## Key endpoint families

- POST /v1/ascendant, /v1/moon-sign, /v1/sun-sign, /v1/nakshatra, /v1/planets, /v1/houses/vedic, /v1/navamsa — the Vedic birth chart as precise single-purpose calls; combine them via /v1/batch to assemble a full chart in one HTTP request
- POST /v1/dasha/vimshottari, /v1/dasha/current — planetary periods
- POST /v1/dosha/manglik, /v1/dosha/kaal-sarp, /v1/sade-sati — dosha verdicts with structured fields
- GET  /v1/panchanga (+ /tithi /nakshatra /yoga /karana), /v1/choghadiya, /v1/hora, /v1/kala — daily almanac and time windows
- POST /v1/compatibility, /v1/compatibility/ashtakoot, /v1/compatibility/summary — Vedic matchmaking (36-point Ashtakoot)
- POST /v1/western — complete tropical natal chart; /v1/western/planets, /v1/western/aspects, /v1/western/transits, /v1/western/progressions, /v1/western/synastry (+ /themes)
- POST /v1/chart/north-indian, /v1/chart/western-wheel — chart images as SVG or PNG (base64)
- POST /v1/batch — up to 50 calculations in one request (direct API only; costs N quota units)
- GET  /v1/geo/search — city geocoding for birth-place lookup

## Behavior notes for agents

- Numbers are real JSON numbers at full precision (e.g. 331.43152605600557) — never strings, never rounded
- Rate limiting: 429 RATE_LIMITED (retry after Retry-After seconds) vs 429 QUOTA_EXCEEDED (monthly, wait for UTC month reset) vs 402 TRIAL_EXPIRED (hard stop, subscribe)
- Quota headers on every response: X-RateLimit-Limit / -Remaining / -Reset / -RPS
- `lang` parameter accepts: en hi bn ta te kn ml mr gu pa or es pt fr de it ru ar ja ko zh
- Optional `fields` array (dot-paths) on /western, /compatibility, /muhurat trims the response
- Granular model: there is no all-in-one chart bundle endpoint — request the calculations you need individually, or via /v1/batch (each batch item costs 1 request)

## Docs

- https://developers.astroask.app/docs — guides (quickstart, auth, rate limits, errors, batch, concepts)
- https://developers.astroask.app/docs/api — full endpoint reference