Reports and horoscope

These routes return written readings rather than numbers. The text is written and reviewed by an astrologer, in English and Hindi, from the classical rules the engine already computes — and it never pretends to more precision than it has: there are no percentages, scores or lucky numbers.

Each reading costs 5 credits, and the kundli report costs 5 credits per part it contains (40 for the whole report). All of them are on every plan, Free included.

A lagna or nakshatra reading#

With a birth, the engine finds the lagna (or the Moon's nakshatra) and reads it. Without one, name it — a "know your lagna" page needs no birth details at all:

POST /v1/reports/lagna
{ "sign": "leo", "options": { "language": ["en", "hi"] } }

{
  "status": "ok",
  "data": {
    "lagna": {
      "sign": { "id": "leo", "name": "Leo", "names": { "en": "Leo", "hi": "सिंह" } },
      "entry": {
        "text": {
          "en": "With Leo rising, the Sun is the lord of your lagna…",
          "hi": "सिंह लग्न होने पर आपके लग्न के स्वामी सूर्य हैं…"
        }
      }
    },
    "disclaimer": {
      "en": "These predictions are indicative. For a reading of your own chart, consult an astrologer.",
      "hi": "ये फलादेश सांकेतिक हैं। …"
    }
  }
}

House by house#

POST /v1/reports/house-lords takes a birth and answers twelve readings in house order: the sign on each house, its lord, the house the lord sits in (whole-sign, counted from the lagna), and what that placement says about that area of life — the "promise" of the chart.

{
  "house": 1,
  "sign": { "id": "gemini", "name": "Gemini" },
  "lord": { "id": "mercury", "name": "Mercury" },
  "in_house": 9,
  "entry": { "text": { "en": "Your lagna lord in the 9th, the house of fortune and dharma, …" } }
}

Life areas#

POST /v1/reports/life-areas reads the birth chart by area of life rather than house by house: you yourself, wealth, courage and siblings, home and property, education, children, health, marriage, fortune, career, and foreign lands and spending. Each is one summary for the reader — how strongly the chart promises that area (level: favourable, mixed or care), the main reason in plain words, and the mahadasha that brings it forward, with its dates. A one-line summary names the strongest areas and any that need care.

This is the report for a client. The house-by-house (/v1/reports/house-lords) and graha-by-graha (/v1/reports/grahas) readings are the detail behind it, for the astrologer; each area's basis links the two — the house lord and its role for the lagna, the grahas in and aspecting the house, the karakas and the yogas.

Grahas and yogas#

POST /v1/reports/grahas answers the nine grahas, Sun to Ketu: the sign each is in, the house (whole-sign, from the lagna), and two readings — what the graha says in that sign (in_sign) and in that house (in_house).

POST /v1/reports/yogas answers the yogas and doshas the chart forms — Raj, Dhana, Chandra, Mahapurusha, Parivartana and the rest — each with its category, the grahas that form it (participants) and a reading. A dosha no classical verse states (Kaal Sarp, Grahan, Angarak) is not read here, though POST /v1/kundli/yogas still lists it when the chart has it.

Vimshottari#

POST /v1/reports/vimshottari takes a birth and reads every Vimshottari mahadasha from birth to age 80. Each is one summary, not a list of antardashas: the mahadasha named (lord), its dates, a level — favourable, mixed or care — and a text that says what the period is like, which areas of life it brings forward, and its best and most demanding stretches with their dates. current marks the one running now.

Each period also lists its antardashas, with their dates, a grade from −3 to +3 and the reasons — for you or your astrologer, not for the reader. The judgement follows Laghu Parashari (slokas 29–40): each graha's role for the lagna, and whether the lords of the mahadasha and antardasha are related.

Varshphal#

POST /v1/reports/varshphal takes a birth and a year and reads the year from that birthday to the next by the Tajika rules (K. S. Charak): one summary — the year's tone, from the year lord and its strength, and where the year centres — and one reading for each of work, money, relationships, health, education, home and travel, each with a level (favourable, mixed or care). months are the year's periods (the mudda dasha), each with its dates and level; the best and most demanding stretches are named with their dates in the summary.

The birth chart decides what the year can bring: an area the birth chart does not promise is never read above mixed. The reasons — the year lord, the muntha, the Tajika yogas behind each area — are in basis.

The whole report#

POST /v1/reports/kundli is the written birth report in one request — what the PDF kundli prints. It holds eight parts, and each is exactly what its own route answers for the same birth:

Send parts to take only some of them (default all eight, each named once), and year for the Varshphal (default this year; never before the birth year). The answer lists what it holds in parts, in the order above — read the order from there, not from the keys — then one key per part and one disclaimer for the whole report:

POST /v1/reports/kundli
{ "birth": { … }, "parts": ["lagna", "yogas", "varshphal"], "year": 2026 }

{
  "status": "ok",
  "data": {
    "parts": ["lagna", "yogas", "varshphal"],
    "lagna": { "sign": { "id": "gemini", … }, "entry": { "text": { "en": "…" } } },
    "yogas": [ … ],
    "varshphal": { "year": 2026, "summary": { … }, "areas": [ … ], "months": [ … ], … },
    "disclaimer": { "en": "These predictions are indicative. …" }
  },
  "meta": { "credits": 15, … }
}

It costs 5 credits per part — 15 here, 40 for the whole report — the same as calling those reports one by one, because it is those reports. The whole price is reserved before anything is computed (so a report that does not fit in what you have left is refused with 402 and costs nothing), and meta.credits says what the request cost. A refused request costs nothing, as always.

A horoscope by sign#

The reader picks their Moon sign. The engine weighs every graha's transit over the period — counted as a house from that sign — and answers one summary per life area, not a list of transits: what a reader wants is the final reading, not nine placements to reconcile.

POST /v1/horoscope
{ "sign": "cancer", "period": "monthly", "date": "2026-06-01", "options": { "language": "en" } }

{
  "summary": {
    "level": "care",
    "text": { "en": "This month, things may move more slowly than you would like…" }
  },
  "areas": [
    {
      "area": "work",
      "level": "care",
      "text": {
        "en": "This month, recognition at work may be slow to come… Until 15 June, a new position or honour is possible…"
      }
    }
  ],
  "basis": [
    {
      "graha": { "id": "jupiter" },
      "sign": { "id": "gemini" },
      "house": 12,
      "nature": "unfavourable",
      "leaves": "2026-06-…"
    }
  ]
}

• summary is the overall reading; areas are work, money, relationships, health, education, always in that order.
• level is favourable, mixed or care. There are no scores or percentages.
• Each text opens with that tone, then says what helps and what to watch, and dates a change that falls inside the period ("Until 15 June, …").
• basis is the transits behind it — graha, sign, house, favourable or unfavourable, and the exact instants (entered, leaves). It is for you (or the astrologer on your site), not for the reader; the text never names a graha or a house.
• period is daily (the default), weekly (seven days from date), monthly (the calendar month) or yearly (the calendar year). The slow grahas — Jupiter, Saturn, Rahu and Ketu — weigh most; the Moon counts only in a daily horoscope; a yearly one is the slow grahas alone.
• Days run from local midnight to local midnight in timezone (default Asia/Kolkata) or utc_offset. date defaults to today there.

Languages#

Every piece of text is an object keyed by language, holding the languages in options.language in the order you asked for them: {"hi": "…"}, or {"en": "…", "hi": "…"}. The shape is the same either way, so text.hi always works when you asked for Hindi.

The disclaimer#

Every reading ends with a disclaimer line unless you turn it off. It is on by default because these are general readings, not a reading of anyone's whole chart.

Turn it off when an astrologer is handing the reading to their own client; name yourself when the reading is on your site.

See also time zones for how date and timezone are read.