🪐 VedAstro for Java

The most comprehensive Vedic astrology library for Java — 684 calculations, one method call.

🎯 Built for Real Apps

Perfect for:

📱 Horoscope services - Get 200+ life predictions instantly
💑 Marriage matching backends - 16-factor Kuta compatibility analysis
📅 Daily panchanga APIs - Tithi, Nakshatra, Yoga, Karana
🔮 AI astrology chatbots - Natural language birth chart queries
📊 Astrological research - Batch process thousands of charts
🌟 Numerology calculators - Chaldean system with life aspect scores

Zero runtime dependencies. The library uses only the JDK — java.net.http for transport and a small bundled JSON codec — so it drops into a Spring Boot, Jakarta EE, Quarkus or plain main project without pulling a transitive tree or fighting a version conflict.

🏃 Quick Start (3 minutes to your first calculation)

Installation (10 seconds)

<dependency>
  <groupId>org.vedastro</groupId>
  <artifactId>vedastro</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle:

implementation 'org.vedastro:vedastro:1.0.0'

Requires Java 21 or newer. There is nothing else to install: no native libraries, no ephemeris files, no system packages.

Your First Calculation (20 seconds)

import org.vedastro.Calculate;
import org.vedastro.GeoLocation;
import org.vedastro.Time;
import org.vedastro.calculate.PlanetName;

public class Main {
    public static void main(String[] args) {
        // Free tier key. For a paid key, set VEDASTRO_API_KEY and use
        // Calculate.setApiKey(System.getenv("VEDASTRO_API_KEY")).
        Calculate.setApiKey("FreeAPIUser");

        // Time format: "HH:MM DD/MM/YYYY +TZ:TZ".
        // GeoLocation takes the name, then LONGITUDE, then latitude.
        Time birth = Time.of("14:30 25/10/1992 +05:30",
                GeoLocation.of("Mumbai", 72.8777, 19.0760));

        // One call returns the Sun's sign.
        Object result = Calculate.planetRasiD1Sign(PlanetName.SUN, birth);

        System.out.println("Sun Sign: " + Calculate.name(result)); // Libra
    }
}

That's it! You just made your first Vedic astrology calculation. 🎉

Results are dynamic. A calculator returns Object holding the unwrapped API payload: a Map<String, Object>, a List<Object>, a String, a Double, a Boolean, or null. Objects decode as Map and numbers as Double, so read fields with the Json helpers or a cast. See Decoded results.

📚 Beginner-Friendly Examples

Every snippet is complete. They all use a client from Quick Start, or the static Calculate facade, and this helper for reading a field out of a payload:

// Reads a Name-style field from an object payload.
static String field(Object payload, String key) {
    return String.valueOf(org.vedastro.Json.asMap(payload).get(key));
}

Example 1: Get Birth Chart Basics

Use case: display the Sun, Moon and Ascendant signs

import org.vedastro.VedAstroClient;
import org.vedastro.calculate.HouseName;
import org.vedastro.calculate.PlanetName;

VedAstroClient client = VedAstroClient.fromEnvironment();

Time birth = Time.of("14:30 25/10/1992 +05:30",
        GeoLocation.of("Mumbai", 72.8777, 19.0760));

Object sun = client.calculate().planetRasiD1Sign(PlanetName.SUN, birth);
Object moon = client.calculate().planetRasiD1Sign(PlanetName.MOON, birth);
// House 1 is the ascendant. HouseSignName unwraps to a plain String.
Object rising = client.calculate().houseSignName(HouseName.HOUSE1, birth);

System.out.println("Sun:    " + field(sun, "Name"));   // e.g. Libra
System.out.println("Moon:   " + field(moon, "Name"));  // e.g. Scorpio
System.out.println("Rising: " + rising);               // e.g. Capricorn

👉 See full example: demos/BirthChartBasics.java

Example 2: Marriage Compatibility

Use case: check whether two people are compatible for marriage

Time person1 = Time.of("23:40 31/12/1996 +09:00", GeoLocation.of("Tokyo", 139.83, 35.65));
Time person2 = Time.of("14:30 15/06/1997 -05:00", GeoLocation.of("New York", -74.006, 40.7128));

Object report = client.calculate().matchReport(person1, person2);
Map<String, Object> match = Json.asMap(report);

System.out.println("Compatibility: " + match.get("KutaScore") + "/100");
System.out.println("Status: " + Json.asMap(match.get("Summary")).get("ScoreSummary"));

// Each factor carries a Nature of Good, Bad or Neutral.
for (Object item : Json.asList(match.get("PredictionList"))) {
    Map<String, Object> kuta = Json.asMap(item);
    System.out.println("  • " + kuta.get("Name") + ": " + kuta.get("Nature"));
}

Output (values depend on the two charts):

Compatibility: 65.0/100
Good match - Near perfect match, overall happiness
  • Graha Maitram: Good
  • Rajju: Good
  • Nadi Kuta: Good
  • Vasya Kuta: Bad
  • Dina Kuta: Good

👉 See full example: demos/MarriageCompatibility.java

Example 3: Current Planetary Positions

Use case: get today's positions for any location

import java.time.ZoneId;
import java.time.ZonedDateTime;

GeoLocation mumbai = GeoLocation.of("Mumbai", 72.8777, 19.0760);
// Build the time from a ZonedDateTime already in the target zone; its offset is preserved.
Time now = Time.from(ZonedDateTime.now(ZoneId.of("Asia/Kolkata")), mumbai);

PlanetName[] planets = {PlanetName.SUN, PlanetName.MOON, PlanetName.MARS,
        PlanetName.MERCURY, PlanetName.JUPITER, PlanetName.VENUS,
        PlanetName.SATURN, PlanetName.RAHU, PlanetName.KETU};

for (PlanetName planet : planets) {
    Object sign = client.calculate().planetRasiD1Sign(planet, now);
    Object star = client.calculate().planetConstellation(planet, now);
    System.out.println("  " + planet + ": " + field(sign, "Name") + " in " + star);
}

Output:

  Sun: Taurus in Krithika - 2
  Moon: Sagittarius in Moola - 1
  ...

Free-tier pacing: this loop makes two calls per planet. See Pacing requests.

👉 See full example: demos/CurrentPlanets.java

Example 4: Daily Panchanga

Use case: today's Tithi, Nakshatra, Yoga and Karana

Time today = Time.from(ZonedDateTime.now(ZoneId.of("Asia/Kolkata")), mumbai);

// LunarDay and NithyaYoga return objects; the others unwrap to strings.
Map<String, Object> tithi = Json.asMap(client.calculate().lunarDay(today));
System.out.println("Tithi:     " + tithi.get("Name") + " (" + tithi.get("Paksha") + ")");
System.out.println("Nakshatra: " + client.calculate().moonConstellation(today));

Map<String, Object> yoga = Json.asMap(client.calculate().nithyaYoga(today));
System.out.println("Yoga:      " + yoga.get("Name"));
System.out.println("Karana:    " + client.calculate().karana(today));

Output:

Tithi:     Amavasya (Krishna)
Nakshatra: Chitta - 3
Yoga:      Vishkambha
Karana:    Chatushpada

Note: shapes vary per calculator, so check the Javadoc or api_manifest.json rather than assuming. Panchanga is reckoned from local sunrise, so the location matters.

👉 See full example: demos/DailyPanchanga.java

Example 5: Vimshottari Dasa Timeline

Use case: list the planetary periods (Mahadasa → Bhukti → Antaram) across a range

Time birth = Time.of("14:30 25/10/1992 +05:30", mumbai);
Time start = Time.of("00:00 01/01/2020 +05:30", mumbai);
Time end   = Time.of("23:59 31/12/2030 +05:30", mumbai);

// The two-argument form uses the server defaults.
Object timeline = client.calculate().dasaAtRange(birth, start, end);
System.out.println(Json.encode(timeline));

// Or tune the nesting depth and scan precision.
var options = new Calculators.DasaAtRangeOptions();
options.levels = 2;            // Mahadasa -> Bhukti
options.precisionHours = 100;  // coarser scan, faster response
Object tuned = client.calculate().dasaAtRange(birth, start, end, options);

👉 See full example: demos/VimshottariDasa.java

Example 6: Numerology Calculator

Use case: Chaldean numerology for a name and a birth date

String name = "John Doe";

System.out.println("Birth number:   " + client.calculate().birthNumber(birth));
System.out.println("Destiny number: " + client.calculate().destinyNumber(birth));

Object prediction = client.calculate().nameNumberPrediction(name);
Map<String, Object> fields = Json.asMap(prediction);
System.out.println("Number:        " + fields.get("Number"));
System.out.println("Root number:   " + fields.get("RootNumber"));
System.out.println("Ruling planet: " + fields.get("Planet"));

// Prediction is HTML formatted, so strip the tags for a terminal.
String plain = Json.asString(fields.get("Prediction"), "").replaceAll("<[^>]+>", "");
System.out.println(plain.substring(0, Math.min(400, plain.length())));

Output:

Birth number:   7
Destiny number: 2
John Doe: number 34 (root 7, ruling planet Ketu)
This number has the potential to be seen as lucky, ...

👉 See full example: demos/Numerology.java

Example 7: Semantic Search of Classical Texts (RAG)

Use case: ask a plain-English question and get the most relevant passages from works such as Brihat Parashara Hora Shastra and Phaladeepika — no exact keywords needed

Object texts = client.calculate().getAvailableSourceTexts();
System.out.println("Searchable texts: " + texts);

Object passages = client.calculate().searchSourceText("effects of Saturn in the 7th house");
for (Object item : Json.asList(passages)) {
    Map<String, Object> passage = Json.asMap(item);
    double score = ((Number) passage.get("score")).doubleValue();
    // A lower score is a closer match, so invert it into a relevance percentage.
    System.out.printf("%s p.%s (%.0f%%)%n",
            passage.get("sourceName"), passage.get("pageNumber"), (1 - score) * 100);
    System.out.println("   " + passage.get("text"));
}

// Narrow to one book and tune the knobs.
var options = new Calculators.SearchSourceTextOptions();
options.topK = 3;
options.sourceName = "Hindu-Predictive-Astrology";
options.contextSize = 800;
Object focused = client.calculate().searchSourceText("results of Jupiter aspecting the Moon", options);

🤖 This is the same retrieval step that powers VedAstro's RAG/AI features — feed the returned passages into an LLM prompt to build a cited astrology chatbot.

👉 See full example: demos/RagVedicBooks.java

🎓 Step-by-Step Tutorials

Tutorial 1: Understanding Time Format

The most common beginner issue: the time string.

Format: "HH:MM DD/MM/YYYY +HH:MM" — 24-hour clock, DD/MM/YYYY order, explicit numeric UTC offset.

Location	Example	Offset
India	`"14:30 25/10/1992 +05:30"`	IST = UTC+5:30
USA (East)	`"09:30 25/10/1992 -05:00"`	EST = UTC-5:00
USA (West)	`"06:30 25/10/1992 -08:00"`	PST = UTC-8:00
Japan	`"23:30 25/10/1992 +09:00"`	JST = UTC+9:00
UK	`"14:30 25/10/1992 +00:00"`	GMT = UTC+0:00

Three ways to build a Time:

// 1. The API string, validated immediately.
Time birth = Time.of("14:30 25/10/1992 +05:30", mumbai);

// 2. Separate calendar fields, zero-padded for you.
Time same = Time.of(14, 30, 25, 10, 1992, "+05:30", mumbai);

// 3. From java.time, preserving the offset. Preferred when you already have a moment.
Time fromZone = Time.from(ZonedDateTime.now(ZoneId.of("Asia/Kolkata")), mumbai);
Time fromInstant = Time.from(Instant.parse("1992-10-25T09:00:00Z"), ZoneId.of("Asia/Kolkata"), mumbai);

Common mistakes, all of which throw IllegalArgumentException at the call site:

Time.of("2:30 PM 25/10/1992 +05:30", mumbai);  // AM/PM is not supported
Time.of("14:30 1992-10-25 +05:30", mumbai);    // ISO date order
Time.of("14:30 25/10/1992", mumbai);           // missing offset
Time.of("14:30 25/10/1992 IST", mumbai);       // named zone, not an offset
Time.of("14:30 31/02/1992 +05:30", mumbai);    // 31 February does not exist

GeoLocation.of(name, longitude, latitude) takes longitude first. A swapped pair is the second most common bug, and it silently produces a plausible but wrong chart, so coordinates are range-checked when the location is built.

Tutorial 2: Choosing the Right Ayanamsa

What is an ayanamsa?

The ayanamsa is the gap between the tropical (Western) and sidereal (Vedic) zodiacs. Different systems shift a planet by up to about 3°, which is enough to change its sign near a boundary.

47 systems are available. Common choices:

Constant	When to use
`Ayanamsa.LAHIRI`	Indian government standard, most widely used — the server default
`Ayanamsa.RAMAN`	Popular in South India
`Ayanamsa.KRISHNAMURTI`	KP (Krishnamurti Paddhati) system
`Ayanamsa.FAGAN_BRADLEY`	Western sidereal astrology
`Ayanamsa.YUKTESHWAR`	Sri Yukteswar's calculation

Three ways to set it:

// 1. Per client: the default for every request this client sends.
VedAstroClient client = VedAstroClient.builder()
        .apiKey(apiKey)
        .defaultAyanamsa(Ayanamsa.LAHIRI)
        .build();

// 2. Per call, scoped to the current thread. Safe under concurrency, because two server
//    threads can hold different systems at the same time.
Object degree = client.withAyanamsa(Ayanamsa.RAMAN,
        () -> client.calculate().ayanamsaDegree(birth));

// 3. Not at all: the server applies its own default, which measures as Lahiri.

A scoped override wins over the client default, and it is restored even if the lambda throws.

Recommendation:

🇮🇳 Indian astrology → Ayanamsa.LAHIRI
🌏 Unsure → omit it; the server default measures as Lahiri
📐 KP system → Ayanamsa.KRISHNAMURTI
🌍 Western sidereal → Ayanamsa.FAGAN_BRADLEY

👉 See full example: demos/CustomAyanamsa.java

Tutorial 3: Interpreting Match Reports

Understanding the Kuta score:

Score range	Compatibility	Recommendation
33-36 points	Excellent	Highly compatible
25-32 points	Good	Compatible, proceed with confidence
18-24 points	Average	Requires careful consideration
Below 18	Poor	Not recommended without other factors

The 16 Kutas explained:

Graha Maitram (5 pts) — mental compatibility, happiness
Gana (6 pts) — temperament match (Deva/Manushya/Rakshasa)
Yoni (4 pts) — sexual compatibility
Nadi (8 pts) — health and progeny (traditionally weighted most heavily)
Varna (1 pt) — spiritual/ego compatibility
…and 11 more factors

Reading the report:

Map<String, Object> match = Json.asMap(client.calculate().matchReport(person1, person2));

System.out.println(match.get("KutaScore"));                    // normalised to 100
System.out.println(Json.asMap(match.get("Summary")).get("ScoreSummary"));

for (Object item : Json.asList(match.get("PredictionList"))) {
    Map<String, Object> kuta = Json.asMap(item);
    System.out.println(kuta.get("Name") + ": " + kuta.get("Nature")); // Good / Bad / Neutral
    System.out.println("  Info: " + kuta.get("Info"));
}

🔧 Common Use Cases & Demo Files

Twelve runnable programs live in org.vedastro.demos.

# Quick start (configured in the POM)
./mvnw -q exec:java

# Any other demo
./mvnw -q exec:java -Dexec.mainClass=org.vedastro.demos.DailyPanchanga

Demo	Use case	Skill level
`QuickStart`	The simplest possible program	Beginner
`BirthChartBasics`	Sun, Moon, ascendant, birth constellation	Beginner
`CurrentPlanets`	Today's positions for a location	Beginner
`DailyPanchanga`	Tithi, Nakshatra, Yoga, Karana, sunrise	Beginner
`MarriageCompatibility`	Full 16-factor match report	Beginner
`Numerology`	Birth, destiny and name numbers	Beginner
`DivisionalCharts`	D1, D9, D10, D12 signs	Intermediate
`CustomAyanamsa`	Switching between the 47 systems	Intermediate
`VimshottariDasa`	Planetary periods over a range	Intermediate
`RagVedicBooks`	Semantic search of classical texts	Intermediate
`ErrorHandling`	Configuration, failures, retries	Intermediate
`BatchProcessing`	Many charts from a server, paced	Advanced

The demos read VEDASTRO_API_KEY and fall back to the free tier, pacing themselves 13 seconds apart when no key is set.

🔢 Decoded results

The API's Payload is decoded into standard Java values:

JSON	Java
Object	`LinkedHashMap<String, Object>`
Array	`ArrayList<Object>`
Number	`Double`
String	`String`
Boolean	`Boolean`
null	`null`
SVG response	`String`

As in the Python, Node.js and Go SDKs, a payload object with exactly one property is unwrapped to that property's value. Zero, false, empty strings, empty collections and null are all valid results, so never treat a falsy value as "missing".

Object raw = client.calculate().planetNirayanaLongitude(PlanetName.SUN, birth);

// Numbers decode as Double. Use asInt when you want a whole number.
double longitude = ((Number) raw).doubleValue();
int rounded = Json.asInt(raw, 0);

// Objects and arrays have tolerant accessors that never throw on an unexpected shape.
Map<String, Object> map = Json.asMap(result);
List<Object> list = Json.asList(result);
String name = Json.asString(map.get("Name"), "");

⚙️ Optional arguments

Thirty calculators have optional parameters. Each one gets a small options class whose fields are nullable: a null field is omitted, so the server applies its own default, and an explicit value — including 0, false or "" — is sent.

// Omit optional arguments entirely and take the server defaults.
Object all = client.calculate().searchSourceText("Saturn");

// Or pass an options object.
var options = new Calculators.SearchSourceTextOptions();
options.topK = 3;
options.sourceName = "Brihat-Parashara-Hora-Shastra";
Object focused = client.calculate().searchSourceText("Saturn", options);

Defaults are documented on each field and listed in api_manifest.json.

🔑 Keys, clients, and configuration

Read your key from the environment at start-up:

VedAstroClient client = VedAstroClient.builder()
        .apiKey(System.getenv("VEDASTRO_API_KEY"))
        .defaultAyanamsa(Ayanamsa.LAHIRI)
        .build();

An empty key uses the service's free tier. Never embed a paid key in a distributed artifact; JARs are trivially unpacked.

Builder method	Effect
`apiKey(String)`	Your key, or blank for the free tier
`defaultAyanamsa(Ayanamsa)`	Ayanamsa sent with this client's requests
`baseUrl(String)`	Point at a different Calculate service or a test server
`transport(Transport)`	Supply your own HTTP transport, e.g. for tests or a proxy
`timeout(Duration)`	Optional request deadline; none is applied by default (see below)
`silent(boolean)`	Suppress the one-line start-up banner

Invalid configuration is rejected as soon as it is set, so a bad value fails at start-up rather than on a live request.

⏳ There is no request timeout by default

Deliberately. A VedAstro calculation can take milliseconds or minutes depending on the endpoint and the load on the service, and a client library has no way to know what is acceptable for your workload. A built-in deadline would be exactly the kind of brittle logic that silently truncates a valid answer, so the library applies none — neither a request deadline nor a connect deadline. If a call is still running, it is still working.

When you do want a deadline — usually because your own request or job budget demands one — set it explicitly:

VedAstroClient client = VedAstroClient.builder()
        .apiKey(System.getenv("VEDASTRO_API_KEY"))
        .timeout(Duration.ofSeconds(30))   // only because *you* decided 30s is too long
        .build();

To bound only the connection attempt, pass a transport instead: new HttpTransport(Duration.ofSeconds(10), null) — a null deadline for the request itself.

🧵 Using it in a server

A VedAstroClient is immutable after construction, holds a pooled HttpClient, and is safe to share across every thread. Create one at start-up and inject it.

@Configuration
class VedAstroConfig {
    @Bean
    VedAstroClient vedAstroClient() {
        return VedAstroClient.builder()
                .apiKey(System.getenv("VEDASTRO_API_KEY"))
                .build();
    }
}

// Every calculator blocks the calling thread, which suits a normal servlet thread or a virtual
// thread. Give each request its own thread rather than serialising calls behind one lock.
@GetMapping("/sun-sign")
String sunSign(@RequestParam String when, @RequestParam double lat, @RequestParam double lon) {
    Time birth = Time.of(when, GeoLocation.of("query", lon, lat));
    Object result = client.calculate().planetRasiD1Sign(PlanetName.SUN, birth);
    return Json.asString(Json.asMap(result).get("Name"), "unknown");
}

Good practice on a server:

One client per application. Do not build one per request; you would lose connection reuse.
Do not set a timeout unless you mean it. The library applies none, so a slow calculation completes; a fixed deadline would only ever truncate a valid answer. If your servlet container or job runner has its own budget, set one deliberately with .timeout(...).
Cache by chart input. The same birth details recur, and a cache hit costs nothing.
Do not retry blindly. Only idempotent reads are safe to retry, and only on transport errors.
Never log the key. The SDK already redacts it from every message it raises.

🧯 Errors

try {
    Object result = client.calculate().planetRasiD1Sign(PlanetName.SUN, birth);
    // ...
} catch (ApiException remote) {
    // The API answered but reported a failure: bad input, bad key, or a rate limit.
    log.warn("vedastro {} HTTP {}: {}", remote.getEndpoint(), remote.getStatusCode(), remote.getMessage());
} catch (VedAstroException transport) {
    // No usable response: DNS, TLS, connect timeout, or a malformed body.
    log.warn("vedastro transport: {}", transport.getMessage());
}

Every failure is unchecked, so you are never forced into a try block you cannot act on.
ApiException carries getEndpoint() and getStatusCode().
The configured API key is replaced with [redacted] in every message, so it cannot leak into logs.
Interrupting a thread restores its interrupt flag and raises a VedAstroException.
The SDK never retries and never throttles, because only the caller knows whether a second request is safe.

⏱️ Pacing requests and rate limits

The free tier allows five requests per minute, counted per API key across every thread and process. Space calls at least 13 seconds apart.

// A minimal pacer for a single-threaded consumer.
final class Pacer {
    private final long gapMillis;
    private long nextAllowedAt;

    Pacer(int callsPerMinute) {
        this.gapMillis = (long) Math.ceil(60_000.0 / callsPerMinute);
    }

    synchronized void acquire() throws InterruptedException {
        long now = System.currentTimeMillis();
        long waitFor = nextAllowedAt - now;
        nextAllowedAt = Math.max(now, nextAllowedAt) + gapMillis;
        if (waitFor > 0) Thread.sleep(waitFor);
    }
}

BatchProcessing shows the multi-threaded version, which paces the start of each call while still letting requests overlap on the network. Paid keys use the service's own higher limits.

📖 What Can You Calculate? (684 Methods)

Full API reference: vedastro.org/API.html · api_manifest.json lists every method, its parameters and its defaults.

Every calculator is a method on Calculators, reachable as client.calculate().<name>(...).

Core chart analysis (225 methods)

planetRasiD1Sign, planetNirayanaLongitude, planetConstellation, planetsInSign, planetsInConjunction, isPlanetRetrograde, isPlanetExalted, isPlanetDebilitated, houseSignName, houseRasiSign, lordOfHouse, allPlanetData, allHouseData, allZodiacSignData, +211 more

Divisional charts — vargas (102 methods)

allHouseNavamshaSign (D9), allHouseDrekkanaSign (D3), allHouseChaturthamsaSign (D4), planetShashtyamshaD60Sign (D60), planetDivisionalLongitude, D1–D60 vargas

Panchanga, muhurta & time (65 methods)

lunarDay, tithiNumber, nakshatraPada, nithyaYoga, karana, rahuKala, gulikaKala, durmuhurta, sunriseTime, sunsetTime, horaTable, ayanamsaDegree, planetEphemerisLongitude, +51 more

Strength, dignity & Shadbala (62 methods)

planetShadbalaPinda, planetStrength, houseStrength, planetIshtaScore, planetKashtaScore, allPlanetOrderedByStrength, pickOutStrongestPlanet, planetDignity, isPlanetVargottama, +53 more

Charts, aspects & events (55 methods)

northIndianChart, southIndianChart, skyChart, planetAspectDegree, planetsAspectingPlanet, isPlanetAspectedByPlanet, eventsAtTime, eventsAtRange, eventStartTime, horoscopePredictions, swissEphemeris, +44 more

Prashna, chakra & Pancha Pakshi (28 methods)

chapter5PrashnaMargaPredictions … chapter30PrashnaMargaPredictions, sarvatobhadraChakra, kotaChakra, sudarsanaChakra, birthYamaPanchaPakshi, calculateAshtamangalaNumberFromShells, +few more

Ashtakvarga (20 methods)

sarvashtakavargaChart, bhinnashtakavargaChart, planetAshtakvargaBindu, gocharaKakshas, ashtakavargaLongevity, prastaraAshtakavarga, sodyaAshtakavarga, +13 more

Dasa — planetary periods (20 methods)

dasaAtRange, dasaAtTime, dasaForNow, dasaForLife, moolaDasa, narayanaDasa, kalachakraDasa, tithiAshtottariDasa, +12 more

Earthquake research (20 methods)

calculateEarthquakeRiskScore, isEarthquakeNearEclipse, isEarthquakeJupiterSaturnConjunction, isEarthquakePlanetsClusteredInNarrowArc, +16 more

Longevity & life events (18 methods)

detailedAshtakavargaLongevity, marriageByJupiter, childBirthByJupiter1, nativeDeathBySaturn, hasBalarishtaExceptions, marakaPlanetList, +12 more

Upagraha & special points (15 methods)

gulikaLongitude, maandiLongitude, dhumaLongitude, upaketuLongitude, kaalaLongitude, fortunaPoint, destinyPoint, isUpagraha, +7 more

Transit & timing — gochara (13 methods)

planetSignTransit, transitHouseFromLagna, transitHouseFromMoon, isGocharaOccurring, getConstellationTransitStartTime, isPlanetRetrograde, +7 more

Yogas, doshas & kartari (12 methods)

kalaSarpaYoga, jhoraYogaList, isPlanetInGandanta, kujaDosaScore, classifyForKartari, shubKartariPlanets, paapaKartariPlanets, +5 more

Jaimini & Tajika (8 methods)

jaiminiRasiDrishti, jaiminiRasiStrength, tajakaVarshaphala, tajakaYogaList, trueSiderealSolarReturn, arudhaLagnaSign, +2 more

AI, ML & text search (7 methods)

findBirthTimeByMachineLearning, findBirthTimeByMachineLearningTopK, findBirthTimeByAnimal, searchSourceText (RAG over classical texts), getAvailableSourceTexts, horoscopePredictionsForLargeAstrologyModelTrainingData, +1 more

Numerology (6 methods)

birthNumber, destinyNumber, nameNumber, nameNumberPrediction, rootNumberFriendship, mainActivity

Compatibility & matching (4 methods)

matchReport, tarabala, chandrabala, yoniKutaAnimal

Health & nature scores (4 methods)

predictMedicalHealthConditions, houseNatureScore, planetNatureScore, getActiveNccBodyRulesAtTime

🚀 Why VedAstro? The Simplest & Most Affordable Vedic Astrology API

✨ Unbeatable Value

What you get	VedAstro	Competitors
Monthly cost	$1/month	$50–$200/month
Free tier	✅ 5 req/min	❌ None or very limited
Calculations	684 methods	50–200 methods
Ayanamsa systems	47 systems	3–10 systems
Setup complexity	Zero setup	Complex (DLLs, ephemeris files)
Commercial use	✅ Both tiers	❌ Enterprise only

The bottom line: get 10x more features at 1/50th the price. No credit card needed to start.

💰 Pricing That Makes Sense

Tier	Price	Rate limit	Best for
Free	$0/month	5 req/min	Learning, testing, personal projects
Premium	$1/month	Higher (service-set)	Production apps, commercial use

Indian developers: ₹79/month or ₹758/year (₹63/month, most popular)

All 684 calculations are included in both tiers. The only difference is throughput. Premium is quoted as 200 calls/minute by the API's own rate-limit error; confirm current numbers at vedastro.org/API.html.

🏗️ How It Works (Architecture)

Your Java Code
      v
org.vedastro (this library, JDK only)
      v
REST API (vedastro.zaishi.net)
      v
VedAstro Engine (Azure Cloud)
      v
Swiss Ephemeris (NASA JPL data)

The library is a thin, typed client: it builds the request body, POSTs it, unwraps the standard { Status, Payload } envelope, and returns the inner payload. The calculations themselves run on VedAstro's servers.

Why this design?

✅ Zero third-party dependencies — transport and JSON are bundled
✅ Instant updates (684 calculations, always the latest, with no client release needed)
✅ No native code, no cgo, no ephemeris downloads
✅ Cross-platform (Windows / macOS / Linux, any JDK 21+)

🛠️ Development and generation

Calculators.java, the enum types, PlanetName.java and api_manifest.json in org.vedastro.calculate are generated by StaticTableGenerator Task 12 in the main VedAstro repository. Do not edit generated files — Calculators.java starts with a "DO NOT EDIT" header.

# From the main VedAstro repository
dotnet run --project StaticTableGenerator -- --task 12

# From this repository
./mvnw -B test
./mvnw -B verify

Task 12 writes to ../VedAstro.Java-PUBLIC/src/main/java/org/vedastro/calculate. Set VEDASTRO_JAVA_OUT to override the output directory, and VEDASTRO_JAVA_FACADE to point at Calculate.java when it lives somewhere else.

The static facade in Calculate.java is hand-written apart from the block between @GENERATED_METHODS_BEGIN and @GENERATED_METHODS_END, which Task 12 replaces on every run. That block is the only reason regenerating is safe: it never touches the Javadoc, the helper methods, or the surrounding API.

🤝 Contributing

Contributions are welcome — issues and PRs at VedAstro.Java.

Note: everything under org.vedastro.calculate is generated. To change it, change the server metadata and re-run Task 12, then run the tests here.

📄 License

MIT License — free for commercial and personal use.

🙏 Support the Project

VedAstro is non-profit and user-funded. If it saves you time and money:

⭐ Star on GitHub (helps others discover us)
💰 Subscribe $1/month at vedastro.org/API.html
🎁 Donate at vedastro.org/Donate
📢 Share with other developers

Every subscription helps keep VedAstro free and open-source! 🙏

📚 Additional Resources

📖 Full API Docs: vedastro.org/API.html
🚀 Quick Start: QUICKSTART.md
❓ FAQ: FAQ.md
🐍 Python SDK: VedAstro.Python
🟨 Node.js SDK: VedAstro.NodeJS
🔵 Go SDK: VedAstro.Go
💬 Telegram: t.me/vedastro_org
🐛 Issues: GitHub Issues
🌐 Website: vedastro.org

Made with ❤️ by users, for users
Website • API Docs • GitHub • Telegram • Donate

🪐 Empowering developers to build amazing astrology apps since 2020

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.mvn/wrapper		.mvn/wrapper
src		src
.gitignore		.gitignore
FAQ.md		FAQ.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
mvnwDebug		mvnwDebug
mvnwDebug.cmd		mvnwDebug.cmd
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation

🪐 VedAstro for Java

🎯 Built for Real Apps

🏃 Quick Start (3 minutes to your first calculation)

Installation (10 seconds)

Your First Calculation (20 seconds)

📚 Beginner-Friendly Examples

Example 1: Get Birth Chart Basics

Example 2: Marriage Compatibility

Example 3: Current Planetary Positions

Example 4: Daily Panchanga

Example 5: Vimshottari Dasa Timeline

Example 6: Numerology Calculator

Example 7: Semantic Search of Classical Texts (RAG)

🎓 Step-by-Step Tutorials

Tutorial 1: Understanding Time Format

Tutorial 2: Choosing the Right Ayanamsa

Tutorial 3: Interpreting Match Reports

🔧 Common Use Cases & Demo Files

🔢 Decoded results

⚙️ Optional arguments

🔑 Keys, clients, and configuration

⏳ There is no request timeout by default

🧵 Using it in a server

🧯 Errors

⏱️ Pacing requests and rate limits

📖 What Can You Calculate? (684 Methods)

Core chart analysis (225 methods)

Divisional charts — vargas (102 methods)

Panchanga, muhurta & time (65 methods)

Strength, dignity & Shadbala (62 methods)

Charts, aspects & events (55 methods)

Prashna, chakra & Pancha Pakshi (28 methods)

Ashtakvarga (20 methods)

Dasa — planetary periods (20 methods)

Earthquake research (20 methods)

Longevity & life events (18 methods)

Upagraha & special points (15 methods)

Transit & timing — gochara (13 methods)

Yogas, doshas & kartari (12 methods)

Jaimini & Tajika (8 methods)

AI, ML & text search (7 methods)

Numerology (6 methods)

Compatibility & matching (4 methods)

Health & nature scores (4 methods)

🚀 Why VedAstro? The Simplest & Most Affordable Vedic Astrology API

✨ Unbeatable Value

💰 Pricing That Makes Sense

🏗️ How It Works (Architecture)

🛠️ Development and generation

🤝 Contributing

📄 License

🙏 Support the Project

📚 Additional Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages