Getting Started

This guide covers the rules that apply across almost every VedAstro API call. Read this before calling any method.

1. Every response is enveloped — and the Payload shape varies by endpoint

All endpoints return:

{ "Status": "Pass" | "Fail", "Payload": ... }

Always check Status before reading Payload. On failure, Payload is a plain error string, not an object.

On success, many endpoints nest their real result one level deeper, under a key matching the calculator name (e.g. Payload.AddressToGeoLocation). 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 — use the "Try it" widget on each method's page to see the real live shape.

2. Time format is a specific string, not ISO 8601

Birth/check times use StdTime, formatted as "HH:MM DD/MM/YYYY ±HH:MM". Example: "14:30 25/10/1992 +05:30".

Path-style GET endpoints (like MatchReport) use / as the date separator in the URL — a --separated date fails to parse.

3. Ayanamsa

Most endpoints require an Ayanamsa value. RAMAN is VedAstro's canonical default. Other supported values: LAHIRI, KRISHNAMURTI, YUKTESHWAR.

4. Authentication

Send the key via x-api-key, APIKey, or Authorization: Bearer. Subscribe at vedastro.org/Pricing.html — the same key works for the MCP server too.

5. Getting started with the Python library

Prefer Python over raw HTTP? The official VedAstro.Python library (PyPI package vedastro, MIT licensed) is a thin wrapper around this REST API — no ephemeris files, no C extensions, no local calculation. It just calls the cloud API for you, so everything documented above (envelope, StdTime, Ayanamsa, rate limits) still applies underneath.

pip install vedastro

Set your key once, then build a Time from a GeoLocation and call any calculator:

from vedastro import *

Calculate.SetAPIKey('your-api-key')  # or 'FreeAPIUser' for the free tier

geo = GeoLocation("Tokyo, Japan", 139.83, 35.65)
birth_time = Time(hour=23, minute=40, day=31, month=12, year=2010, offset="+08:00", geolocation=geo)

result = Calculate.AllPlanetData(PlanetName.Sun, birth_time)
Tools.Print(result)

Compatibility / match report between two people:

from vedastro import *

Calculate.SetAPIKey('your-api-key')

romeo = Time("23:40 31/12/1996 +08:00", GeoLocation("Tokyo, Japan", 139.83, 35.65))
juliet = Time("14:30 15/06/1997 -05:00", GeoLocation("New York, USA", -74.006, 40.7128))

match = Calculate.MatchReport(romeo, juliet)
Tools.Print(match)

Dasa periods over a date range:

from vedastro import *
import json

Calculate.SetAPIKey('your-api-key')

geo = GeoLocation("Tokyo, Japan", 139.83, 35.65)
birth_time = Time("23:40 31/12/2010 +08:00", geo)
start = Time("00:00 01/01/2020 +08:00", geo)
end   = Time("23:59 31/12/2025 +08:00", geo)

dasa = Calculate.DasaAtRange(birth_time, start, end, levels=3, precision_hours=100)
print(json.dumps(dasa, indent=4))

Switch Ayanamsa globally:

Calculate.SetAyanamsa(Ayanamsa.Lahiri)
Calculate.SetAyanamsa(Ayanamsa.Fagan_Bradley)
Calculate.SetAyanamsa(Ayanamsa.Krishnamurti)

More demos (planet data as JSON/CSV, bhava charts, custom Ayanamsa, horoscope predictions, match checking) live in the VedAstro.Python repo. Method names in Python mirror the 652 Calculate methods documented on this site.

6. Runnable examples

See vedastro-api-examples for verified, runnable curl/Python/JavaScript quickstarts against the raw REST API.

7. Prefer MCP tool-calling?

VedAstro runs a production MCP server with typed tools wrapping the raw REST quirks above: https://mcp.vedastro.org/api/mcp.