Astrology API conventions: zodiac, time zones and language

Zodiac and houses

Positions use the sidereal zodiac of Vedic astrology, which measures the 12 signs against the stars. By default they use the Lahiri ayanamsa, the gap in degrees between this zodiac and the Western one. Houses are the 12 parts of a chart. The API uses whole-sign houses: each house is one full sign, counted from the rising sign (the ascendant). Planet positions come from the JPL DE440s ephemeris. It is planetary data published by NASA’s Jet Propulsion Laboratory (JPL).

To choose the ayanamsa, add ayanamsa to the birth details: lahiri (Lahiri, the default), kp (Krishnamurti, used in KP astrology), raman (B. V. Raman's), yukteshwar (Sri Yukteshwar's), fagan_bradley (Fagan-Bradley, the Western sidereal zodiac), jn_bhasin (J. N. Bhasin's), ushashashi (Usha-Shashi) or true_chitra (True Chitrapaksha, which keeps the star Spica at 180°). Transits, sade sati and forecasts for that chart use the same one. Transits are where the planets are on a given day. Sade sati is a Saturn period of about 7.5 years. Every response names the ayanamsa in meta.ayanamsa. Calls about two people, such as kundli matching (comparing two birth charts for marriage), need the same ayanamsa for both. If not, they get a 422 error. The ayanamsa guide compares the three on one real chart.

Rahu and Ketu are the two lunar nodes, the points where the Moon’s path crosses the Sun’s path. By default the API uses their true position. Add "node": "mean" to the birth details for the averaged position instead. In John Doe’s chart, Rahu sits at 13.5 degrees of its sign with the true node. With the mean node, it is at 12.7. Every response names the one it used in meta.node.

Times and time zones

Send the local clock time at the place of birth. Add the latitude, the longitude and a time zone name from the IANA time zone database, such as America/New_York or America/Chicago. The API looks up the offset for that exact date. So it handles daylight saving time and old time zone changes for you. The response shows the offset it used in meta.timezone.

You can send a fixed UTC offset in hours instead, such as -5. The API then uses that offset exactly as given.

When clocks go back, one local time happens twice. The API will not guess which one you mean. It returns 422 unless you add timezone_fold: 0 for the first time and 1 for the second. Or send the offset you mean as timezone.

When clocks go forward, one local time never happens. An example is 2:30 AM on March 8, 2026 in New York. The API returns 422 for that time too. Check the birth time, or send the UTC offset that was really in use. Five common mistakes, each with a real chart, are in time zone errors in birth charts.

Birth details always need latitude, longitude and timezone. Some GET endpoints take a date and place in the query string, and for them all three are optional. Examples are the daily panchang (the Hindu calendar for a day), the month calendar, festivals and vrats (fasting days). Others are tara bala (a daily rating from your birth star) and the daily Moon-sign horoscope. Without a place, they use Ujjain, India, the traditional reference place. GET /v1/sky also uses India time (UTC+5:30). The place block in the response says when this happened. Always send your own place.

Supported dates

The API supports dates from 1850 to 2149. That is the range of the NASA JPL planetary data it uses. A date outside it returns 422.

Are readings in plain English?

Yes. Reading text comes from a fixed library of passages written ahead of time in plain English. Published rules pick the passages that fit a chart. No AI model writes or changes them, so the same birth details always get the same words. Send detail=expanded for longer text, or a lang code for another language.

Each passage is tied to one chart condition, such as a planet in a sign it rules. The block’s id names that condition. Here is the first block of John Doe’s Mars reading, from POST /v1/reading/section/planet:Mars:

{
  "id": "attribute:own_sign:Mars",
  "title": "Mars · own sign",
  "text": [
    "Your energy is direct. Mars is in its own sign, one of the two it rules, so nothing stands between it and the job. Mars is the planet of energy and courage, and at home it holds nothing back."
  ],
  "language": "en",
  "detail": "standard"
}

attribute:own_sign:Mars means Mars sits in one of the two signs it rules. All 480 rules that pick and rank passages are in the rulebook, each with its own ID. POST /v1/reading/rules lists the rules a chart triggers, without the text. When a fix changes a rule, the changelog names its ID.

On Nov 2, 2026, we asked for John Doe’s Sun reading twice. Both answers were the same, word for word. Sections that depend on a date, such as transits, change with as_of. It defaults to today, so set it when you need the same words every day. If no passage is written yet for a combination, the response lists it in gaps. The API does not fill the space with vague text.

The detail option sets the length: standard (the default) or expanded. How much longer depends on the section. In John Doe’s chart, the expanded Sun reading is about 1.8 times as long. His expanded Moon sign reading is about 1.9 times as long. If a passage has no expanded version yet, you get the standard one. Each text block says which length it got in its own detail field. See every section in the readings feature and the section IDs.

Can the API answer in Hindi?

Yes. Add lang=hi for Hindi to any /v1/ call. Names of planets, signs, nakshatras and festivals come back in that language, and so does reading text. Each translated name keeps its English original in a field ending in _en. Field names, codes, rule notes and error messages stay in English.

Here is the Sun from John Doe’s chart, from POST /v1/planets?lang=hi:

{
  "positions": [
    {
      "name": "सूर्य",
      "sign": "कर्क",
      "degree_in_sign": 28.7753409,
      "nakshatra": "आश्लेषा",
      "dignity": "मित्र क्षेत्र",
      "name_en": "Sun",
      "sign_en": "Cancer",
      "nakshatra_en": "Ashlesha",
      "dignity_en": "friend"
    }
  ],
  "localization": {
    "language": "hi",
    "untranslated": []
  }
}

The localization block says which language you got. Its untranslated list names any value still in English. For John Doe’s chart, the list is empty. Supported languages: en, hi.

Use the _en fields as keys in your code. Every response names planets, signs and nakshatras, so match on the English name, not on the position in a list.

Reading text comes in Hindi too. Here is the Mars passage from the example above, with lang=hi:

आपकी ऊर्जा सीधी है। मंगल अपनी राशि में है, यानी उन दो राशियों में से एक में जिनका वह स्वामी है। इसलिए उसके और हाथ के काम के बीच कुछ नहीं आता। मंगल ऊर्जा और हिम्मत का ग्रह है, और अपने घर में वह कुछ नहीं रोकता।

If a passage is not written in Hindi yet, you get the English one. A reading response then has fell_back_to_en set to true, and that block’s language says en.

Some parts stay in English on purpose: field names, codes such as own_sign, endpoint paths and error messages. Method notes stay in English too, such as the rule field of a dosha check, which states the test the API ran.