Official sample code and usage guide for the VedAstro API — a REST API for Vedic astrology calculations (birth charts, predictions, compatibility, dasa periods, transits, and more).
This repo exists specifically to make the API easy for AI coding agents (Claude, GPT, Cursor, etc.) to use correctly. If you are an AI agent reading this to write integration code, read the whole file before generating requests — the gotchas below are the #1 source of broken integrations.
- Base REST API:
https://api.vedastro.org/api - Full method list: https://vedastro.org/Complete-List-VedAstro-API-Methods-Calculators.html
- Website: https://vedastro.org
- Prefer MCP tool-calling? See Prefer MCP? below.
All endpoints return:
{ "Status": "Pass" | "Fail", "Payload": ... }Always check Status before reading Payload. On failure, Payload is a plain error string, not an object:
{ "Status": "Fail", "Payload": "Could not parse birth time '...'" }On success, many endpoints nest their real result one level deeper, under a key matching the calculator name — e.g. Payload.AddressToGeoLocation, Payload.DasaAtTime, Payload.GocharaKakshas. A few endpoints (e.g. HoroscopePredictions) instead return the result directly as Payload (an array). There is no way to know which shape an endpoint uses except by checking — the examples below are all verified against the live API, so copy the shape from the matching example rather than assuming.
Birth/check times use StdTime, formatted as:
"HH:MM DD/MM/YYYY ±HH:MM"
Example: "14:30 25/10/1992 +05:30" — 2:30 PM on 25 Oct 1992, UTC+5:30 (India).
- ❌
"1992-10-25T14:30:00+05:30"(ISO 8601 — will fail) - ✅
"14:30 25/10/1992 +05:30"
Most endpoints also require an Ayanamsa value. RAMAN is VedAstro's canonical default. Other supported values: LAHIRI, KRISHNAMURTI, YUKTESHWAR.
If you don't know the exact method name for what you need, POST /Calculate/ContextBasedAstrologyData semantically routes your plain-English query to the best-matching methods out of 640+ available and invokes all of them. Called directly over REST it returns the full raw output of every matched method (long text blocks, per-method result objects) — it is not a short synthesized answer at this layer. Only the hosted MCP server (see Prefer MCP?) applies an LLM summarization pass on top to produce the short {answer, drivers, evidence} shape you may have seen elsewhere; that shape does not come from calling the raw REST endpoint yourself.
POST /Calculate/ContextBasedAstrologyData
Content-Type: application/json
{
"query": "what is my moon nakshatra",
"birthTime": {
"StdTime": "14:30 25/10/1992 +05:30",
"Location": { "Name": "Mumbai", "Latitude": 19.0760, "Longitude": 72.8777 }
}
}Verified response shape (trimmed — methods typically has ~10 entries, each with a long description and a result object):
{
"Status": "Pass",
"Payload": {
"ContextBasedAstrologyData": {
"query": "what is my moon nakshatra",
"searchPoolSize": 25,
"invokedCount": 10,
"methods": [
{
"matchedMethod": "PlanetPakshaBala",
"score": 0.44,
"endpoint": "https://api.vedastro.org/api/Calculate/PlanetPakshaBala",
"usedParameters": [ { "name": "time", "type": "Time", "value": "14:30 25/10/1992 +05:30", "source": "birthTime" } ],
"result": { }
}
]
}
}
}If you want a short, ready-to-display answer instead of raw method dumps, call this same query through the MCP server's get_context_based_astrology_data tool rather than the raw endpoint — see Prefer MCP?.
For current-sky/"now" queries (no birth details needed), supply checkTime instead of/alongside birthTime. At least one of birthTime / checkTime must be supplied.
POST /Calculate/AddressToGeoLocation
Content-Type: application/json
{ "Address": "mumbai", "Ayanamsa": "RAMAN" }Verified response (note the result is nested under Payload.AddressToGeoLocation):
{
"Status": "Pass",
"Payload": {
"AddressToGeoLocation": {
"Name": "Mumbai, Maharashtra, India",
"Longitude": 72.821,
"Latitude": 18.969
}
}
}POST /Calculate/HoroscopePredictions
Content-Type: application/json
{
"birthTime": {
"StdTime": "14:30 25/10/1992 +05:30",
"Location": { "Name": "Mumbai", "Latitude": 19.0760, "Longitude": 72.8777 }
},
"Ayanamsa": "RAMAN",
"sortByWeight": true
}Returns 200+ raw life-prediction items directly as the Payload array (this endpoint does not nest under a HoroscopePredictions key):
{
"Status": "Pass",
"Payload": [
{
"Name": "MaleficOn5thOr7thFromAscOrMoon",
"Description": " The native may not marry or if he marries his wife may not live. ",
"...": "..."
}
]
}Uses URL path parameters instead of a JSON body. The date segment must use / as the separator (DD/MM/YYYY), not - — a hyphenated date fails to parse:
GET /Calculate/MatchReport/Location/{maleLat},{maleLon}/Time/{maleTime}/{maleDD}/{maleMM}/{maleYYYY}/{maleTz}/Location/{femaleLat},{femaleLon}/Time/{femaleTime}/{femaleDD}/{femaleMM}/{femaleYYYY}/{femaleTz}/Ayanamsa/RAMAN
Verified example:
GET https://api.vedastro.org/api/Calculate/MatchReport/Location/19.0760,72.8777/Time/14:30/25/10/1992/+05:30/Location/28.6139,77.2090/Time/09:15/03/04/1994/+05:30/Ayanamsa/RAMAN
Response is nested under Payload.MatchReport following the same pattern as other path-style endpoints.
POST /Calculate/DasaAtTime
Content-Type: application/json
{
"birthTime": {
"StdTime": "14:30 25/10/1992 +05:30",
"Location": { "Name": "Mumbai", "Latitude": 19.0760, "Longitude": 72.8777 }
},
"checkTime": {
"StdTime": "12:00 11/07/2026 +05:30",
"Location": { "Name": "Mumbai", "Latitude": 19.0760, "Longitude": 72.8777 }
},
"Ayanamsa": "RAMAN",
"levels": 1
}Verified response (nested under Payload.DasaAtTime, keyed by dasa lord):
{
"Status": "Pass",
"Payload": {
"DasaAtTime": {
"Jupiter": {
"Type": "Dasa",
"TechnicalName": "JupiterPD1",
"Lord": "Jupiter",
"ParentLord": null,
"Description": "Jupiter Dasa",
"Nature": "Neutral"
}
}
}
}POST /Calculate/GocharaKakshas
Content-Type: application/json
{
"checkTime": {
"StdTime": "12:00 11/07/2026 +00:00",
"Location": { "Name": "Greenwich", "Latitude": 51.4769, "Longitude": 0.0 }
},
"birthTime": {
"StdTime": "14:30 25/10/1992 +05:30",
"Location": { "Name": "Mumbai", "Latitude": 19.0760, "Longitude": 72.8777 }
},
"Ayanamsa": "RAMAN"
}Response is nested under Payload.GocharaKakshas (verified Status: "Pass", same nesting pattern as AddressToGeoLocation).
| Tier | Access | Rate limit |
|---|---|---|
| Free | No API key needed | 5 requests/minute |
| Premium | sk_live_... API key ($1/mo) |
Unlimited |
Send the key via any of these headers:
x-api-key: sk_live_...
APIKey: sk_live_...
Authorization: Bearer sk_live_...
Get a key at vedastro.org/MCPServerApp.html.
See examples/ for copy-pasteable code:
VedAstro also runs a production MCP server with 17 typed tools (horoscope, match report, dasa, transits, location resolution, and more) that wraps the raw REST quirks above for you. Recommended if your agent/client supports MCP tool-calling.
- Endpoint:
https://mcp.vedastro.org/api/mcp(protected, OAuth-capable) - Manual/header auth:
https://mcp.vedastro.org/api/mcp/public - See
examples/mcp/claude_desktop_config.jsonfor a ready-to-use client config.
- Full API method list: https://vedastro.org/Complete-List-VedAstro-API-Methods-Calculators.html
- Website / API builder: https://vedastro.org/API.html