An astrology app needs more than planet positions. Users want readings: what the chart says about career, love or money, and a report they can keep. Sometimes the reading text comes from a different system than the chart. Then the two will disagree sooner or later, and users notice. Our astrology API avoids this by building the chart, every reading and the full report from one calculation.
Why charts and readings drift apart
Many teams build this in two parts. One service calculates the chart. Another service, or a pile of text templates, writes the readings. It works on day one. Then something changes on one side only. It might be a new ayanamsa (the gap between the Vedic and Western zodiacs). Or it might be a different house setting, or a fix to a planet position. The chart now says one thing and the reading still says another.
Here is how that looks to a user. John Doe, born on August 15, 1990 at 10:30 AM in New York, opens your app. The chart screen shows his rising sign. A few taps later, the career reading talks about a different rising sign. John does not know which system is right, and he has no way to find out. He only knows that your app said two different things. That is enough to lose his trust.
One calculation, many outputs
Our API writes its readings from the same calculation that produces the chart. It returns 27 topic readings. They are grouped as life predictions, monthly forecasts, sade sati (a Saturn period of about seven and a half years) and remedies. It also returns a full report as HTML. One chapter of the report shows where the chart's own rules point in opposite directions, instead of hiding the conflict.
Because everything starts from one calculation, there is no second chart hiding behind the readings. The chart and the readings share the same settings, such as the Lahiri ayanamsa and whole-sign houses. So a fix to the calculation reaches both at once. They cannot drift, because there is nothing to drift between.
What a reading looks like
A reading is not a long essay with no structure. It is split into sections. Each section has its own ID: ascendant, nakshatra, planet:Mars, house:7, or a life topic such as topic:personality. A section opens with a short, plain answer, then goes deeper. For John Doe, the personality section opens with a clear headline about how other people tend to see him. You can show that headline on a card, and let the user open the rest if they want more.
This shape helps your design. You can ask for the list of sections first. It returns only an ID, a title and a group for each, with no text. Then you build a list of cards and fetch only the sections you show. You do not have to load a whole report to show one paragraph.
Readings in more than one language
The same call returns the text in English, Hindi or another language the API serves. GET /v1/meta lists them. Values are translated too, such as weekdays, colors, sign names and gemstone names. If a passage is not written in that language yet, the English passage comes back instead and is marked. So nothing is left blank. Endpoint paths, field names and error messages stay in English, so your engineers keep one client.
This also keeps your languages in step. A user who switches from English to Hindi sees the same chart and the same reading, written in a different language. They do not get a different answer.
Which endpoints to call
Call POST /v1/planets for the chart, POST /v1/reading/section/{section_id} for one reading section, and POST /v1/report for the full document. The report comes back as HTML, so convert it to PDF on your side if you need a file.
A simple plan for a first version looks like this:
When the user enters birth details, call the planets endpoint and draw the chart.
Call POST /v1/reading/sections to see which sections are available for this chart, and show one card for each.
When the user opens a card, call the section endpoint with that section's ID and the same birth details.
Add a "Download report" button that calls the report endpoint. Send topics=true if you want the 27 topic readings inside it.
Every call takes the same birth details: date, time and place. Send the same details each time, and the answers will agree with each other.
Readings for a date
Some sections depend on today's sky, such as a forecast or the period a person is running now. For these, you pass an as_of date in the format YYYY-MM-DD. It tells the API which day to read the sky for. In the full report, the transit and forecast chapters appear only when you send as_of. So add it when you want them.
Short or longer text
Both endpoints take a detail setting. The default is standard. The other choice is expanded, which is about 1.8 times longer. A phone card can use the standard text, and a printed report can use the expanded text. If a passage has no expanded version yet, you get the standard one, so nothing is left blank.
When the chart disagrees with itself
Real charts often contain rules that point in opposite directions. One placement may be called helpful by one rule and difficult by another. Many products smooth this over and show only the pleasant half. We think that is a mistake. A user who later hears the other half from an astrologer will feel misled.
In the full report, one chapter lays these conflicts out in plain words. For John Doe, a reader sees both sides next to each other, with the reason for each. Your app can show the chapter as it is, or link to it from a short summary card. Either way, nothing is hidden, and the report still matches the chart on the first screen.
Making the report yours
The report is one self-contained HTML page with print styles. Your users can print it to PDF from any browser. You can also open it in a web view inside your app. If you want your own heading, send a title, such as "John Doe, birth report for Acme Inc." Without a title, the report uses the ascendant sign as its heading.
What to check before you ship
Before you release, run through a short list:
Open the chart and a reading for the same person, side by side. Do the rising sign and the planet signs agree?
Switch the lang setting to hi and check that the values still match.
Read a report from start to finish, including the chapter that shows opposing rules. Make sure your design leaves it visible, not hidden behind a fold.
Try a person with an unusual birth time, such as just after midnight. Look at how your app shows the date.
If those pass, your users will see one story from the first screen to the last page of the report. Below is the opening of a real personality reading for John Doe.
