Documentation

FAQ

Q: What makes the Grahvani API different from other astrology APIs?

Every response can carry a provenance block naming the method used, the conventions applied, and the classical text and locus a rule comes from. Where published sources genuinely disagree — the yoni kūṭa grid is the live example — the response says so in provenance.disputed rather than presenting a contested number as settled. The correctness claims are checkable rather than asserted: KP horary reproduces Krishnamurti's published values exactly, and Vimśottarī matches Drik Pañcāṅga's 120-year cycle to within 26 seconds.

Q: How is the Grahvani API priced?

In units, not calls . Compute cost varies about twentyfold across the API, so a flat per-call price would either overcharge cheap requests or lose money on expensive ones. A rāśi chart is 1 unit, a daśā tree 3, an Aṣṭakūṭa report 10, and the two meta endpoints are free. Every response reports meta.units , so cost is never a surprise and never retroactive. Non-2xx responses are never billed.

Q: What happens if I send a birth time I am not sure about?

If you do not know the birth time, omit the field entirely rather than sending 00:00:00 or an empty string. Midnight is a real birth time and we will believe you. Omitting it returns the full chart — lagna, daśās, everything — computed for 12:00 noon, with meta.birth_time_assumed: true so you can disclose the assumption to your own user. We never refuse a reading for want of a birth time.

Q: Why must the timezone be an IANA name and not an offset?

Because a fixed offset such as "+05:30" cannot express a historical daylight-saving transition, and India observed DST as recently as 1945. For a birth inside such a window an offset silently shifts the whole chart by the length of the error — and an hour of error moves the ascendant about 15°, half a sign. Send "Asia/Kolkata" .

Q: What are the rate limits?

Per-plan, per minute, and always accompanied by a Retry-After header in seconds when you exceed them. A rate limit ( 429 rate_limit_exceeded ) means slow down and nothing was consumed; a quota exhaustion ( 429 quota_exhausted ) means your unit allowance for the billing period is spent and waiting seconds will not help. GET /v1/meta/usage reports both, free.

Questions we are actually asked, answered plainly. Each heading here is emitted as structured FAQPage data generated from this page's own text, so what a search engine shows and what you read are the same words.

What is Grahvani?#

Grahvani is Vedic astrology software built by AstroCorp Techlab Pvt Ltd. It has two faces: a workbench for practising astrologers at grahvani.in, and the Grahvani API at api.grahvani.in — the same computation core exposed to developers as a metered HTTP API. The API computes birth charts, divisional charts, Vimśottarī daśā, pañcāṅga, Krishnamurti Paddhati cusps and horary, and Aṣṭakūṭa compatibility.

What makes the Grahvani API different from other astrology APIs?#

Every response can carry a provenance block naming the method used, the conventions applied, and the classical text and locus a rule comes from. Where published sources genuinely disagree — the yoni kūṭa grid is the live example — the response says so in provenance.disputed rather than presenting a contested number as settled.

The correctness claims are checkable rather than asserted: KP horary reproduces Krishnamurti's published values exactly, and Vimśottarī matches Drik Pañcāṅga's 120-year cycle to within 26 seconds.

How is the Grahvani API priced?#

In units, not calls. Compute cost varies about twentyfold across the API, so a flat per-call price would either overcharge cheap requests or lose money on expensive ones. A rāśi chart is 1 unit, a daśā tree 3, an Aṣṭakūṭa report 10, and the two meta endpoints are free. Every response reports meta.units, so cost is never a surprise and never retroactive. Non-2xx responses are never billed.

Is there a free tier?#

Yes — 500 units per month and 5 requests per minute, with no card required. Separately, a gv_test_… key gives unlimited test mode: deterministic fixtures, never billed, never touching your live quota. Build your integration against test mode, then swap the key.

Which ayanāṁśa does the API use?#

Lahiri (Chitrapakṣa) by default, and it is by far the deepest school in the engine. Six are supported in total — lahiri, raman, yukteswar, bhasin, true_chitra and kp — but they are not equal in depth, and the gap is large enough to break an integration that assumes otherwise.

Call GET /v1/meta/capabilities — free, 0 units — before depending on a non-default school. If you request an operation a school does not implement, you get a 501 naming the schools that do. We never silently fall back to Lahiri, because a chart computed in a school you did not ask for is indistinguishable from one you did.

How accurate are the calculations?#

Positions come from the Swiss Ephemeris. The classical layers on top are implemented from published sources and checked against independent references where one exists:

KP horary numbers 37 and 206 reproduce Krishnamurti's own published values exactly.
Vimśottarī daśā matches Drik Pañcāṅga across a full 120-year cycle to within 26 seconds.
Graha Maitrī matches Bṛhat Parāśara Horā Śāstra Ch. 3 śl. 55 on all seven planets.

Where we cannot cite a source, provenance is omitted rather than invented.

Why do your daśā dates differ from another tool?#

Two independent causes, and it is worth knowing which is which. The ayanāṁśa variant outweighs everything else by roughly 40×; if dates differ by days, that is almost always why. The year length convention is the smaller cause — we use the sidereal year (365.256363 days), which is what matches Drik.

One tool in the market adds whole calendar years rather than a fixed day count, so no constant can ever reproduce its dates. That is structural, not a bug on either side.

What happens if I send a birth time I am not sure about?#

If you do not know the birth time, omit the field entirely rather than sending 00:00:00 or an empty string. Midnight is a real birth time and we will believe you.

Omitting it returns the full chart — lagna, daśās, everything — computed for 12:00 noon, with meta.birth_time_assumed: true so you can disclose the assumption to your own user. We never refuse a reading for want of a birth time.

Why must the timezone be an IANA name and not an offset?#

Because a fixed offset such as "+05:30" cannot express a historical daylight-saving transition, and India observed DST as recently as 1945. For a birth inside such a window an offset silently shifts the whole chart by the length of the error — and an hour of error moves the ascendant about 15°, half a sign. Send "Asia/Kolkata".

What are the rate limits?#

Per-plan, per minute, and always accompanied by a Retry-After header in seconds when you exceed them. A rate limit (429 rate_limit_exceeded) means slow down and nothing was consumed; a quota exhaustion (429 quota_exhausted) means your unit allowance for the billing period is spent and waiting seconds will not help. GET /v1/meta/usage reports both, free.

Do you store the birth data I send?#

Birth data is used to compute the response you asked for. We keep request metadata — the request_id, the endpoint, the units charged, the timestamp — because that is what billing and support require, and it is what you quote when something goes wrong.

Is the API versioned, and will it break?#

Everything is under /v1, and that contract freezes once customers depend on it. Additive changes happen within /v1; anything breaking waits for /v2, with /v1 supported for at least 12 months after a successor ships.

Can I get an SDK?#

Not yet as a published package. The OpenAPI 3.1 specification is the source of truth for this documentation and the CI contract tests, and it generates a working client through openapi-generator for most languages today. Request samples in cURL, Python, JavaScript and PHP are on every endpoint page.

What does a 501 mean here — is the endpoint broken?#

No. 501 not_available_in_school means the operation is real and the ayanāṁśa school is real, but we do not compute that operation in that school. The message names the schools that do.

It is deliberately not a 404, which would say "no such thing" and send you hunting for a typo in a path that is perfectly correct. See not_available_in_school.

Who operates the API, and where?#

AstroCorp Techlab Pvt Ltd, GSTIN 36AAMCC3512G1ZU, India. Exports of service are zero-rated under LUT. Payments are handled through Razorpay.

Introduction API reference Errors OpenAPI spec llms.txt

Grahvani API — a product of AstroCorp Techlab Pvt Ltd · GSTIN 36AAMCC3512G1ZU

Base URL https://api.grahvani.in