Some astrology APIs return only numbers. Then, when a customer's own astrologer disagrees, your team has nothing to point at. Support tickets stall, and the customer starts to doubt every screen in your app. The fix is an API that names the rule behind each answer. Each rule has a stable rule ID that links to a public rulebook.
A rule you can point to
Our API states the rule behind each yoga and dosha answer in plain words. It says why the rule did or did not apply. Dosha answers also list the classical exceptions they found, without applying them for you. So a disagreement with the output becomes a disagreement about one rule. It might be about Lahiri or another ayanamsa, or whole-sign houses or Placidus. It might be about one table of kootas (matching factors) or another.
That small change moves the conversation from "your app is wrong" to "we use this rule, and here is where it comes from." The first sentence cannot be answered. The second one can be checked, discussed and, if needed, changed.
An example with John Doe
Say Acme Inc. runs a matchmaking app. John Doe, born on August 15, 1990 at 10:30 AM in New York, opens his chart and sees that manglik dosha is present. He worries, and he shows the screen to his family astrologer. The astrologer looks at the chart and says it is fine, because Mars sits in its own sign.
Now picture two versions of this story.
In the first version, the API returned only a flag: manglik, yes. John writes to support. The support team cannot see why the flag is yes, and cannot say whether the astrologer is right. They send a vague reply. John decides he cannot trust the app and leaves.
In the second version, the API returned the rule together with the answer. For John, the manglik check says that Mars sits in house 1, 2, 4, 7, 8 or 12. These houses are counted from the ascendant (rising sign), from the Moon and from Venus. The check says the dosha is present. It also lists one classical exception it found: Mars is in its own sign. The API lists that exception but does not apply it. Whether to apply it is a choice for the astrologer or for your product.
Now both people are right. John's chart does match the rule, and his astrologer is pointing at a real exception. Your support team can say exactly that, in one short message, and John keeps trusting the app.
Every rule has an ID
The public rulebook lists every rule the API follows, each with a stable ID. CH-06 says houses are whole-sign. KM-01 lists the eight kootas of guna milan. DO-02 covers the exceptions to manglik dosha. Astrologers already cite classical texts. With rule IDs, your support team can cite something too.
A stable ID helps in a few ways:
Your support team can write "this result follows rule DO-02" and link to the rulebook, instead of guessing.
Your engineers can see which rule an answer came from when they debug a report from a customer.
Your astrologers, if you have any, can read the rule once. Then they can tell you whether they accept it, instead of testing the output case by case.
When a rule changes, the ID makes it easy to talk about what changed and why. Our changelog names the rule in every fix that changes results.
Where disagreements usually come from
When two astrology tools give different answers for the same person, the cause is usually not a bug. It is a different choice somewhere in the method. These are the usual ones:
The ayanamsa. Lahiri is the most common, but other ayanamsas shift every planet by a small amount. A planet near the edge of a sign can land in a different sign.
The house system. Whole-sign houses and Placidus houses can put the same planet in different houses.
The tables. Guna milan uses a table for each koota, and published tables are not all the same.
The birth time and place. A few minutes can move the rising sign, and a wrong time zone can move it a lot.
The exceptions. Some tools apply a classical exception silently, and others ignore it. Either way, the user sees a different answer.
If the API shows its rules, each of these becomes a line you can read. You do not have to guess it from the output.
Why this also helps your own team
A stated rule is not only for customers. New engineers learn the product faster when each answer names its rule. They can read the rule instead of guessing what the code meant. Reviewers can ask a clear question: is this the rule we want? And when an astrologer on your team wants a different choice, you can talk about just that rule. You do not have to reopen the whole product.
How to show rules in your app
You do not need to put long text on every screen. A simple pattern works well. Show the answer first, in plain words. Under it, add a small "Why this result" link that opens the rule in one or two sentences. An AI chatbot can quote the same rule, as long as it calls the API instead of guessing the chart. For a dosha, also show the exceptions the API listed, and label them clearly as "possible exceptions, for an astrologer to judge."
This keeps the main screen calm for most users. It also gives the curious user, or the customer's astrologer, everything they need to check the work. And it helps your support team, because the same wording appears in the app and in the rulebook.
What to ask a provider
If you are comparing astrology APIs, ask for one real response and look for the rule behind it. If there is none, you are buying a number you cannot check. Here are a few good questions to ask:
Does each yoga and dosha answer say which rule it used, and why it applied or did not?
Are classical exceptions listed, and is it clear whether they were applied?
Is there a public list of rules with stable IDs, so you can link to it?
Can you choose or at least see the ayanamsa and the house system?
Is there a page that explains how the results were tested?
A provider that can answer these questions is saying that it expects to be checked. That is a good sign. Below is a real manglik dosha answer from our API, for the same John Doe described above. Read it the way an astrologer would: find the rule first, then the answer, then the exceptions.
