New Numerology API

Readings

Astrology Reading and Report API

The astrology reading API from API for Astrology (apiforastrology.com) turns a birth chart into plain English text your users can read.

Updated

© API for Astrology (apiforastrology.com). "Readings and reports explained". All rights reserved. Not to be copied or reused.John Doe's birth chartJohn Doe: your readingPersonalityYou tend to have a clear sense ofwho you are, and people oftennotice it.CareerLove and marriageWealth

How the astrology reading API works

  1. 1A birth chart is full of symbols that most people can't read.
  2. 2The API turns it into plain English, topic by topic, such as personality, career, love and money.
  3. 3It returns readings as text, a short summary with no jargon, and a full report ready to print.
POST /v1/reading/section/topic:personality?as_of=2026-10-01200 OK
{
  "section": {
    "id": "topic:personality"
  },
  "blocks": [
    {
      "answer": {
        "headline": "You tend to have a clear sense of who you are, and people often notice it. Energy and confidence usually come easily to you, and you bounce back well when life gets hard."
      }
    }
  ]
}
The plain answer that opens John Doe's personality reading, one of the life topics. Real output for John Doe, born Aug 15, 1990, 10:30 AM, New York.

Call the astrology reading API from your code

Send the details as JSON with your API key in the Authorization header. Copy the code, set ASTROLOGY_API_KEY to your key, and run it.

POST /v1/reading/section/planet:Mars

# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/reading/section/planet:Mars?as_of=2026-10-01" \
  -H "Authorization: Bearer $ASTROLOGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":8,"day":15,"hour":10,"minute":30,"second":0,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'
Response (lists shortened)200 OK
{
  "section": {
    "id": "planet:Mars",
    "group": "planet",
    "title": "Mars"
  },
  "blocks": [
    {
      "id": "attribute:own_sign:Mars",
      "title": "Mars · own sign",
      "family": "attribute",
      "score": 3,
      "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.",
        "Your courage is real, and it is usually the first thing people notice about you. In Aries it shows as speed: you act while others are still talking. In Scorpio it is held back and aimed: you wait for the right moment, and then you don't…",
        "Either way, the force does what it means to do and does not ask permission first. The risk is conflict you didn't need, because Mars in its own sign rarely backs down. So decide on purpose which fights are worth having."
      ],
      "language": "en",
      "detail": "standard",
      "graha": "Mars",
      "attribute": "own_sign",
      "themes": [
        "direct force",
        "unqualified courage"
      ]
    },
    {
      "id": "planet_sign:Mars:1",
      "title": "Mars in Aries",
      "family": "planet_sign",
      "score": 2,
      "text": [
        "Mars rules Aries, so it acts here without asking anyone's permission. Mars is the planet of your energy, courage and drive, and Aries is its own fire sign. So no other planet stands in between, and nothing slows it down.",
        "You usually act first and think later. You start things by doing, not by planning on paper: you sign up for the race, then train. Your courage is often the first thing people notice about you. So is your impatience with anyone who dithers.…",
        "Without a direction, this energy turns inward. Mars with nothing to push against turns into irritation, restlessness and arguing for the sake of it. You need something demanding to aim at: physical work, a hard problem or a contest. Once…"
      ],
      "language": "en",
      "detail": "standard",
      "graha": "Mars",
      "themes": [
        "courage",
        "directness",
        "impatience"
      ]
    },
    {
      "id": "planet_house:Mars:8",
      "title": "Mars in the 8th house",
      "family": "planet_house",
      "score": 3,
      "text": [
        "Mars sits in your eighth house, the part of the chart for hidden matters, sudden change and shared money. You look into things properly. Mars is a planet of action, so here your energy goes into digging and into handling crises. Research,…",
        "You have strong stamina, so you get through what happens to you and aren't easily scared by the next thing. What to watch is your taste for intensity, because after a while it can start choosing the events for you."
      ],
      "language": "en",
      "detail": "standard",
      "graha": "Mars",
      "themes": [
        "surgery and risk",
        "investigation",
        "disputed inheritance"
      ]
    }
  ],
  "gaps": [],
  "language": "en",
  "detail": "standard",
  "fell_back_to_en": false,
  "in_short": {
    "outcome": "strained",
    "lines": [
      "Mars is under some pressure in your chart. What it looks after may need more effort and patience from you.",
      "In your chart, it looks after your own effort, your nerve, and brothers and sisters. It also looks after upheaval, inheritance, and what is shared or kept hidden.",
      "Its effects show most in upheaval, inheritance, and what is shared or kept hidden."
    ],
    "basis": {
      "graha": "Mars",
      "owns": [
        3,
        8
      ],
      "house": 8
    }
  },
  "tendency": {
    "graha": "Mars",
    "house": 8,
    "verdict": "mixed",
    "leans": "strains",
    "counts": {
      "supports": 1,
      "strains": 2
    },
    "supports": [
      {
        "kind": "tendency_dignity_strong",
        "graha": "Mars",
        "says": "Mars is in Aries (own sign)"
      }
    ],
    "strains": [
      {
        "kind": "tendency_rules_dusthana",
        "graha": "Mars",
        "says": "Mars rules the 8th house, a dusthana"
      },
      {
        "kind": "tendency_in_dusthana",
        "graha": "Mars",
        "says": "Mars stands in the 8th, a dusthana"
      }
    ],
    "noted": [],
    "not_evaluated": [],
    "rule": "supports only -> favorable; strains only -> difficult; both -> mixed; neither -> plain. Nothing is weighted; `leans` counts the two lists and does not score them."
  },
  "meta": {
    "ayanamsa": "lahiri",
    "ayanamsa_value": 23.7260727,
    "julian_day": 2448119.10483,
    "ephemeris": "JPL DE440s",
    "node": "true",
    "timezone": {
      "source": "zone",
      "offset_hours": -4,
      "zone": "America/New_York",
      "abbreviation": "EDT",
      "dst": true,
      "dst_hours": 1,
      "ambiguous_resolved_by_fold": null,
      "note": "read from the IANA tz database at this instant, so daylight saving and historical offset changes are included"
    }
  }
}

What the astrology reading API returns

  • Readings on 32 topics, such as personality, career, love and marriage, wealth, health, family and home, sade sati (Saturn's seven-and-a-half-year period) and remedies. The life topics start with a plain answer.
  • A summary of the whole chart, about two to three printed pages, with no planet names, signs or Sanskrit. Each part says what it is based on.
  • A love, career or wealth forecast over a date range. It lists the periods and transits (the planets' current positions) that matter, with a reading for each. When two transits pull opposite ways at the same time, it names the clash and picks no winner.
  • A printable report: one self-contained HTML page with every section, ready to print to PDF, with no outside files.
  • Readings by section: the rising sign, the Moon sign, each planet, each house, the yogas (planet combinations) and the doshas (chart flaws).
  • Daily horoscopes, for a Moon sign or for one chart, have their own page: see the horoscope API below.

The same birth details always get the same words, because the text comes from a fixed library, not an AI model. Where no text is written yet for a combination, the response lists it as a gap instead of filling it with vague words. Send detail=expanded for longer text.

What it uses from your plan

Calculations use 1 call each. Written readings use reading credits instead:

  • One chapter1 credit
  • Life summary2 credits
  • The year-ahead chapter3 credits
  • Love, career or wealth forecast3 credits
  • Full report25 credits
  • Topic chapters in the full report+15 credits
What reading credits buy

Astrology reading API endpoints

The rules behind the astrology reading API

A life topic is read from the houses, their rulers and the karakas, the planets linked to each topic (LP-01). It is built from the chart, not stored as one paragraph (LP-03). When two rules in a chart point opposite ways, the reading names the disagreement and never averages it (RC-01). Nothing is weighted in secret: each reading states its rule (RD-02). Retrograde planets (those that seem to move backward) are reported but never counted (RD-04). Monthly readings are built on the transits (MF-01).

How we check the numbers

Every answer here starts from planet positions worked out from NASA JPL planet data (DE440). We test them against NASA JPL Horizons, NASA's planet position service. On 25,571 positions from 1850 to 2149, the Sun and planets agree within 0.001 arc seconds. The Moon agrees within 0.011. On 2,000 random birth charts, the rising sign agrees with Swiss Ephemeris within 0.004. An arc second is 1/3,600 of a degree. Our tests fail if a result drifts past these figures.

A practicing astrologer reviews the rules behind these answers. Each rule has an ID you can look up in the public rulebook.

See how we test accuracy

32 topic readings

Each topic is one chapter, called by its id. Open a family to see its readings.

Life prediction11 readingsShow
  • Personality and self topic:personality
  • Career and work topic:professional-life
  • Love and relationships topic:love-and-marriage
  • Money and wealth topic:wealth
  • Learning and education topic:education
  • Health and wellbeing topic:health-and-wellbeing
  • Family and home topic:family-and-home
  • Life purpose and milestones topic:life-purpose
  • Friends and social life topic:friends-and-social
  • Travel and relocation topic:travel-and-relocation
  • Favorable and unfavorable periods topic:favorable-periods
Monthly forecast6 readingsShow
  • Career topic:monthly-career
  • Love life topic:monthly-love
  • Wealth topic:monthly-wealth
  • Favorable and unfavorable days topic:monthly-days
  • Tips for the month topic:monthly-tips
  • Transits this month topic:monthly-transits
Sade sati6 readingsShow
  • Predictions topic:sadesati-predictions
  • What to expect topic:sadesati-expect
  • Rising period topic:sadesati-rising
  • Peak period topic:sadesati-peak
  • Setting period topic:sadesati-setting
  • Remedies topic:sadesati-remedies
Remedies9 readingsShow
  • Life gemstone topic:remedy-life-gemstone
  • Lucky gemstone topic:remedy-lucky-gemstone
  • Rudraksha topic:remedy-rudraksha
  • Lucky mantra topic:remedy-lucky-mantra
  • Havan and puja topic:remedy-havan-puja
  • General remedies topic:remedy-general
  • Sade sati remedies topic:remedy-sadesati
  • Kaal sarp remedies topic:remedy-kaal-sarp
  • Pitra dosha remedies topic:remedy-pitra-dosha

The printable report

The report opens with a short summary in plain words, then these chapters. “Where your chart disagrees with itself” shows where the chart's rules point in opposite directions.

  1. 1Your signature
  2. 2Your birth details
  3. 3The chart
  4. 4Your periods
  5. 5The grahas
  6. 6The houses
  7. 7Where your chart disagrees with itself
  8. 8What the chart forms
  9. 9What is moving nowOnly when you send a date (as_of)
  10. 10The topic readingsOnly when you ask for them (topics=true)

Sample report

A full kundli report from one call

One request returns a printable report with 11 chapters on the chart, the houses, the planetary periods and more. Read the one we made for John Doe before you build yours.

From the blog

Astrology reading API questions

All questions
Which topics can I get readings on?

32 topics in four groups: 11 life topics such as personality, career, love, wealth, health and travel; 6 monthly forecasts; 6 on sade sati; and 9 remedies. Every chart lists all 32. The sade sati and dosha remedy topics answer only when the chart has them.

See every topic id
How do I fetch a full reading?

First call POST /v1/reading/sections to get the sections this chart has, then fetch the ones you need from POST /v1/reading/section/{section_id}, such as planet:Mars or topic:personality. Or call POST /v1/report for every section in one printable page.

Can I write my own text from your rules?

Yes. POST /v1/reading/rules returns every rule the chart triggers, but no reading text. Each rule has its ID, family, title, the planets and houses it is about, and its score. Use it to drive your own copy, or to check why a section says what it says.

Browse the rulebook
Is there a version for readers who know no astrology?

Yes. POST /v1/summary covers the whole chart in about two to three printed pages, with no planet names, signs or Sanskrit. Each of its twelve sections has a because field that names what it is based on, so the plain wording can still be checked.

Can I put my own title on the report?

Yes: send title to set the heading, which is the rising sign by default. Add as_of for the transit and forecast chapters, and topics=true for the topic readings. For another language, add lang=hi for Hindi. The page loads nothing from outside, so it opens and prints offline.

See a sample report
Will a reading change from one day to the next?

Only the parts tied to a date, so send as_of to fix it. The transit and monthly sections are worked out for that date. The remedy sections follow the main period running then, and the sade sati sections answer for the phase running then.

Astrology API

Call it with a free test key

Create an account and a test key, then call any endpoint on this page. Or try a request in the API reference first.

Your first answer

John Doe, New York

POST /v1/planets200 OK
  • RisingVirgoHast
  • SunCancerAshlesha
  • MoonTaurusMrigashira
  • MarsAriesKrittika

Real API output. A free test key gets the same answer.

  1. 01

    Test key: 1,000 test calls a month to build with

  2. 02

    Free plan: 2,000 live calls a month, no card needed

  3. 03

    Open rules: every rule is published, so you can check any answer