SDKs

Official clients for Python and TypeScript. Both are generated from the same OpenAPI specification that produces this documentation, so an operation cannot exist in the API and be missing from an SDK — CI fails if they drift.

Install#

pip install grahvani

npm install @grahvani/api

Neither has runtime dependencies. Python uses urllib from the standard library, so installing it cannot drag a requests version into your tree; TypeScript uses built-in fetch, so it works in Node 18+, Deno, Bun and edge runtimes.

Your first chart#

from grahvani import Grahvani

gv = Grahvani()                        # reads GRAHVANI_API_KEY

chart = gv.charts.rasi(birth={
    "date": "1980-05-01",
    "time": "05:16:00",                # omit entirely if unknown — we assume noon and say so
    "place": {"latitude": 27.1767, "longitude": 78.0081, "timezone": "Asia/Kolkata"},
})

print(chart.data["ascendant"])
print(chart.units, "units")
print(chart.provenance)

import { Grahvani } from "@grahvani/api";

const gv = new Grahvani();             // reads GRAHVANI_API_KEY

const chart = await gv.charts.rasi({
  birth: {
    date: "1980-05-01",
    time: "05:16:00",
    place: { latitude: 27.1767, longitude: 78.0081, timezone: "Asia/Kolkata" },
  },
});

console.log(chart.data, chart.meta.units, chart.provenance);

What the client does that a raw HTTP call does not#

Honours Retry-After on a 429. A client that ignores it turns a rate limit into an outage of its own making — and the header is authoritative, because only the server knows when the window resets.

Retries 5xx and connection failures with backoff and jitter. The jitter matters more than the backoff: a fleet that all started at the same moment will otherwise retry at the same moment, recreating the burst that caused the problem.

Never retries a 4xx. Your request is wrong, so sending it again is wrong again. On a metered API a retry loop over a 400 is a way to spend rate budget achieving nothing.

Drops unset optionals instead of sending null. This is not tidiness — an absent birth.time means "unknown, assume noon and tell me you did". A null is just a bad value, and the two must not collapse.

Validates path enums before the call, so a typo in a varga costs you nothing. In TypeScript that check is at compile time.

Errors are typed, and carry the doc URL#

The exception in your logs contains the address of the page that explains it.

from grahvani import InvalidRequestError, RateLimitError, NotAvailableInSchoolError

try:
    gv.charts.divisional("d9", birth=birth, ayanamsa="raman")
except NotAvailableInSchoolError as e:
    print(e.message)          # names the schools that DO implement it
except RateLimitError as e:
    time.sleep(e.retry_after)
except InvalidRequestError as e:
    print(e.field, e.doc_url)

The full surface#

Both SDKs expose the same nine operations under the same names.

Configuration#

Other languages#

There is no official client yet for Go, Java, Ruby or PHP. The OpenAPI 3.1 specification generates a working client for all of them through openapi-generator, and every endpoint page carries a cURL sample you can port directly.

If you need one of these supported properly, tell us which — that is what decides the order.