The Astrology API

Rooted in the classical texts

Charts and readings follow the Parashari tradition as taught in Brihat Parashara Hora Shastra, Phaladeepika, Saravali and Jataka Parijata. Marriage matching offers both the South Indian ten porutham method and the North Indian Ashtakoota guna count, and Vastu follows the sixteen zones and the forty five devtas of the Vastu Purusha Mandala.

Your key

Send your key in a request header with every call. Keys are kept only as a one-way fingerprint, so store the secret you were shown somewhere safe; if it ever leaks, revoke it and issue a new one from your console.

curl -H "X-API-Key: YOUR_KEY" \
  "https://YOUR_HOST/v1/astro/panchang/sunrise?date=20/10/2026&lat=13.0827&lon=80.2707&tz=5.5"

Fourteen languages, each in its own script

Add the language parameter to any call. Planets, signs, stars and every reading come back in that language's own script and its own traditional terms, never mixed with another script.

lang = en | ta | te | kn | hi | ml | sa | bn | gu | es | mr | pa | or | ur

curl -H "X-API-Key: YOUR_KEY" \
  "https://YOUR_HOST/v1/astro/horoscope/planet-details?dob=11/03/1994&tob=11:40&lat=13.0827&lon=80.2707&tz=5.5&lang=ta"

What you can call

Panchang for any day and place, the birth chart with its divisional charts, porutham and guna matching, Vimshottari and other dashas, dosha checks, daily to yearly horoscopes, numerology and Vastu basics. The full list with every parameter is in the reference below and in the downloadable description.

/v1/astro/panchang/...      panchang, sunrise, hora, choghadiya, festivals
/v1/astro/horoscope/...     planet-details, divisional-charts, ashtakvarga
/v1/astro/extended/...      extended-kundli-details, kp-planets, current-sade-sati
/v1/astro/matching/...      south-match (porutham), ashtakoot, dashakoot
/v1/astro/dashas/...        maha-dasha, antar-dasha, yogini-dasha-main, char-dasha-main
/v1/astro/dosha/...         mangal-dosh, kaalsarp-dosh, pitra-dosh
/v1/astro/prediction/...    daily-moon, weekly-moon, yearly, numerology
/v1/astro/utilities/...     radical-number-details, gem-details, geo-search
/v1/astro/vastu/zones       vastu basics
/v1/vastu/...               plot grid, entrance, score, ayadi

Full reports in three sizes

Ask for a complete reading built from our reviewed rule-based reading bank, or an AI narrative written over the very same chart facts. Each report comes as structured text, a designed document, a spoken reading or a chart film, and each of these comes small, medium or detailed.

curl -X POST "https://YOUR_HOST/v1/astro/report/natal" \
  -H "X-API-Key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"dob":"11/03/1994","tob":"11:40","lat":13.0827,"lon":80.2707,"tz":5.5,
       "lang":"hi","format":"pdf","size":"detailed"}'

format = json | pdf | audio | film
size   = small | medium | detailed
/v1/astro/report/{family}     rule based
/v1/astro/ai_report/{family}  AI narrative

Long work runs as a job

Add the async flag and the call answers at once with a job number. Check its status whenever you like, or give us an address and we will call it the moment the work is ready. Spoken readings and films always run this way.

POST /v1/astro/ai_report/natal
{ ..., "format": "audio", "size": "medium", "async": true,
  "webhook_url": "https://example.com/hooks/astro" }

202 { "status": "ok", "response": { "job": { "id": "...", "status": "queued",
      "poll_url": "/v1/astro/jobs/..." } } }

GET /v1/astro/jobs/{id}   queued | running | rendering | done | failed

Signed callbacks

Every callback carries a timestamp and a signature made with your key's own secret. Check the signature before you trust the message and reply quickly with a success code; if you cannot, we try again a few times with growing gaps.

// Node.js
const crypto = require('crypto');
function verify(rawBody, headers, secret) {
  const ts = headers['x-webhook-timestamp'];
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(ts + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headers['x-webhook-signature']));
}

Credits and credit packs

Each call uses credits from your plan's monthly allowance first, then from any credit packs you hold. Every answer tells you how many credits it used and how many remain, so there are no surprises.

X-Credits-Used: 8
X-Credits-Remaining: 9992

"meta": { "credits": 8, "remaining": 9992, "request_id": "..." }

Fair use limits

Each key has a per minute limit set by its plan. Go past it and the call is politely refused with a clear code and a hint of when to try again.

HTTP/1.1 429
Retry-After: 60
X-RateLimit-Limit: 60

{ "status": "error", "error": { "code": "rate_limited", "message": "..." } }

Safe retries

When you send a request that creates something, add your own unique request key. If the network drops and you send it again, you receive the first answer and are never charged twice.

curl -X POST "https://YOUR_HOST/v1/astro/report/match" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Idempotency-Key: order-2026-10-20-0001" \
  -d '{ ... }'

Idempotent-Replayed: true   (on a repeated request)

One shape for every error

Every refusal has the same shape: a short code you can act on, a plain message and, where it helps, the name of the parameter to fix.

{
  "status": "error",
  "error": { "code": "param_missing", "message": "...", "param": "tob" },
  "meta": { "request_id": "..." }
}

Stable versions

The version is part of the address, so your integration keeps working as we grow. New fields may appear in answers; anything that could break your code arrives only in a new version.

https://YOUR_HOST/v1/astro/...
Api-Version: 1          (optional request header)
X-Api-Version: 1.0.0    (every answer)

The reading bank

On plans that include it, you can read our whole reviewed reading bank section by section and page by page, in every language and in full, to build experiences of your own.

GET /v1/astro/content/sections?lang=ta
GET /v1/astro/content/blocks?section=yogas&lang=ta&limit=100
GET /v1/astro/content/blocks?section=yogas&lang=ta&cursor=NEXT_CURSOR

AI narrative, firmly grounded

AI reports are written only from the calculated chart and the reviewed readings, then checked for script and tone before they reach you. Partners can use our models, or bring their own provider key where their plan allows it.

Machine readable description

Download the full description to generate a client in your favourite language, or to explore every endpoint in the tool you already use.

GET https://YOUR_HOST/v1/astro/openapi.json
GET https://YOUR_HOST/v1/astro/catalog