Kaal Jyoti APIGet a key

Why results differ

Two programs computing the same chart can disagree, and almost always for a reason that is a choice rather than a mistake. Here is every choice this API makes, so you can match it against whatever you are comparing with.

Work down the list: it is ordered by how much difference each one makes.

1. Ayanamsa#

The single biggest cause. The ayanamsa is the offset between the tropical and sidereal zodiacs, and the schools of Vedic astrology do not agree on it. Two common ones differ by a fraction of a degree — enough to move a planet at the edge of a sign into the next one, and enough to change a nakshatra pada.

This API offers 47 ayanamsas, each with a stable slug. The default is lahiri. Set it per request:

"options": { "ayanamsa": "true_chitra" }

GET /v1/reference/ayanamsas lists them all, and costs no credits.

Two things worth knowing:

  • Every answer reports the ayanamsa it used, with its value in degrees, in meta.ayanamsa — so a difference can be checked rather than argued about.
  • POST /v1/kp/chart defaults to krishnamurti, not lahiri. KP is defined on the Krishnamurti ayanamsa, and a KP chart computed on Lahiri would be quietly wrong. Name options.ayanamsa to override it.

2. The time zone the birth was read in#

Second biggest, and the one that produces the strangest differences, because an hour of error moves the ascendant by about fifteen degrees while leaving the planets almost where they were. If the ascendant disagrees and the grahas agree, suspect the zone before anything else.

The whole story, including India's 1942–45 war time, is on the time zones page. Historical offsets come from the platform's time-zone database rather than a table of our own, which is right far more often than it is convenient.

3. Sunrise, and everything measured from it#

The panchang is a day from sunrise to sunrise, and every muhurta window — rahu kaal, yamaganda, gulika, abhijit, the choghadiya and hora tables — is a division of the interval between sunrise and sunset. So a program that computes sunrise differently disagrees about all of them at once, usually by a few minutes.

This API uses the Hindu rising convention: the centre of the Sun's disc, crossing the horizon, with no correction for atmospheric refraction. Programs that use the ordinary civil convention — the upper limb of the disc, with refraction — will put sunrise a couple of minutes earlier and sunset a couple of minutes later, and every window derived from them will be shifted to match. This is the convention the Kaal Jyoti app uses, and the reason the API and the app agree.

Near the poles there may be no sunrise at all on a given day. When the search cannot resolve one, the answer falls back to what can be stated without it (the live tithi), and the fields that need a sunrise come back null rather than guessed at.

4. House system#

House numbers are whole sign from the lagna: the houses array on a kundli, the bhavas the vargas and the readings are read in. That is the classical Vedic default and what the app shows, and there is nothing to set.

If you are comparing against a program set to Placidus houses, the planets will match and the house numbers will not. That is the two of you using different systems, not an error in either.

Cusps are a separate question, with their own routes and their own system:

  • POST /v1/kundli/chalit serves four cusp systems — sripati (Porphyry madhyas), placidus, equal and kp — and returns all four when you do not name one.
  • POST /v1/kp/chart uses the KP cusps.
  • The kundli PDF (POST /v1/pdf/kundli) prints a bhava chalit in options.house_system, default Placidus; whole_sign and porphyry print a Sripati chalit. It is the only route whose options take a house system — sent to any other route, options.house_system is a 400 validation_error that names the field.

Above the polar circles#

Placidus is undefined above the polar circles, and the engine substitutes Porphyry cusps there rather than failing. So a Placidus chalit for a birth at, say, 70° N is really a Porphyry one. It is what the app does and what most astrology software does — but it is worth knowing before you compare such a chart with a program that refuses instead.

5. Where the positions come from, and how far they reach#

Planetary positions are computed from NASA JPL's DE440 planetary ephemeris — the numerical integration of the solar system that space missions are navigated with — reduced to apparent positions by Kaal Jyoti's own ephemeris library to the current IAU standards: IAU 2006 precession, IAU 2000A nutation and IAU 2006 sidereal time. The API answers for 1800 to 2400 CE; a year before 1800 or after 2400 is a 400 validation_error.

Other software can still differ from it, on the same ayanamsa, for four reasons. None of them is a mistake on either side; each is a choice.

  • The ephemeris file. Programs built on older ephemeris files (JPL's DE430 and DE431, or compressed files made from them) place the planets very slightly differently. Between 1850 and 2050 the planets agree to a fraction of an arcsecond — the last decimal places, not signs.
  • ΔT. A birth time is clock time, while the planets move in a uniform time scale; ΔT is the difference between the two, and it comes from the Earth's irregular rotation. This API uses the measured values from 1955 to the present (the IERS Earth orientation data), the published historical reconstruction of Stephenson, Morrison and Hohenkerk (2016) before 1955, and, after the last measured year, the recent trend carried forward with the long-term acceleration from the same paper. Nobody can measure ΔT for the future, so every program predicts it its own way: two predictions can be about ten seconds apart by 2100 and more than a minute apart by 2400, which moves the Moon by a few arcseconds in 2100 and by up to the better part of an arcminute in 2400. In the past the differences are fractions of a second.
  • Sidereal time. The ascendant and every house cusp depend on the Earth's rotation angle at the moment. This API uses the IAU 2006 model for every date. Software that switches to another model outside 1850–2050 will put the ascendant and cusps a few arcseconds away from these there.
  • What an ayanamsa's name means. An ayanamsa is defined by a value at an epoch (or by a star), carried forward by precession. Each of the 47 here has one fixed definition, and GET /v1/reference/ayanamsas lists them. The same name can mean different definitions in different programs — there are several "Lahiri"s (lahiri, lahiri_icrc, lahiri_1940, lahiri_vp285) — so compare the value in meta.ayanamsa with the one the other program reports before comparing anything else.

So a planet, a cusp or a dasha boundary that sits exactly on an edge can fall on the other side in another program, and the further a date is from the present, the likelier that is.

6. Ties, and other small print#

  • Events at the same instant. A transit scan can produce two events at the same moment — a conjunction with Ketu and an aspect on Rahu always coincide, since the nodes are opposite. Their order relative to each other is not meaningful; sort by whatever your display needs rather than relying on it.
  • Degrees exist only in D1. A divisional chart places a graha in a sign; it has no longitude of its own. POST /v1/kundli/chart answers with show_degrees: false for any varga but d1, whatever you asked for.
  • data is exactly what the engine computed. The gateway resolves the zone, validates, caches, attaches names and wraps the envelope — it does no arithmetic of its own. Strip the labels and you have the engine's document byte for byte, which is what its contract tests assert.

7. And it agrees with the app#

The engine behind this API is checked against the Kaal Jyoti app's own engine on ten thousand generated births before every release — the same charts, the same dashas, the same panchang, compared field by field. If an answer here differs from the app's, that is a bug and we want to hear about it.

Still not matching?#

Tell us the birth (date, time, place), the ayanamsa, what you expected and what you got, and which program you compared with — support. Nearly every report resolves to one of the six headings above, and the ones that do not are the interesting ones.