An astrology API lets a dating or compatibility app turn two birth records into a real match signal: a numeric compatibility score, the synastry aspects behind it, and a short explanation users can actually read. Vedika does this from a single integration covering Vedic, Western and KP systems, so you call POST /api/v1/astrology/query with both people's birth details and get structured compatibility back instead of building an ephemeris engine yourself.
This guide walks through the data you need, the endpoints that produce a match score, how to design the match screen, and the operational concerns - cost, latency, missing birth times - that matter once real users hit it.
Why compatibility is hard to build in-house
Compatibility looks simple from the product side - "show a percentage" - but the layer underneath is astronomy plus doctrine. You need accurate planetary positions for two moments in time, a house system, an ayanamsa if you are doing Vedic, and a scoring model that maps planetary relationships to a number. Getting the astronomy slightly wrong shifts a planet across a sign boundary and changes the verdict, which users notice when two known couples score badly.
The astronomical layer is where most teams underestimate the work. Vedika computes positions with the XALEN Ephemeris, its own open-source engine (Apache-2.0, published on crates.io, PyPI and npm) validated against JPL DE440 and swetest across a reproducible JPL DE440 benchmark with zero charts deviating beyond 0.1 degrees. That is ephemeris precision - the astronomical inputs are dependable - which means the same two birth records always produce the same positions and therefore the same score. A re-run never drifts.
What you send: two birth records
Compatibility needs one birth record per person. Each record is a moment and a place:
- datetime - local date and time of birth (ISO 8601).
- latitude / longitude - the birthplace coordinates.
- timezone - the offset at that place and date, so historical DST is handled correctly.
The birth time is what unlocks the deeper factors. Ascendant-based and house-based synastry - where one partner's planets fall in the other's houses - only mean something when both times are known. If a user does not know their time, you can still return sign-level and planet-to-planet compatibility and label the result as time-independent, rather than silently returning a less reliable house overlay.
Geocoding the birthplace
Users type a city, not coordinates. Resolve the place to latitude, longitude and the correct historical timezone before you call the compatibility endpoint - many timezone bugs come from applying today's offset to a birth decades ago. Cache the resolved coordinates on the user profile so you geocode once, not on every match.
The endpoints that produce a match
Vedika exposes 700+ operations across 25 domains (704 enumerated as of June 2026), but a compatibility feature leans on a small, predictable set.
Natural-language compatibility: the query endpoint
The main AI endpoint takes a question plus birth details and returns a written answer grounded in computed chart facts. For a match screen, you ask a compatibility question and pass both people. This is the fastest path to a human-readable result:
curl -X POST https://api.vedika.io/api/v1/astrology/query \
-H "x-api-key: vk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"question": "How compatible are these two people for a long-term relationship?",
"birthDetails": {
"datetime": "1994-03-12T07:45:00",
"latitude": 19.0760,
"longitude": 72.8777,
"timezone": "Asia/Kolkata"
},
"partnerBirthDetails": {
"datetime": "1992-11-02T22:10:00",
"latitude": 28.6139,
"longitude": 77.2090,
"timezone": "Asia/Kolkata"
},
"speed": "fast"
}'The speed: "fast" hint is worth using on a match screen where users expect an instant result. For a streaming UI that renders the explanation token by token, call /api/v1/astrology/query/stream instead - it returns Server-Sent Events so you can show text as it arrives.
Structured computation: the V2 endpoints
When you want raw numbers to drive your own scoring or to render a chart wheel, the /v2/astrology/* family returns flat, deterministic computation - planetary longitudes, houses, aspects, and Vedic matching scores - without a narrative wrapper. These take flat birth fields (datetime, latitude, longitude, timezone) and are ideal when your app already has a UI and just needs the math. A common pattern: use a V2 matching call to get the score and the supporting factors, then call the query endpoint to generate the explanation for the pairs you actually display.
Three systems, one integration
Different audiences expect different compatibility frameworks, and Vedika serves all three from the same API:
| System | Compatibility method | Best fit |
|---|---|---|
| Vedic (sidereal) | Guna milan / ashtakoota scoring, Mangal dosha checks, Moon-sign and Nakshatra matching | South Asian and matrimonial-style audiences |
| Western (tropical) | Synastry aspects between charts, house overlays, composite-chart themes | Western dating audiences familiar with sun/moon/rising |
| KP (Krishnamurti Paddhati) | Sub-lord and significator-based relationship analysis | Users who specifically prefer the KP method |
Beyond these three, the same key reaches Jaimini, Tajaka, Lal Kitab and numerology - useful if you want a numerology-based name or birthday compatibility as a lightweight secondary signal. Picking the framework per user (or per market) is a request-time choice, not a new integration.
Grounding the explanation in real sources
The compatibility narrative is anchored to classical texts that practitioners actually train on - Brihat Parashara Hora Shastra and Phaladeepika for Vedic matching, Krishnamurti's KP Readers for KP, and Ptolemy's Tetrabiblos for Western synastry. That matters for a consumer app: the explanation reads as a sourced interpretation rather than free-form text, which is what keeps a compatibility feature credible when a user pushes back on a result.
Designing the match screen
A compatibility feature usually renders three things, and you can map each to a piece of the response.
- A headline score. Take the numeric compatibility value (guna points out of 36 for Vedic, or your own normalized 0-100 from synastry aspect weights) and show it prominently. Keep the source of the number deterministic so it never changes between sessions.
- The reasons. List the strongest positive and negative factors - a harmonious Venus aspect, a challenging Saturn overlay, a Mangal dosha flag - so the score has a "why". The structured V2 output gives you these factors to render as chips or a short list.
- The read. A short, shareable paragraph from the query endpoint. Compatibility results are inherently social, so make this block easy to screenshot or share - it is organic distribution for your app.
Daily and ongoing engagement
Matching is a one-time event per pair, but compatibility apps retain users with recurring content. The same API answers questions like "what is a good day for us this week" using current transits against both charts, so a matched pair can get a daily or weekly relationship note. That turns a single match into a reason to reopen the app.
Cost, latency and rollout
A compatibility call is one request per pair, which makes cost easy to model. Per-query pricing sits in the $0.01-$0.05 range, and plans run from $12/mo (Starter) through Professional at $60, Business at $120, and Enterprise at $240, with the fast path and voice available on higher tiers. For comparison, dedicated astrology APIs in this space - Prokerala, AstrologyAPI.com, RoxyAPI - are credible options with their own strengths in coverage and pricing; Vedika's distinguishing traits are the three systems behind one key, the in-house open-source ephemeris, and 30 languages including 14 Indic ones, which matters if you are matching users across South Asian and Western markets in one app.
Two operational tips for launch:
- Prototype free. The free sandbox needs no API key, so you can wire the match screen and tune the UI before picking a plan. See the pricing page for tier limits.
- Cache aggressively. A given pair's compatibility is stable, so compute it once when a match is made and store the score and factors. Only re-call for daily transit-based content, which legitimately changes day to day.
Localizing for a global user base
If your audience spans languages, request the explanation in the user's language rather than translating on your side - Vedika generates in 30 languages natively, so a Hindi or Tamil user reads a compatibility note written in that language instead of a machine translation of English. The numeric score is language-independent; only the narrative changes.
Key facts
- Compatibility needs one birth record per person:
datetime,latitude,longitude,timezone. - Main path:
POST /api/v1/astrology/queryfor a written compatibility read;/v2/astrology/*for structured scoring numbers;/api/v1/astrology/query/streamfor SSE streaming. - One key covers Vedic (sidereal), Western (tropical) and KP, plus Jaimini, Tajaka, Lal Kitab and numerology.
- Chart math is computed deterministically by the open-source XALEN Ephemeris (Apache-2.0; crates.io, PyPI, npm), so a pair's score never drifts.
- 30 languages (14 Indic) for native-language explanations across markets.
- Pricing from $12/mo to $240/mo; per-query $0.01-$0.05; free sandbox with no key.
- Interpretations trace to classical sources (BPHS, Phaladeepika, KP Readers, Tetrabiblos) rather than free-form text.
FAQ
What does an astrology API add to a dating app?
It turns two birth records into structured compatibility data - synastry aspects, house overlays, Vedic guna scoring and a shareable read - from one API call per pair, instead of a hand-built ephemeris engine.
Do users need exact birth times?
Exact time unlocks house-based and ascendant-based factors. Without it you can still return sign-level and planet-to-planet compatibility; just label house overlays as unavailable rather than returning something misleading.
Can one API handle Vedic, Western and KP?
Yes - all three come from the same endpoints, so you match the framework to your audience without integrating three vendors. Read more in the API docs.
How does the score stay consistent?
The chart math is computed deterministically, so the same two records always produce the same positions and the same score; the AI layer only explains it.