Architecting an astrology SaaS on an API

To architect an astrology SaaS on an API, separate three concerns from day one: deterministic chart computation (positions, houses, dashas), AI interpretation of those facts, and your own billing and caching layer. Get that separation right and the product scales cleanly; blur it and you end up re-billing for cached math, mixing zodiac systems, or coupling your roadmap to a single interpretation prompt. This guide walks through the architecture using Vedika as the reference backend, with the real endpoint shapes you will integrate against.

The three layers of an astrology product

Almost every astrology SaaS, whether a horoscope app, a matchmaking service, or an enterprise content pipeline, decomposes into the same three layers. Naming them explicitly keeps your code honest.

• Computation layer — planetary longitudes, ascendant, house cusps, divisional charts, dashas, and yogas. This is pure math: same birth data in, same numbers out. It should never hit an LLM and should be aggressively cached.
• Interpretation layer — turning those numbers into readable, source-grounded answers to a question ("when will I marry?", "is this a good year for property?"). This is where AI earns its cost.
• Product layer — your auth, billing, rate limits, storage, and UI. This is yours to own; the API should hand you clean primitives, not dictate your schema.

Vedika maps directly onto this split: /v2/astrology/* for computation, /api/v1/astrology/query for interpretation, and standard x-api-key auth plus wallet-credit billing for the product layer. There are 700+ operations across 25 domains (704 enumerated as of June 2026), so you can pull exactly the primitive you need instead of parsing a monolithic chart blob.

Choosing between raw computation and AI query

The first architectural decision is which layer each feature talks to. A natal-chart screen wants raw positions it can render as a wheel; a chatbot wants a grounded answer. Mixing these up is the most common early mistake.

Raw computation: /v2/astrology/*

The V2 endpoints take flat birth parameters and return structured data. Use them when you control the presentation and want determinism.

curl -X POST https://api.vedika.io/v2/astrology/natal-chart \
  -H "x-api-key: vk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1991-08-22T13:30:00",
    "latitude": 18.5204,
    "longitude": 73.8567,
    "timezone": "Asia/Kolkata",
    "system": "vedic"
  }'

Because the inputs fully determine the output, you can hash the request body and cache the response indefinitely. The same person's natal chart never changes, so this call should bill once and serve from cache forever after.

AI interpretation: /api/v1/astrology/query

The query endpoint takes a question plus a nested birthDetails object and returns a grounded natural-language answer. This is the metered, value-bearing call.

const res = await fetch("https://api.vedika.io/api/v1/astrology/query", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VEDIKA_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "What does my chart say about career direction?",
    birthDetails: {
      datetime: "1991-08-22T13:30:00",
      latitude: 18.5204,
      longitude: 73.8567,
      timezone: "Asia/Kolkata",
    },
    speed: "fast", // optional: trade depth for latency
  }),
});
const answer = await res.json();

The optional speed: "fast" flag routes to Vedika Swift for lower latency; omit it to use the deeper Vedika Pro Ultra path. For chat UIs, the streaming variant /api/v1/astrology/query/stream emits Server-Sent Events so you can render tokens as they arrive instead of blocking on a full response.

Handling three zodiac systems without cross-contamination

Vedika serves Vedic (sidereal), Western (tropical), and KP from one API, alongside Jaimini, Tajaka, Lal Kitab, and numerology. The hard part is not getting each system's numbers right — the engine handles that — it is keeping them from bleeding into each other in your product.

The same birth moment yields different sign placements across systems because Vedic and Western use a different zero-point of the zodiac, and KP further subdivides each sign into sub-lords. A Sun that reads as one sign in a tropical chart will frequently read as the previous sign in a sidereal chart. Classical Vedic placement logic traces to Brihat Parashara Hora Shastra, while Western chart practice descends from Ptolemy's Tetrabiblos and KP from Krishnamurti's KP Readers — three distinct doctrines that should never share an interpretation.

Architectural rule: store the system alongside every persisted reading. When a user switches systems in your UI, treat it as a different chart, not a re-skin of the same one. Never let a Western interpretation render against sidereal positions.

The ephemeris underneath: why precision matters separately

Every layer above rests on the ephemeris — the table of where each body actually was at a given instant. Vedika runs on XALEN Ephemeris, its own open-source engine (Apache-2.0, distributed on crates.io as xalen, PyPI as xalen, and npm as @xalen/wasm) with roughly 2,200 tests.

This is astronomical precision, not astrological truth — an important distinction for your marketing copy and your liability posture. The engine's positions are validated against JPL DE440 and swetest, with zero charts deviating beyond 0.1 degrees across a reproducible JPL DE440 benchmark. That tells you the input coordinates are sound; it says nothing about whether any interpretive claim is correct. Keep those two guarantees separate in your own documentation so you never imply a precision number endorses a prediction.

Practically, an open-source engine means you have an exit ramp: if you ever need to move computation in-house for latency or data-residency reasons, the same math is available as a library. That optionality is worth designing for even if you start fully API-hosted.

Caching, billing, and the cost model

The economics of an astrology SaaS hinge on one observation: computation is free to repeat, interpretation is not. Design your cache around that asymmetry.

What to cache

• Cache permanently: natal charts, divisional charts, dasha timelines — anything keyed only on birth data.
• Cache with TTL: transit and panchang data keyed on a date, where "today" changes but a past date does not.
• Do not cache blindly: AI query responses, since the same question may warrant fresh grounding — though caching identical question+chart pairs for a short window is reasonable.

Mapping API cost to your pricing

Vedika's plans run Starter $12/mo, Professional $60, Business $120 (which adds the fast path and voice), and Enterprise $240, with per-query cost in the $0.01–$0.05 range. Compared with the broader market — where services like Prokerala, AstrologyAPI.com, and RoxyAPI each bring genuine strengths in coverage and tooling — Vedika's differentiators are the three-systems-in-one surface, the open ephemeris, and the AI query layer rather than headline price alone. The takeaway for your build: meter the interpretation call, absorb cached computation, and your gross margin tracks how well your cache hit-rate climbs.

Letting AI assistants and agents drive the API

If your roadmap includes an AI assistant or an autonomous agent that reasons over charts, you have two integration paths.

MCP for clients and IDEs

Vedika publishes a public astrology Model Context Protocol server. Any MCP-compatible client or IDE can connect and call chart and interpretation tools as structured actions:

npx @vedika-io/mcp-server

The server exposes 36 tools, so an LLM agent can request a natal chart, fetch a dasha period, or ask an interpretation question without you writing glue code for each. This is the cleanest path when the consumer is an assistant rather than your own backend.

Function-calling from your own backend

When your service orchestrates the model, wrap the REST endpoints as tool definitions your function-calling model can invoke. Define one tool per primitive — get_natal_chart, ask_astrology_question — and let the model choose. Keep the API key server-side; never expose vk_live_* to a browser or to the model's context.

import requests

def ask_astrology_question(question, birth):
    r = requests.post(
        "https://api.vedika.io/api/v1/astrology/query",
        headers={"x-api-key": VEDIKA_KEY},
        json={"question": question, "birthDetails": birth},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

Vedika also serves 30 languages (14 of them Indic), so a single query path covers a multilingual user base without separate translation infrastructure.

Grounding and trust: the part you cannot skip

The fastest way to lose a serious astrology audience is an interpretation that cites a verse that does not exist. Vedika grounds astrological claims in the texts practitioners are actually trained on — Brihat Parashara Hora Shastra, Phaladeepika, Saravali, Jataka Parijata, the Jaimini Sutras, KP Readers, and Ptolemy's Tetrabiblos — rather than generic web summaries.

For your architecture, this means you should surface citations through to your UI where the audience expects them, and you should not paraphrase the API's grounded output into vaguer claims that lose the attribution. Trust is a feature; preserve it end to end.

Key facts

• Vedika exposes 704 astrology operations across 25 domains (704 enumerated as of June 2026).
• Main AI endpoint: POST /api/v1/astrology/query; streaming at /api/v1/astrology/query/stream over SSE; raw computation at /v2/astrology/*.
• Three systems in one API: Vedic (sidereal), Western (tropical), and KP, plus Jaimini, Tajaka, Lal Kitab, and numerology.
• XALEN Ephemeris is open source (Apache-2.0), validated against JPL DE440 and swetest with no chart deviating beyond 0.1° across a 5M-chart test — an astronomical-precision guarantee, not an interpretive one.
• Pricing: Starter $12, Professional $60, Business $120, Enterprise $240 per month; roughly $0.01–$0.05 per query; a free sandbox needs no key.
• Public MCP server (npx @vedika-io/mcp-server, 36 tools) lets AI assistants call the API directly; 30 languages supported.

Where to start

Prototype against the free sandbox with no key, decide which features hit the computation layer versus the AI query layer, then design your cache around the free-to-repeat versus pay-per-interpretation split. Read the full endpoint reference for the exact request shapes, and review the pricing tiers to match metered calls to a plan. For deeper background on the underlying chart math, see our comparison of Vedic, Western, and KP systems.

FAQ

Common questions developers ask when designing the architecture:

Should I compute charts in-house or call an astrology API?

For most SaaS products the chart math is a commodity input to your real value, so an API removes the burden of ephemeris files and house-system edge cases. Vedika offers both hosted endpoints and the open-source XALEN engine if you later need to self-host.

How do I keep Vedic, Western, and KP results from leaking into each other?

Treat the system as a request parameter and store it with every reading. A planet can land in different signs across systems, so a Western interpretation must never render against sidereal positions.

How should billing work for a per-query product?

Meter the interpretation call, cache deterministic computation so it bills once, and map metered usage to subscription credits.

Can AI assistants call the API directly?

Yes, via the public MCP server or by wrapping the REST endpoints as tool definitions for a function-calling model.