Short answers to the questions that come up most. The README has runnable examples for each of them.
Which Java versions are supported? Java 21 or newer. The library uses records, pattern
matching, and java.net.http.HttpClient, all of which are standard since Java 21.
Is this a calculation engine? No. It is a client for the remote VedAstro API, so every calculation needs network access. The astrology itself runs on VedAstro's servers.
Does it have any dependencies? No runtime dependencies. Transport uses the JDK's
java.net.http, and a small JSON codec is bundled, so there is no transitive tree to resolve and
no version conflicts with your framework. JUnit is test-scoped only.
How do I add it to my build? Use org.vedastro:vedastro:1.0.0 from Maven Central. The library
also builds from source with the included Maven wrapper (./mvnw -B verify), so you can vendor it
if you prefer.
Are calls blocking? Yes. Every calculator blocks the calling thread until the API responds. That suits a servlet thread or a Java 21 virtual thread; give each request its own thread rather than serialising calls behind one lock.
Is the client thread-safe? Yes. A VedAstroClient is immutable after construction and holds a
pooled HttpClient, so build one at start-up and share it. Creating a client per request would
throw away connection reuse.
How do I set the API key? VedAstroClient.builder().apiKey(System.getenv("VEDASTRO_API_KEY")),
or Calculate.setApiKey(...) for the static facade. An empty key uses the free tier. Never embed a
paid key in a distributed JAR — they are trivially unpacked.
What are the rate limits? The free tier allows five requests per minute, counted per key across every thread and process in your application. Paid keys are quoted as 200 calls per minute by the API's own rate-limit error. Confirm current limits at vedastro.org/API.html.
Does it retry or throttle automatically? Neither. Only the caller knows whether a second
request is safe, so the library leaves both to you. BatchProcessing in the demos shows a paced
multi-threaded version.
Why do methods return Object? Results vary per calculator: objects, arrays, scalars, or SVG
markup. Decoded values are Map, List, String, Double, Boolean, or null. Read them with
Json.asMap, Json.asList, Json.asString, Json.asInt, or a checked cast.
Why is my number 3.0 instead of 3? JSON has one number type, so every number decodes as
Double, matching the Go SDK where all numbers are float64. Use Json.asInt(value, fallback)
when you need a whole number.
Why did my payload come back as a plain value instead of a map? A payload object with exactly
one property is unwrapped to that property's value, the same rule the Python, Node.js and Go SDKs
use. So planetRasiD1Sign may return a Map with Name and DegreesIn, while houseSignName
returns a bare String.
A call failed — what should I check? In order: the API key, the time string
("HH:MM DD/MM/YYYY +HH:MM", 24-hour, DD/MM/YYYY), the coordinate order
(GeoLocation.of(name, longitude, latitude)), and the rate limit. ApiException.getMessage()
carries the API's own explanation.
How do I cancel a request? Interrupt the calling thread — the flag is restored and a
VedAstroException is raised — or set a timeout(...) on the client if your own budget demands a
deadline. There is no timeout by default: a calculation can take milliseconds or minutes, and
the library cannot know what is acceptable for your workload, so a built-in deadline would only
ever truncate a valid answer. To stop a long batch, check
Thread.currentThread().isInterrupted() between calls.
Can two requests use different ayanamsas at once? Yes. client.withAyanamsa(...) scopes the
choice to the calling thread for the duration of the lambda and restores the previous value
afterwards, even if the lambda throws. A client-wide default is set with defaultAyanamsa(...).
Which ayanamsa should I use? Ayanamsa.LAHIRI for Indian astrology (and it is the server
default when you set nothing), Ayanamsa.KRISHNAMURTI for KP, Ayanamsa.FAGAN_BRADLEY for
Western sidereal.
Can I use it with Spring Boot? Yes, and it is the recommended integration: declare one
VedAstroClient as a @Bean and inject it. See Using it in a server.
Can I call an endpoint that the library does not wrap yet? Yes:
client.call("NewEndpointName", Map.of("time", birth)). This is useful while the server is ahead of
a regenerated client.
Can I use this commercially? Yes. MIT licensed, and both the free and paid tiers permit commercial use.