Skip to content

About

Official Java client for the VedAstro Vedic astrology API - 684 calculations, zero runtime dependencies

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

🪐 VedAstro for Java

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

Maven coordinates Java version License Stars


🎯 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

package org.vedastro.demos;

import org.vedastro.GeoLocation;
import org.vedastro.Json;
import org.vedastro.Time;
import org.vedastro.VedAstroClient;
import org.vedastro.calculate.Calculators;
import org.vedastro.calculate.DasaSystem;

/**
 * DEMO: Vimshottari Dasa life timeline.
 *
 * <p>USE CASE: list every planetary period in the system-defined life
 * <p>DIFFICULTY: Intermediate
 *
 * <p>RUN: {@code mvn -q exec:java -Dexec.mainClass=org.vedastro.demos.VimshottariDasa}
 */
public final class VimshottariDasa {

    private VimshottariDasa() {
    }

    public static void main(String[] args) {
        VedAstroClient client = DemoSupport.client();

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

        // The convenient overload omits optional arguments and uses the server defaults.
        Object timeline = client.calculate().dasaForLife(birth);
        System.out.println("Vimshottari life, server defaults:");
        System.out.println(Json.encode(timeline));

        // The full overload selects the starting rule and the nesting depth.
        var options = new Calculators.DasaForLifeOptions();
        options.system = DasaSystem.VIMSHOTTARI_JANMA; // Moon-based Janma
        options.depth = 2;                             // Mahadasa -> Bhukti
        Object tuned = client.calculate().dasaForLife(birth, options);
        System.out.println();
        System.out.println("Janma Vimshottari, depth=2:");
        System.out.println(Json.encode(tuned));
    }
}

👉 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:

  1. Graha Maitram (5 pts) — mental compatibility, happiness
  2. Gana (6 pts) — temperament match (Deva/Manushya/Rakshasa)
  3. Yoni (4 pts) — sexual compatibility
  4. Nadi (8 pts) — health and progeny (traditionally weighted most heavily)
  5. Varna (1 pt) — spiritual/ego compatibility
  6. …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
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)

DasaSystems, DasaAtTime, DasaForLife (use the language-specific naming shown in the examples). 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:

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


📚 Additional Resources


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

🪐 Empowering developers to build amazing astrology apps since 2020

About

Official Java client for the VedAstro Vedic astrology API - 684 calculations, zero runtime dependencies

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages