AstroNest — Vedic Astrology & Ephemeris

Official19 tools

by onedotlinks · TypeScript

Vedic astrology for AI agents: kundli, daśā, guna milan, life, venture and gem readings, ephemeris.

MCP Server: io.github.onedotlinks/astronest

The io.github.onedotlinks/astronest MCP server provides Vedic astrology capabilities for AI agents. It supports generating and working with astrological data including charts, daśā (dashas), readings, and muhūrta. Ephemeris calculations are based on the JPL DE440 dataset.

🛠️ Key Features

Charts
Daśā
Readings
Muhūrta
JPL DE440 ephemeris

🚀 Use Cases

Provide Vedic astrology charts to AI agents
Compute or reference daśā-related information
Generate astrology readings for agent workflows
Determine muhūrta using DE440 ephemeris data

⚡ Developer Benefits

Structured astrology inputs for AI agent integration
Consistent ephemeris source via JPL DE440
Narrow focus on core Vedic astrology primitives (charts, daśā, readings, muhūrta)

⚠️ Limitations

Server scope is limited to Vedic astrology items listed in its description
No additional tooling details, capabilities, or counts are provided

Topics

apiastrologyhoroscopejyotishkundlimcpmcp-servermodel-context-protocolnextjsvedic-astrology

Captured live from the server via tools/list.

get_chart

Use this when the user wants their birth chart (kundli): ascendant, planets in signs and houses, yogas, the current planetary periods, or a divisional chart such as the navāṁśa (D9). Sidereal (Lahiri) chart: ascendant, the nine grahas, twelve houses, yogas and the Vimśottarī daśā. A modern Western block is added unless `western` is false. With `location`, also astrocartography lines at that place and the chart's own frame relocated there. Includes the D9 and D10 divisional charts by default; ask for any of the sixteen ṣoḍaśavarga with `divisionals`. Cost: 1 credit per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}

Parameters5

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
includeDasha	boolean	optional	Include the Vimśottarī daśā periods in the chart response. Default true.
western	boolean	optional	Set false to omit the modern Western block.
location	object	optional	Both coordinates or neither: a half-filled location is refused, never defaulted.
divisionals	array	optional	Divisional charts (vargas) to include: any of the sixteen ṣoḍaśavarga. Default d9 (navāṁśa) and d10 (daśāṁśa); send [] for none. Each returns its ascendant and every graha's sign, degree and house within the varga, by the Parāśari formulas.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "includeDasha": {
      "type": "boolean",
      "default": true,
      "description": "Include the Vimśottarī daśā periods in the chart response. Default true."
    },
    "western": {
      "type": "boolean",
      "default": true,
      "description": "Set false to omit the modern Western block."
    },
    "location": {
      "type": "object",
      "description": "Both coordinates or neither: a half-filled location is refused, never defaulted.",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "orbDegrees": {
          "type": "number",
          "default": 3,
          "maximum": 15
        }
      }
    },
    "divisionals": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "d1",
          "d2",
          "d3",
          "d4",
          "d7",
          "d9",
          "d10",
          "d12",
          "d16",
          "d20",
          "d24",
          "d27",
          "d30",
          "d40",
          "d45",
          "d60"
        ]
      },
      "default": [
        "d9",
        "d10"
      ],
      "description": "Divisional charts (vargas) to include: any of the sixteen ṣoḍaśavarga. Default d9 (navāṁśa) and d10 (daśāṁśa); send [] for none. Each returns its ascendant and every graha's sign, degree and house within the varga, by the Parāśari formulas."
    }
  },
  "required": [
    "birthData"
  ]
}

get_dasha

Use this when the user asks which planetary period (daśā) they are in, when it ends, or which periods are coming. The current periods include the running pratyantardaśā; send depth 'pratyantardasha' for the full timeline at that level. Cost: 1 credit per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}

Parameters2

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
depth	string	optional	Timeline depth. 'pratyantardasha' nests the pratyantardaśās under each antardaśā (about ten times larger). The current periods always include the running pratyantardaśā.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "depth": {
      "type": "string",
      "enum": [
        "antardasha",
        "pratyantardasha"
      ],
      "default": "antardasha",
      "description": "Timeline depth. 'pratyantardasha' nests the pratyantardaśās under each antardaśā (about ten times larger). The current periods always include the running pratyantardaśā."
    }
  },
  "required": [
    "birthData"
  ]
}

get_guidance

Use this when the user asks how to conduct themselves in the period they are in: what to do and what to take care with, each with its classical reason. Guidance, not prediction. Plain-language guidance cards for each running daśā level (mahādaśā, antardaśā, …) at `referenceDate` (default: now). Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}

Parameters2

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
referenceDate	string	optional	ISO date or datetime. Defaults to now.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "referenceDate": {
      "type": "string",
      "description": "ISO date or datetime. Defaults to now."
    }
  },
  "required": [
    "birthData"
  ]
}

interpret_domain

Use this when the user asks what their chart says about one area of life (career, marriage, finance, health, property, children, education, travel, legal and others) and a reproducible verdict with its reasons and sources is wanted. Prefer it to get_forecast when no written narrative is needed. Deterministic reading of one life area: the verdict, the factors for and against it, timing windows, whether the engine's own methods agree, and the classical books the reading draws on. Every layer is declared as present, computed_empty, not_covered or failed, so nothing is silently missing. No language model is called: the same chart always gets the same reading. Cost: 5 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"domain":"career"}

Parameters2

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
domain	string	required	Life area to read, e.g. career, marriage, finance or health.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "domain": {
      "type": "string",
      "enum": [
        "career",
        "business",
        "finance",
        "children",
        "property",
        "education",
        "travel",
        "spirituality",
        "lineage",
        "reputation",
        "partnerships",
        "legal",
        "family",
        "marriage",
        "health"
      ],
      "description": "Life area to read, e.g. career, marriage, finance or health."
    }
  },
  "required": [
    "birthData",
    "domain"
  ]
}

get_life_reading

Use this when the user wants their life as a whole: which life areas (marriage, children, career, business, money, property, family, travel, education, spirituality, health) are in focus when, across past and future, and where life stands now. The life's chapters (each mahādaśā in plain words, with dates and ages) and eleven life areas, each with the planets that govern it on this chart, every governing period past and future with why that planet governs it, and what is in focus now and next. Past periods are included, so the reading can be tested against a life already lived; send `recorded` events to place them on the timeline. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required. The full reading is large; pass `areas` to return only the life areas you need. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"areas":["career","relationship"],"recorded":[{"type":"job_start","date":"2012-07-01","certainty":"exact"},{"type":"marriage","date":"2018-11-25","certainty":"exact"}]}

Parameters3

birthData	object	required	The person's birth data. The time is required: every period depends on the rising sign.
recorded	array	optional	Optional dated life events to place on the timeline.
areas	array	optional	Optional: only these life areas (default all eleven). The full reading is large, so an AI agent answering about one area should pass it here.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data. The time is required: every period depends on the rising sign."
    },
    "recorded": {
      "type": "array",
      "maxItems": 100,
      "description": "Optional dated life events to place on the timeline.",
      "items": {
        "type": "object",
        "required": [
          "type",
          "date"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "marriage",
              "relationship_end",
              "loss_or_separation",
              "child_birth",
              "child_loss",
              "job_start",
              "job_loss",
              "business_start",
              "education_start",
              "education_end",
              "property_event",
              "relocation",
              "legal_event",
              "health_period",
              "other"
            ]
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "certainty": {
            "type": "string",
            "enum": [
              "exact",
              "approximate",
              "year"
            ],
            "default": "approximate"
          }
        }
      }
    },
    "areas": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "relationship",
          "children",
          "education",
          "career",
          "business",
          "money",
          "property",
          "family",
          "travel",
          "spirituality",
          "health"
        ]
      },
      "description": "Optional: only these life areas (default all eleven). The full reading is large, so an AI agent answering about one area should pass it here."
    }
  },
  "required": [
    "birthData"
  ]
}

get_domain_timeline

Use this when the user asks about one area of life — when marriage, children, career, money, property or another area is in focus, or what a given stretch of years holds for it. One life area across the whole life: the planets that govern it on this chart, every period that brings it into focus (past and future, with dates, ages and why that planet governs it), and what is in focus now and next, in plain words. Pass `window` to get only the periods that overlap a date range. It is the same reading as the whole-life reading, cut to one area, so the two never disagree. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required. Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"area":"relationship","window":{"from":"2026-01-01","to":"2031-12-31"}}

Parameters3

birthData	object	required	The person's birth data. The time is required: every period depends on the rising sign.
area	string	required	The life area.
window	object	optional	Optional: only periods overlapping this date range (YYYY-MM-DD). Default: the whole life.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data. The time is required: every period depends on the rising sign."
    },
    "area": {
      "type": "string",
      "enum": [
        "relationship",
        "children",
        "education",
        "career",
        "business",
        "money",
        "property",
        "family",
        "travel",
        "spirituality",
        "health"
      ],
      "description": "The life area."
    },
    "window": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "properties": {
        "from": {
          "type": "string",
          "format": "date"
        },
        "to": {
          "type": "string",
          "format": "date"
        }
      },
      "description": "Optional: only periods overlapping this date range (YYYY-MM-DD). Default: the whole life."
    }
  },
  "required": [
    "birthData",
    "area"
  ]
}

get_relationship_reading

Use this when the user asks how two people get on in a bond other than marriage — business partners, siblings, a parent and child, or friends. Reads the bond the way the classical method reads it: the houses that govern this kind of bond and their lords in each chart, the natural significators, whose planets fall in whose governing houses, and whether that reach runs both ways, plus the running periods in each chart that engage the bond. A bond meter (strong tie, workable or strained) is computed by a stated convention and returned with every point it is built from; it is not a classical score, since the texts give no arithmetic for a business or sibling match. Deterministic: no language model is called. Both birth times are required. For marriage, use the compatibility tool. Cost: 8 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"type":"business","a":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209,"name":"A"},"b":{"date":"1991-11-03","time":"06:10","timezone":"Asia/Kolkata","latitude":19.076,"longitude":72.8777,"name":"B"}}

Parameters3

type	string	required	The bond. For marriage, call /v1/compatibility.
a	any	required	First person: birth data (time required) plus optional name.
b	any	required	Second person: birth data (time required) plus optional name.

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "business",
        "sibling",
        "parent_child",
        "friend"
      ],
      "description": "The bond. For marriage, call /v1/compatibility."
    },
    "a": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "First person: birth data (time required) plus optional name."
    },
    "b": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "Second person: birth data (time required) plus optional name."
    }
  },
  "required": [
    "type",
    "a",
    "b"
  ]
}

get_venture_timing

Use this when the user asks when to start, launch, sign, borrow or expand a business, or which line of business their chart supports. A calendar of the coming months in four labels — commit (sign, open, launch), build (keep building; commit only what can be undone), guarded (low fixed cost; no lease, no borrowing) and hold (no new fixed commitments) — each window with the daśā period running and the slow transits of Saturn and Jupiter over it, and the reasons. Describe the businesses being weighed in `ventures` and each is ranked on how strongly the chart supports it and whether the coming periods carry it, with the grounds, its best coming period, and a caution when it needs premises during a hold; name none and the full catalogue of business types is ranked. A ranking of chart support, never a probability of success. Deterministic: no language model is called. The birth time is required. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"ventures":["software and data platform for businesses","a restaurant in a leased storefront","OneDot"],"months":36}

Parameters3

birthData	object	required	The person's birth data. The time is required: every period depends on the rising sign.
ventures	array	optional	Optional: the businesses being weighed, each described by what it does ("software for accountants", "a café with a leased storefront"). A brand name alone cannot be placed and is returned as unclassified. Omit to rank the whole catalogue.
months	integer	optional	How far ahead the calendar runs, and the horizon each venture's period support is averaged over.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data. The time is required: every period depends on the rising sign."
    },
    "ventures": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 200
      },
      "description": "Optional: the businesses being weighed, each described by what it does (\"software for accountants\", \"a café with a leased storefront\"). A brand name alone cannot be placed and is returned as unclassified. Omit to rank the whole catalogue."
    },
    "months": {
      "type": "integer",
      "minimum": 6,
      "maximum": 72,
      "default": 36,
      "description": "How far ahead the calendar runs, and the horizon each venture's period support is averaged over."
    }
  },
  "required": [
    "birthData"
  ]
}

assess_gemstone

Use this when the user asks whether they should wear a particular gemstone (blue sapphire, emerald, pukhraj, a crystal), or whether a stone they wear suits their chart. Answers the prescription, not the future: which planet the stone strengthens, what that planet owns from this ascendant, whether a classical rule (a dusthāna or kendrādhipati lordship, a māraka) argues against strengthening it, and whether the reason is permanent or lasts only as long as the running period. Returns a verdict — well_founded, period_bound, no_ground, contraindicated or unrecognised — with every ground for and against, the planet's capacity at its degree, when the chart puts the planet in scope, the stones the sources hold apart from it (checked against `alsoWearing`), and wearing detail (finger, metal, day, weight, with the book it comes from) only when the chart gives a reason to wear it. When the source states a caution about the stone, the response says so and names the book. A word that covers several stones ("sapphire") is answered with the candidates. Nothing here predicts what a stone does. Deterministic: no language model is called. The birth time is required. Cost: 5 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"gem":"blue sapphire","alsoWearing":["ruby"]}

Parameters3

birthData	object	required	The person's birth data. The time is required: every period depends on the rising sign.
gem	string	required	One stone, in English or by its Indian name: "yellow sapphire", "pukhraj", "emerald", "moonstone".
alsoWearing	array	optional	Optional: stones already worn. When the chart puts the planet in scope, a pairing the sources hold apart is reported as a conflict.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data. The time is required: every period depends on the rising sign."
    },
    "gem": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60,
      "description": "One stone, in English or by its Indian name: \"yellow sapphire\", \"pukhraj\", \"emerald\", \"moonstone\"."
    },
    "alsoWearing": {
      "type": "array",
      "maxItems": 9,
      "items": {
        "type": "string"
      },
      "description": "Optional: stones already worn. When the chart puts the planet in scope, a pairing the sources hold apart is reported as a conflict."
    }
  },
  "required": [
    "birthData",
    "gem"
  ]
}

get_compatibility

Use this when the user asks whether two people are a good match for marriage and wants the full reading, not only a score. For the fast 36-point score with Manglik alone, use get_guna_milan. Both charts read together for marriage. The 36-point Aṣṭakūṭa (guna milan) is one input: the verdict names the governing factor and says when it outweighs the score. Also returned: each chart's marital promise, sustainability and happiness, progeny, Manglik reckoned from the lagna, the Moon and Venus with mutual cancellation, a joint marriage-timing window, synastry, and caveats where an uncertain birth time would change the reading. Deterministic: no language model is called. Each partner is a BirthData object plus optional `name` and `gender`. Cost: 12 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"a":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209,"name":"A"},"b":{"date":"1991-11-03","time":"06:10","timezone":"Asia/Kolkata","latitude":19.076,"longitude":72.8777,"name":"B"}}

Parameters3

a	any	required	First partner: birth data plus optional name and gender.
b	any	required	Second partner: birth data plus optional name and gender.
referenceDateIso	string	optional	ISO date the reading is anchored to. Defaults to now.

Raw schema

{
  "type": "object",
  "properties": {
    "a": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "First partner: birth data plus optional name and gender."
    },
    "b": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "Second partner: birth data plus optional name and gender."
    },
    "referenceDateIso": {
      "type": "string",
      "description": "ISO date the reading is anchored to. Defaults to now."
    }
  },
  "required": [
    "a",
    "b"
  ]
}

get_guna_milan

Use this when the user asks for the guna milan / kundli matching score (out of 36), or whether either person is Manglik. The classical Aṣṭakūṭa match for a pair (all eight kūṭas, with the Bhakoot and Nāḍī doṣas) and Manglik for both charts reckoned from the lagna, the Moon and Venus, with mutual cancellation. The same engine as /v1/compatibility, without the full reading: the score is one input, and /v1/compatibility reads each chart's marital promise, timing and doṣas on top of it. Deterministic, no language model. Cost: 2 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"a":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209,"name":"A"},"b":{"date":"1991-11-03","time":"06:10","timezone":"Asia/Kolkata","latitude":19.076,"longitude":72.8777,"name":"B"}}

Parameters2

a	any	required	First partner: birth data plus optional name and gender.
b	any	required	Second partner: birth data plus optional name and gender.

Raw schema

{
  "type": "object",
  "properties": {
    "a": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "First partner: birth data plus optional name and gender."
    },
    "b": {
      "allOf": [
        {
          "type": "object",
          "required": [
            "date",
            "timezone",
            "latitude",
            "longitude"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date",
              "description": "YYYY-MM-DD"
            },
            "time": {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
              "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          }
        }
      ],
      "description": "Second partner: birth data plus optional name and gender."
    }
  },
  "required": [
    "a",
    "b"
  ]
}

find_muhurta

Use this when the user asks for an auspicious date or time (muhūrta) to do something, such as a wedding, launch, move or purchase, within a date range at a given place. Scans each day in the range and ranks windows for the subject. The pañcāṅga is computed for `eventPlace`, never defaulted to the birthplace. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"subject":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"eventPlace":{"latitude":19.076,"longitude":72.8777,"timezone":"Asia/Kolkata","label":"Mumbai"},"freeText":"signing a lease","rangeStart":"2026-11-01","rangeEnd":"2026-11-15"}

Parameters9

subject	object	required	Birth data of the person the event is for; windows are ranked against their chart.
subjectName	string	optional	Optional name of the subject, used only in the response text.
eventPlace	object	required	Where the event will happen: latitude, longitude and IANA timezone. The pañcāṅga is computed here, never at the birthplace.
rangeStart	string	required	First date to search, YYYY-MM-DD.
rangeEnd	string	required	Last date to search, YYYY-MM-DD.
eventId	string	optional	Event type identifier, if known.
freeText	string	optional	The event described in words, when there is no eventId.
timeOfDay	string	optional	Local time (HH:MM) at which each day is evaluated. Default: local sunrise.
topN	integer	optional	How many ranked windows to return. Default 5.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "Birth data of the person the event is for; windows are ranked against their chart."
    },
    "subjectName": {
      "type": "string",
      "description": "Optional name of the subject, used only in the response text."
    },
    "eventPlace": {
      "type": "object",
      "required": [
        "latitude",
        "longitude",
        "timezone"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone"
        },
        "label": {
          "type": "string"
        }
      },
      "description": "Where the event will happen: latitude, longitude and IANA timezone. The pañcāṅga is computed here, never at the birthplace."
    },
    "rangeStart": {
      "type": "string",
      "format": "date",
      "description": "First date to search, YYYY-MM-DD."
    },
    "rangeEnd": {
      "type": "string",
      "format": "date",
      "description": "Last date to search, YYYY-MM-DD."
    },
    "eventId": {
      "type": "string",
      "description": "Event type identifier, if known."
    },
    "freeText": {
      "type": "string",
      "description": "The event described in words, when there is no eventId."
    },
    "timeOfDay": {
      "type": "string",
      "description": "Local time (HH:MM) at which each day is evaluated. Default: local sunrise."
    },
    "topN": {
      "type": "integer",
      "minimum": 1,
      "description": "How many ranked windows to return. Default 5."
    }
  },
  "required": [
    "subject",
    "eventPlace",
    "rangeStart",
    "rangeEnd"
  ]
}

get_forecast

Use this when the user asks an open question about what lies ahead in one area of life and wants a written answer. It takes tens of seconds; for a fast, structured verdict use interpret_domain. The interpret verdict for `domain`, voiced as a narrative answer to `question` by a language model grounded in the classical statements for the domain. Expect tens of seconds; set a client timeout of at least 90 s. Cost: 8 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Voiced by a language model: allow up to 90 seconds. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"domain":"career","question":"How will the next year unfold for my work?"}

Parameters3

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
domain	string	required	Life area the question is about, e.g. career, marriage, finance or health.
question	string	required	The question in plain language, e.g. "What does the next year hold for my career?"

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "domain": {
      "type": "string",
      "enum": [
        "career",
        "business",
        "finance",
        "children",
        "property",
        "education",
        "travel",
        "spirituality",
        "lineage",
        "reputation",
        "partnerships",
        "legal",
        "family",
        "marriage",
        "health"
      ],
      "description": "Life area the question is about, e.g. career, marriage, finance or health."
    },
    "question": {
      "type": "string",
      "minLength": 1,
      "description": "The question in plain language, e.g. \"What does the next year hold for my career?\""
    }
  },
  "required": [
    "birthData",
    "domain",
    "question"
  ]
}

resolve_timing

Use this when the user asks whether now, or a particular date or range, is a good time for a decision such as changing jobs, marrying or investing. It takes tens of seconds. The interpret verdict for `domain`, voiced by a language model as an answer to a decision `question`, optionally anchored to `targetDate` or `dateRange`. Expect tens of seconds; set a client timeout of at least 90 s. Cost: 7 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Voiced by a language model: allow up to 90 seconds. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"domain":"career","question":"Should I accept the offer?","targetDate":"2026-11-15"}

Parameters5

birthData	object	required	The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude.
domain	string	required	Life area the decision is about, e.g. career, marriage, finance or health.
question	string	required	The decision question in plain language, e.g. "Is this a good time to change jobs?"
targetDate	string	optional	Optional date the decision is about, YYYY-MM-DD.
dateRange	object	optional	Optional period the decision is about: start and end dates, YYYY-MM-DD.

Raw schema

{
  "type": "object",
  "properties": {
    "birthData": {
      "type": "object",
      "required": [
        "date",
        "timezone",
        "latitude",
        "longitude"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "YYYY-MM-DD"
        },
        "time": {
          "type": "string",
          "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
          "description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
        },
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
    },
    "domain": {
      "type": "string",
      "enum": [
        "career",
        "business",
        "finance",
        "children",
        "property",
        "education",
        "travel",
        "spirituality",
        "lineage",
        "reputation",
        "partnerships",
        "legal",
        "family",
        "marriage",
        "health"
      ],
      "description": "Life area the decision is about, e.g. career, marriage, finance or health."
    },
    "question": {
      "type": "string",
      "minLength": 1,
      "description": "The decision question in plain language, e.g. \"Is this a good time to change jobs?\""
    },
    "targetDate": {
      "type": "string",
      "format": "date",
      "description": "Optional date the decision is about, YYYY-MM-DD."
    },
    "dateRange": {
      "type": "object",
      "required": [
        "start",
        "end"
      ],
      "properties": {
        "start": {
          "type": "string",
          "format": "date"
        },
        "end": {
          "type": "string",
          "format": "date"
        }
      },
      "description": "Optional period the decision is about: start and end dates, YYYY-MM-DD."
    }
  },
  "required": [
    "birthData",
    "domain",
    "question"
  ]
}

get_ephemeris_positions

Use this when you need where the Sun, Moon and planets are at a moment (sidereal or tropical), not a reading. Sun, Moon, planets and lunar nodes at one moment: longitude, latitude, distance, speed and retrograde flag, with sign, and nakṣatra and pada when sidereal. `equatorial: true` adds apparent right ascension and declination. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"2026-10-06T06:00:00Z","bodies":["Sun","Moon","Mars","Jupiter","Saturn","TrueNode"],"zodiac":"sidereal","ayanamsa":"lahiri"}

Parameters5

datetime	string	required	ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).
bodies	array	optional	Default: all twelve.
zodiac	string	optional	sidereal (default) or tropical.
ayanamsa	string	optional	Sidereal only.
equatorial	boolean	optional	Also return apparent right ascension and declination. Default false.

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
    },
    "bodies": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Sun",
          "Moon",
          "Mercury",
          "Venus",
          "Mars",
          "Jupiter",
          "Saturn",
          "Uranus",
          "Neptune",
          "Pluto",
          "MeanNode",
          "TrueNode"
        ],
        "description": "MeanNode and TrueNode are Rāhu (mean or true); Ketu is the node + 180°."
      },
      "description": "Default: all twelve."
    },
    "zodiac": {
      "type": "string",
      "enum": [
        "sidereal",
        "tropical"
      ],
      "default": "sidereal",
      "description": "sidereal (default) or tropical."
    },
    "ayanamsa": {
      "type": "string",
      "enum": [
        "lahiri",
        "raman",
        "krishnamurti",
        "fagan_bradley"
      ],
      "default": "lahiri",
      "description": "Sidereal only."
    },
    "equatorial": {
      "type": "boolean",
      "default": false,
      "description": "Also return apparent right ascension and declination. Default false."
    }
  },
  "required": [
    "datetime"
  ]
}

get_ephemeris_angles

Use this when you need the ascendant, midheaven or house cusps for a moment and place. Ascendant, midheaven and twelve cusps for a moment and place. Placidus is undefined beyond the polar circles at some moments; the call then returns 422 houses_undefined_at_latitude. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"1990-05-12T14:35:00+05:30","latitude":28.6139,"longitude":77.209,"houseSystem":"placidus"}

Parameters6

datetime	string	required	ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).
latitude	number	required	Geographic latitude in decimal degrees, north positive.
longitude	number	required	East positive.
houseSystem	string	optional	House system for the cusps: whole_sign (default), equal or placidus.
zodiac	string	optional	sidereal (default) or tropical.
ayanamsa	string	optional	Sidereal only.

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
    },
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Geographic latitude in decimal degrees, north positive."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "East positive."
    },
    "houseSystem": {
      "type": "string",
      "enum": [
        "whole_sign",
        "equal",
        "placidus"
      ],
      "default": "whole_sign",
      "description": "House system for the cusps: whole_sign (default), equal or placidus."
    },
    "zodiac": {
      "type": "string",
      "enum": [
        "sidereal",
        "tropical"
      ],
      "default": "sidereal",
      "description": "sidereal (default) or tropical."
    },
    "ayanamsa": {
      "type": "string",
      "enum": [
        "lahiri",
        "raman",
        "krishnamurti",
        "fagan_bradley"
      ],
      "default": "lahiri",
      "description": "Sidereal only."
    }
  },
  "required": [
    "datetime",
    "latitude",
    "longitude"
  ]
}

get_ephemeris_ayanamsa

Use this when you need an ayanamsa value (Lahiri, Raman, Krishnamurti, Fagan–Bradley) at a moment. Lahiri, Raman, Krishnamurti and Fagan–Bradley (mean, without nutation) at a moment. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"2026-10-06T00:00:00Z"}

Parameters1

datetime

string

required

ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
    }
  },
  "required": [
    "datetime"
  ]
}

get_ephemeris_sunrise

Use this when you need sunrise and sunset for a date and place, or where the Vedic day begins. Sunrise, sunset and the next sunrise for a local date and place: upper limb at the sea-level horizon with 36.6′ refraction. The Vedic day runs from sunrise to the next sunrise. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"date":"2026-10-06","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}

Parameters4

date	string	required	Local calendar date, YYYY-MM-DD.
timezone	string	required	IANA name, e.g. Asia/Kolkata. Defines the local day.
latitude	number	required	Geographic latitude in decimal degrees, north positive.
longitude	number	required	East positive.

Raw schema

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Local calendar date, YYYY-MM-DD."
    },
    "timezone": {
      "type": "string",
      "description": "IANA name, e.g. Asia/Kolkata. Defines the local day."
    },
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Geographic latitude in decimal degrees, north positive."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "East positive."
    }
  },
  "required": [
    "date",
    "timezone",
    "latitude",
    "longitude"
  ]
}

get_ephemeris_series

Use this when you need planetary positions across a range of dates, for a transit table or to find when a planet changes sign or stations. Positions from start to end (inclusive) every stepMinutes, for transit tables and station finding. At most 1,000 points (too_many_points beyond). A 365-point daily table costs 4 credits. Cost: 1 credit per started 100 points (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"start":"2026-10-01T00:00:00Z","end":"2026-10-10T00:00:00Z","stepMinutes":1440,"bodies":["Mercury","Venus"]}

Parameters6

start	string	required	ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).
end	string	required	ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime).
stepMinutes	integer	required	Minutes between points (1 to 525,600). At most 1,000 points per call.
bodies	array	optional	Default: all twelve.
zodiac	string	optional	sidereal (default) or tropical.
ayanamsa	string	optional	Sidereal only.

Raw schema

{
  "type": "object",
  "properties": {
    "start": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
    },
    "end": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
    },
    "stepMinutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 525600,
      "description": "Minutes between points (1 to 525,600). At most 1,000 points per call."
    },
    "bodies": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Sun",
          "Moon",
          "Mercury",
          "Venus",
          "Mars",
          "Jupiter",
          "Saturn",
          "Uranus",
          "Neptune",
          "Pluto",
          "MeanNode",
          "TrueNode"
        ],
        "description": "MeanNode and TrueNode are Rāhu (mean or true); Ketu is the node + 180°."
      },
      "description": "Default: all twelve."
    },
    "zodiac": {
      "type": "string",
      "enum": [
        "sidereal",
        "tropical"
      ],
      "default": "sidereal",
      "description": "sidereal (default) or tropical."
    },
    "ayanamsa": {
      "type": "string",
      "enum": [
        "lahiri",
        "raman",
        "krishnamurti",
        "fagan_bradley"
      ],
      "default": "lahiri",
      "description": "Sidereal only."
    }
  },
  "required": [
    "start",
    "end",
    "stepMinutes"
  ]
}

README.md9 KBView on GitHub

AstroNest: Vedic astrology for apps and AI agents

AstroNest is a Vedic astrology (Jyotiṣa) engine you can call as a REST API or connect to an AI agent over MCP. It computes on its own JPL DE440 ephemeris, and the readings are deterministic: the same birth data always gives the same answer, with the reasons and the classical books each reading rests on.

This repository has two things: how to connect AstroNest to an AI agent, and a Next.js quickstart on the REST API.

Docs: https://www.astronest.ai/developers
OpenAPI 3.1 spec: https://www.astronest.ai/openapi/astronest-v1.json
Postman: AstroNest Developer API workspace
Keys: https://www.astronest.ai/developer. Sandbox keys are free and return fixed samples.

Connect it to an AI agent (MCP)

Endpoint (Streamable HTTP): https://www.astronest.ai/api/developer/mcp

Claude Code

bash

claude mcp add --transport http astronest https://www.astronest.ai/api/developer/mcp \
  --header "Authorization: Bearer YOUR_ASTRONEST_KEY"

mcp.json (Cursor, VS Code and other clients that read this format)

json

{
  "mcpServers": {
    "astronest": {
      "url": "https://www.astronest.ai/api/developer/mcp",
      "headers": { "Authorization": "Bearer YOUR_ASTRONEST_KEY" }
    }
  }
}

Also on Smithery and the MCP Registry as io.github.onedotlinks/astronest.

What an agent can ask it

Each tool answers one question. The interpretive ones read the chart the way a practitioner does and return the reasons, not just positions:

Tool	The question it answers
`get_life_reading`	What does my life look like as a whole — which areas (marriage, children, career, money, property…) come into focus when, past and future?
`get_domain_timeline`	When is marriage, career or another area in focus, or what do the next few years hold for it?
`get_relationship_reading`	How do two people get on as business partners, siblings, parent and child, or friends?
`get_venture_timing`	When should I launch, sign or borrow — and which line of business does my chart support?
`assess_gemstone`	Should I wear this stone (blue sapphire, pukhraj, emerald…), and why or why not?
`get_compatibility`, `get_guna_milan`	Kundli matching: the 36-point Aṣṭakūṭa score, Manglik from the lagna, Moon and Venus, and the full pair reading
`interpret_domain`, `get_guidance`	What does my chart say about one area of life, and what do the running periods ask of me now?
`find_muhurta`	Which days and windows in a date range suit an event?
`get_chart`, `get_dasha`, ephemeris tools	The chart (with the sixteen divisional charts), Vimśottarī daśā to pratyantar, and raw JPL DE440 positions

The readings describe what the chart shows and why. They are symbolic interpretation, not predictions, and not medical, legal, financial or psychological advice; every response carries that disclaimer.

The Next.js quickstart

A small Next.js app on the AstroNest Developer API. Enter a birth date, time and place and get:

the chart: lagna, the nine grahas with sign, house, nakṣatra and dignity, and the running daśā (1 credit)
guidance now: plain-language cards for the running mahādaśā / antardaśā / pratyantardaśā (3 credits)
a domain reading: career, marriage, finance and twelve more, with supporting factors, cautions, timing windows and how many methods agree (5 credits)
optionally, "explain in plain words" with your own LLM (0 AstroNest credits)

None of the three AstroNest calls uses a language model. They are deterministic, so they return in seconds and the same input always gives the same answer.

Run it in five minutes

Get a key. Sign in at https://www.astronest.ai/developer and create a key. Every account gets 100 free live credits once, valid for 60 days from your first live key (they do not renew): enough for about 20 domain readings or 100 charts. Sandbox keys are free with no time limit and return fixed sample responses. When the free credits are used, or after 60 days, live calls return 402 credits_exhausted until you buy a credit pack; sandbox keys keep working.

Install and configure.

bash

npm install
cp .env.example .env.local
# put your key in ASTRONEST_API_KEY

Run.
bash
```
npm run dev
```
Open http://localhost:3000.

How it fits together

code

browser ──► /api/astronest/{chart|guidance|interpret} ──► AstroNest API   (your key, server-side)
        └─► /api/explain ──────────────────────────────► your LLM         (optional)

lib/astronest.ts is a typed client. It is the file to copy into your own app.
app/api/astronest/[op]/route.ts forwards only those three operations, so the route can't be used to call every endpoint your key allows.
app/api/explain/route.ts sends the reading AstroNest computed to any OpenAI-compatible chat-completions endpoint (OpenAI, Vercel AI Gateway, OpenRouter, a local Ollama) and tells the model to use only the facts it was given. Your model writes the words; AstroNest does the astrology.

Before you deploy

Your key is a secret. It lives in server environment variables only. Never prefix it with NEXT_PUBLIC_, and never call the API from the browser. The API sends no CORS headers, so browser calls fail anyway.
The demo routes spend your credits for anyone who calls them. By default they answer only on localhost. Put your own sign-in (and ideally a rate limit) in front of them before you set ALLOW_PUBLIC_DEMO=true. The localhost check reads the request host, so don't rely on it behind a proxy that rewrites Host.
Birth data is personal data. This app stores nothing, and the API stores nothing either. If you add storage, you take on the data-protection duties that come with it.
Show the disclaimer that comes with every response: symbolic interpretation, not medical, legal, financial or psychological advice.

Going further

Endpoint	Credits	Notes
`POST /v1/chart`	1	add `location` for astrocartography and a relocated frame
`POST /v1/dasha`	1	full Vimśottarī timeline
`POST /v1/guidance`	3	`referenceDate` for any other moment
`POST /v1/interpret`	5	15 domains
`POST /v1/timing/resolve`	7	narrated by a language model; allow 90 s
`POST /v1/forecast`	8	narrated by a language model; allow 90 s
`POST /v1/muhurta`	10	auspicious windows in a date range
`POST /v1/compatibility`	12	two charts read together
`POST /v1/guna-milan`	2	the 36-point Aṣṭakūṭa match + Manglik (lagna, Moon, Venus) for a pair
`POST /v1/life-reading`	10	the whole-life reading: chapters and 11 life areas, past and future (`areas` narrows it)
`POST /v1/domain-timeline`	3	one life area across the life: every period that governs it, optionally within a date window
`POST /v1/relationship`	8	business partners, siblings, parent & child, friends: bond houses, cross-chart contacts, the bond meter
`POST /v1/venture-timing`	10	when to commit, build, guard or hold; the businesses you describe ranked on the chart
`POST /v1/gem-assessment`	5	should this chart wear this stone: the verdict, every ground for and against, how long the reason lasts
`POST /v1/ephemeris/positions`	0.1	raw positions at a moment (JPL DE440); no birth data needed
`POST /v1/ephemeris/angles`	0.1	ascendant, MC and house cusps for a moment and place
`POST /v1/ephemeris/ayanamsa`	0.1	Lahiri, Raman, Krishnamurti, Fagan–Bradley
`POST /v1/ephemeris/sunrise`	0.1	sunrise, sunset and next sunrise for a local date
`POST /v1/ephemeris/series`	1	per started 100 points, up to 1,000

The four single-moment Ephemeris calls cost 0.1 credit each: 1 credit per started block of 10, counted across them per account (the call that opens a block reports units_charged: 1, the next nine report 0). Only successful (2xx) calls are charged. When credits run out, the API returns 402 credits_exhausted; buy a pack in the developer portal. Paid credits do not expire.

OpenAPI 3.1 spec: https://www.astronest.ai/openapi/astronest-v1.json (import it into Postman, or generate a client in any language)
Reference: the developer portal at https://www.astronest.ai/developer

Install

Tools (19)

get_chartget_dashaget_guidanceinterpret_domainget_life_readingget_domain_timelineget_relationship_readingget_venture_timing

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://www.astronest.ai/api/developer/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "astronest": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.astronest.ai/api/developer/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

MCP Server: io.github.onedotlinks/astronest

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

get_chart

get_dasha

get_guidance

interpret_domain

get_life_reading

get_domain_timeline

get_relationship_reading

get_venture_timing

assess_gemstone

get_compatibility

get_guna_milan

find_muhurta

get_forecast

resolve_timing

get_ephemeris_positions

get_ephemeris_angles

get_ephemeris_ayanamsa

get_ephemeris_sunrise

get_ephemeris_series

AstroNest: Vedic astrology for apps and AI agents

Connect it to an AI agent (MCP)

What an agent can ask it

The Next.js quickstart

Run it in five minutes

How it fits together

Before you deploy

Going further

Install

Remote endpoint

Related servers