Astrology API documentation

Vedic astrology is the traditional astrology of India. Dashas are planet periods, and the panchang is the Hindu calendar for a day. Every request goes to https://apiforastrology.com/api/astrology with your API key in a header. The full URL of an endpoint is this base URL plus its path, such as /v1/planets.

Keys, rate limits and errors work the same way for every API. The docs home covers them and lists the quickstart for each API.

Defaults: sidereal zodiac, Lahiri ayanamsa and whole-sign houses. KP uses Placidus cusps. Send the time zone as a name, such as America/New_York. The conventions explain each one.

# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/planets" \
  -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"}'

• Quickstart: make your first callGet a key and make your first call in a few minutes.
• Authentication and rate limitsSend your key in a header, keep it safe, and know your limits.
• Errors and how to handle themWhat each status code means and what to do about it.
• API referenceEvery endpoint, with examples you can run in the browser.
• ConventionsThe zodiac (the 12 signs), houses (the 12 parts of a chart), time zones, dates, language and text length.
• Vedic vs Western astrologyWhy Vedic signs differ from Western ones, and what to tell your users.
• Lahiri, KP and Raman ayanamsaAll eight ayanamsas, the main three compared on one real chart, what moves when you switch, and which to send.
• Use with AI assistantsWhich endpoints to offer a chatbot as tools, and which fields to quote.
• Sections and IDsEvery reading section, festival and fasting-day id, and what each one means.
• ChangelogWhat changed in the API, newest first.

Before you build

These inputs change what the API returns.

• Send the time zone as a name, such as America/New_York, so daylight saving time is applied for that date. A local time that happens twice or never, when clocks change, gets a 422 error, not a guess. For a repeated time, add timezone_fold: 0 or 1. Times and time zones
• The ayanamsa (the zodiac offset) is Lahiri unless you send ayanamsa as kp or raman or yukteshwar or fagan_bradley or jn_bhasin or ushashashi or true_chitra. A different one can move a planet near the edge of a sign into the next sign. Matching needs the same one for both people. Zodiac and houses
• Rahu and Ketu (the Moon’s nodes) use the true node, the actual position, by default. Send "node": "mean" for the averaged position. Each response names its choice in meta.node. True and mean nodes
• Positions are sidereal (Vedic) only. For a Western (tropical) longitude, add meta.ayanamsa_value, then subtract 360 if the sum passes 360. Vedic vs Western
• hour and minute default to 0, so a missing birth time becomes midnight and the rising sign may be wrong. With no birth time, use routes that need only the birth star (nakshatra), such as GET /v1/tara and POST /v1/matching/nakshatra.
• Above the polar circles, a day can have no sunrise. Routes that count from sunrise, such as the daily panchang, then return 422 with no_sunrise. POST /v1/kp refuses places beyond 66 degrees north or south. Birth charts still work there. Errors
• Dates run from 1850 to 2149, the range of the NASA JPL planet data. A date outside it gets a 422 error. Supported dates

API reference by group

• Meta2 endpoints. Check the service health, the options the API supports and its limits.
• Charts15 endpoints. Planet positions, the ascendant (rising sign), aspects (each planet's influence on other houses) and planet strength. It also gives the 16 divisional charts, which split each sign into smaller parts. The bhava chalit chart, special lagnas (extra rising points) and upagrahas (sensitive points such as Gulika) are here too.
• Dasha4 endpoints. Vimshottari, Yogini and Ashtottari dashas, with the start and end dates of every period.
• KP1 endpoint. KP (Krishnamurti Paddhati) astrology: Placidus house cusps, and the sign, star, sub and sub-sub lords of every planet and cusp. Each house lists its significators, the planets that give its results.
• Panchang4 endpoints. The daily panchang and its five parts, with horas (planetary hours) and rahu kaal (a daily time to avoid). It also gives choghadiya, parts of the day marked good, neutral or bad.
• Interpretation4 endpoints. Yogas (planet combinations), doshas (chart flaws) and sade sati (Saturn's 7.5-year period). Each yoga and dosha names the classical rule it tested. Also the planet states (avasthas), each with its reason.
• Remedies3 endpoints. Remedies chosen from the chart, each with its reason: rudraksha beads, gemstones, a lucky mantra, havan and puja, and everyday remedies. Also the remedies for sade sati, kaal sarp and pitra dosha.
• Transits7 endpoints. Gochar (where the planets are on a given day, compared with a birth chart), forecasts, sign changes and themes for the year.
• Matching4 endpoints. Marriage matching: the 36-point ashtakoot score and the South Indian dashakoot checks. It also gives parasparam (each person's planets in the other's houses) and papa samyam (a count of harmful planets).
• Reading13 endpoints. Readings by topic, daily readings, a karma reading and reports you can print.
• Horary3 endpoints. Horary (prashna): a question asked at a moment, read from a chart cast for that moment and place. You pick the topic from a list; a sentence is never read. The question chart describes the tendencies of the moment and is not a promise. Some questions are refused outright (lifespan, the sex of an unborn child, lotteries and gambling, medical diagnosis, accusing a person of a crime, testing), and a moment the classical texts call unfit to judge is refused too, with the reason. A refusal is 422 and carries no reading. Every route for questions asked at a moment is in this group.
• Muhurta5 endpoints. Festival and vrat (fasting day) dates for a year at a place, and good times to start an activity.