Astrology API: natal chart, Vedic kundli, horoscope matching, transits, BaZi, Korean Saju

An astrology API for apps, sites and AI agents. Get astrology calculations as clean JSON: natal (birth) charts with houses and aspects, synastry, composite and Davison charts, transits with their dates, solar, lunar and planet returns, Moon phases, retrogrades, void of course Moon, planetary hours, Vedic kundli with nakshatras and navamsa, Vimshottari dasha, Sade Sati, Manglik facts, kundli matching (Ashtakoot, 36 points), BaZi Four Pillars, Korean Saju (사주, 만세력) with luck pillars, and astrocartography lines. 25 calculation types in one actor, plus chart wheel images.

• Accurate: planet positions checked against NASA JPL Horizons at 500 random moments per body from 1900 to 2100 (largest error 0.0011 degree for the planets, 0.005 degree for the Moon), and against the Swiss Ephemeris on 400 random charts (planets within 0.0015 degree, houses within 0.0012 degree below 60 degrees of latitude). New and full Moons and sunrise match the US Naval Observatory within one minute.
• Birth places built in: type a city ("Paris, FR", "Houston, TX", "Mumbai"). About 171,000 cities, towns and large villages (places over 1,000 people) with coordinates and time zones, historical daylight saving rules included. No geocoding key needed. Or send latitude, longitude and a time zone.
• Honest about missing birth times: without a time you still get the planets, plus the moment any planet changed sign that day, and no invented houses. Kundli matching lists every possible score when the Moon changed nakshatra or sign that day.
• Kundli matching checked against a major Indian astrology site: on 25 test couples, all 8 koota scores were identical.
• Western, Vedic, Chinese and Korean in one actor: tropical and sidereal (Lahiri), true or mean node, Placidus, Koch, Equal or Whole Sign houses.
• Chart wheel image: add "svg": true for a ready-to-show SVG wheel (light or dark theme).
• Numbers only: no interpretation texts. The actor keeps nothing of its own: your input and results stay in your Apify run storage under your plan's retention.

Who it's for

• Horoscope and astrology apps: natal charts, transits, returns and chart wheels for each user's profile.
• Matchmaking and marriage sites: kundli (horoscope) matching with all 8 koota scores, Manglik facts and the dosha exceptions, for one couple or every pair in a list.
• Astrology blogs and content sites: ephemeris tables, retrograde, ingress and Moon phase calendars for any year.
• Korean saju and fortune apps: 만세력 pillars, 십신, 대운 and 세운 as JSON, with Korean lunar birthdays.
• AI agents and chatbots: exact positions instead of guessed ones, through the Apify API or Apify's MCP server.
• Astrologers and researchers: charts for a whole client list or a data set in one run.

What you can calculate

Type	You get	Without a birth time
natal	Sun to Pluto, nodes (true and mean, north and south), Lilith (mean), Chiron with sign, degree, speed, retrograde, house; Ascendant, MC, Descendant, IC, Vertex; 12 house cusps; aspects with orb and applying/separating; element and modality balance; Moon phase at birth	Planets at 12:00 local time, signChanges for any planet that changed sign that day; no houses or angles
synastry	Both charts, every inter-aspect, house overlays both ways, a count of harmonious and challenging contacts	Moon aspects only within 6 degrees; overlays need the other person's time
composite	Midpoint chart, houses from the midpoint MC; warns when a midpoint is unstable	No houses or angles (both times needed)
davison	The real sky at the time and place halfway between two births (simple or great-circle midpoint)	No houses or angles (both times needed)
transits	Planets at any moment and their aspects to the birth chart, with the dates each transit enters and leaves orb and every exact pass (retrograde passes marked)	Natal Moon and angles left out
solar_return	The exact return moment for a year and its chart, at the birth place or anywhere else	Error TIME_REQUIRED
lunar_return	The next 1 to 13 lunar returns, each with its chart (one result each)	Error TIME_REQUIRED
planet_return	Every exact return of Saturn, Jupiter, Chiron, Uranus, the node and the faster planets up to 2100	Allowed (Moon excepted), with a note that dates can shift
positions	Positions at any moment, tropical and sidereal with nakshatra; houses and angles if you give a place	(no person)
ephemeris	Positions over a date range at any step, one result per step	(no person)
moon_phase	Phase, illumination, Moon sign and distance, age, previous and next new, quarter and full Moons	(no person)
lunations	All new Moons, quarters and full Moons in a range, with the zodiac degree	(no person)
void_of_course	Void of course Moon periods with the last aspect (modern or traditional planets)	(no person)
retrogrades	Station retrograde, station direct and shadow dates for Mercury to Pluto	(no person)
ingresses	Every sign change in a range	(no person)
planetary_hours	Sunrise, sunset and the 24 planetary hours of a day at a place	(no person)
vedic	Kundli: sidereal grahas with rashi, nakshatra, pada and lord, lagna, whole sign houses, navamsa (D9) chart	No lagna or houses; moonNakshatraChanges if the Moon changed nakshatra
dasha	Vimshottari mahadashas, antardashas and pratyantardashas with dates, balance at birth, the periods running now	Moon at 12:00 with a note; a warning if the first mahadasha depends on the time
kundli_matching	Ashtakoot (Guna Milan): the 8 kootas with what each person has and the points, total out of 36, Nadi and Bhakoot doshas with their classical exceptions listed (not applied), Manglik facts for both	alternatives: every possible score when the Moon changed nakshatra, rashi or Vashya group that day
manglik	Mars house counted from lagna, Moon and Venus, both house lists, the classical cancellations (facts, no verdict)	No lagna check; one check per possible sign when a body changed sign that day
sade_sati	Every Sade Sati period with rising, peak and setting dates (days in the birth time zone, plus the exact moment of each Saturn crossing), the dhaiya periods, and whether one is running now	One result per possible Moon rashi if it changed that day
bazi	Year, month, day and hour pillars with Chinese characters, hidden stems, element counts, solar terms, true solar time	No hour pillar; a note when a solar term (or Li Chun, the year start) fell that day
saju	Korean Saju (사주): four pillars in hangul and hanja, ten gods (십신) for every stem, branch and Korean hidden stem (지장간), element counts, luck pillars (대운) with start age and dates, year pillars (세운), Korean lunar birthday (음력) in or out	No hour pillar; luck pillars counted from noon; a note when 입춘 or a solar term fell that day
astrocartography	MC, IC, AC and DC lines for each planet, and the lines nearest to any city with distances in km	Error TIME_REQUIRED
places	City search: coordinates, region, country, time zone, population	(no person)

Input

Simple: pick a calculation and list people. Every person gets the calculation; two-person types pair them (pairing: consecutive 1 with 2, 3 with 4; firstWithEach; allPairs, up to 141 people). For kundli matching the first person of each pair is the boy, the second the girl.

{
  "calculation": "natal",
  "people": [
    { "name": "Ann", "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" },
    { "name": "Raj", "date": "1985-03-02", "time": "06:10", "latitude": 19.076, "longitude": 72.8777, "timezone": "Asia/Kolkata" }
  ],
  "options": { "houseSystem": "whole" }
}

Advanced: any mix of calculations in requests. If you only use requests, set Calculation to "None" in the form.

{
  "requests": [
    { "id": "chart-1", "type": "natal", "person": { "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" }, "svg": true },
    { "type": "synastry", "person": { "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" },
      "partner": { "date": "1988-02-03", "time": "21:15", "city": "New York" } },
    { "type": "kundli_matching", "boy": { "date": "1990-07-14", "time": "08:30", "city": "Mumbai" },
      "girl": { "date": "1992-03-02", "time": "10:00", "city": "Delhi" } },
    { "type": "transits", "person": { "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" }, "at": "2026-10-16" },
    { "type": "moon_phase", "at": "2026-10-16", "timezone": "Europe/Paris" },
    { "type": "retrogrades", "from": "2026-01-01", "to": "2026-12-31", "timezone": "America/New_York" },
    { "type": "places", "query": "Springfield, IL" }
  ]
}

A person

Field
date	YYYY-MM-DD, 1900 to 2100 (required)
time	HH:MM, 24-hour local time. Leave it out if unknown. A time needs a place
city	"Paris", "Paris, FR", "Paris, Texas", "Houston, TX". The biggest match wins; others are listed in place.otherMatches
latitude, longitude	Decimal degrees, north and east positive. Need timezone or utcOffset too
timezone	IANA name such as America/New_York (history and daylight saving applied)
utcOffset	"+05:30", "-03:00" or hours (5.5). Fixes the birth moment; later event times use timezone when given
ambiguousTime	"earlier" (default) or "later", for a local time that happened twice when clocks went back
name or id	Copied to the result
sex	"male" or "female": saju only, sets the direction of the luck pillars (대운)
calendar, leapMonth	saju only: "lunar" reads date as a Korean lunar date (음력, 1900 to 2099); leapMonth: true for a leap month (윤달)

A moment (at)

"2026-10-16" (12:00 that day), "2026-10-16T10:00:00Z", or { "date": "2026-10-16", "time": "21:30", "timezone": "Asia/Tokyo" }. The place (city, latitude, longitude, timezone, utcOffset) can go inside at or next to it. Default: now. A local time skipped or repeated by a clock change gives a warning.

Options

Option	Types	Values (default first)
houseSystem	chart types, positions	placidus, koch, equal, whole
orbs	chart types except transits	{ "conjunction": 6, "quincunx": 0 } degrees per aspect type (0 to 15; 0 turns a type off). Default 8/10 conjunction and opposition, 7/9 square and trine, 5/7 sextile, 3/5 quincunx (wider with the Sun or Moon)
svg, svgTheme, svgSize	natal, composite, davison, solar_return, lunar_return	false/true; light/dark; 600 (100 to 4000) pixels. The aspect lines in the image use the default orbs
at	transits, positions, moon_phase, dasha, sade_sati	a moment (see above), default now
orb, includeDates	transits	"natal" or one number of degrees for every aspect (0.5 to 10); true/false (false skips the dates, faster)
method	davison	simple, great_circle
year, returnPlace	solar_return	current year (must be after the birth year); a place like a person's
from, count, returnPlace	lunar_return	today; 1 (up to 13); a place
body, max	planet_return	saturn (or jupiter, chiron, uranus, node, sun, moon, mercury, venus, mars); up to 300 returns
bodies	positions, ephemeris, retrogrades, ingresses, astrocartography	list such as ["sun", "moon", "chiron"] (names below)
sidereal	positions, ephemeris	false/true (adds Lahiri sidereal positions and nakshatras)
from, to, timezone	range types	YYYY-MM-DD; days start at midnight in timezone (UTC by default)
step, stepUnit, maxSteps	ephemeris	1; days/hours; 1,000 (up to 5,000 rows per request). Daily steps fall at local midnight
quarters	lunations	true/false (false: new and full Moons only)
planets	void_of_course	modern (Sun to Pluto) or traditional (Sun to Saturn)
date + a place	planetary_hours	the day (default today); the place needs an IANA time zone (a city gives one)
query, max	places	the city text; 5 (up to 20) matches
nodeType, includeOuterPlanets	vedic	true or mean node; false/true (Uranus, Neptune, Pluto)
yearLength, levels, at	dasha	julian (365.25 days), sidereal, savana (360); 2 (1 to 3); the date for "running now"
boy, girl	kundli_matching	people (or person = boy and partner = girl)
trueSolarTime, dayStartsAt23	bazi	true/false each
timeRule, dayChange, at	saju	korean (default: KST minus 30 minutes, the usual 만세력 rule, Korea's old time zones and summer time handled), local_mean_time, true_solar_time or clock; rat_hour (default: the new day starts at 23:00), midnight_late_rat (야자시) or midnight; the date for the year pillars (default now)
lineMode, near, nearCount, resolution	astrocartography	mundo or zodiac; a place; 10 (1 to 40); 1 degree of latitude between line points (0.5, 1, 2, 5 or 10)

Booleans take true/false (also "yes"/"no"). Body names (any case): sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, northNode, northNodeMean, southNode, southNodeMean, lilith, chiron. Each type lists the ones it accepts in its error message.

Output

One dataset row per result. Every row has type, apiVersion (the output format's version: fields are only renamed or removed with a new major version), request (its position in your input) and your id if you gave one. Person types add person, and place when a city was given (two-person types person/partner or boy/girl, with places). Positions always come as longitude (0 to 360), sign, degree within the sign and a readable position ("21°34'25" Cancer"). Times come in UTC and in the local time of the place. Distances: distanceAu for planets, distanceKm for the Moon.

Excerpt of a natal row:

{
  "type": "natal", "request": 1, "id": "chart-1",
  "person": { "date": "1990-07-14", "time": "08:30" },
  "place": { "name": "Paris", "country": "France", "latitude": 48.8534, "longitude": 2.3488, "timezone": "Europe/Paris" },
  "chart": {
    "moment": { "utc": "1990-07-14T06:30:00Z", "local": "1990-07-14T08:30:00+02:00", "utcOffset": "+02:00" },
    "planets": [ { "body": "sun", "longitude": 111.57375, "sign": "Cancer", "degree": 21.57375, "position": "21°34'25\" Cancer", "speed": 0.953723, "house": 12 } ],
    "angles": { "ascendant": { "position": "17°47'06\" Leo" }, "midheaven": { "position": "3°58'00\" Taurus" } },
    "houses": { "system": "placidus", "cusps": [ { "house": 1, "position": "17°47'06\" Leo" } ] },
    "aspects": [ { "a": "jupiter", "b": "saturn", "type": "opposition", "orb": 0.2192, "applying": false } ]
  }
}

Typical row sizes: natal 9 KB (25 KB with the wheel image), synastry 30 KB, transits 20 KB, astrocartography 41 KB, kundli matching 4 KB, dasha with 3 levels 116 KB.

Errors

A request that cannot be calculated gives a free row with error: { code, message }, and the run carries on.

Code	When
BAD_INPUT	A field is missing or malformed (date, time, option value)
PLACE_NOT_FOUND	No city matches the text
TIME_REQUIRED	The type needs a birth time (solar and lunar returns, astrocartography, Moon returns)
OUT_OF_RANGE	A date outside 1900 to 2100
NO_RESULT	Nothing to return (for example no Uranus return before 2100)
UNKNOWN_TYPE	The type is not one of the 25
INTERNAL	An unexpected failure (please report it)

A problem with the whole input (nothing to calculate, an odd number of people with consecutive pairing, more than 10,000 calculations) stops the run before anything is calculated, with the reason in the run's status. A run whose first 200 calculations all fail stops early too.

Limits

Limit	Value
Dates	1900 to 2100
Calculations per run	10,000 (allPairs: up to 141 people)
Date ranges	ephemeris up to 100 years and 5,000 rows; lunations, retrogrades and ingresses 10 years; void of course Moon and Moon ingresses 400 days. Without to: 30 days (ephemeris, void of course) or 365 days (the others)
Bodies per request	the list above, repeats ignored
Speed	measured on Apify at the default 1 GB: 1,000 birth charts in 52 s, 500 Vedic charts and dashas in 20 s, 190 kundli matchings in 16 s; transits about 5 s each. Apify gives more processor to more memory (4 GB is a full core, about 4 times faster), at the same cost per result: for big transit or planet return batches raise the memory or split the batch, so the run ends within its time limit

Pricing

USD 1.50 per 1,000 results (USD 0.0015 each), plus Apify's small start fee per run (USD 0.00005). No subscription, and platform usage is included. One charge per dataset row that holds a result. Error rows are free. Your spending limit is checked before every calculation, so the run stops cleanly when it is reached. One request can make several results: lunar_return with count: 3 makes 3, and an ephemeris request makes one per step (a default 30-day range is 31).

Use it as an API

Call the actor synchronously and get the rows back in one request (runs up to 300 seconds; a fresh run takes a few seconds to start):

POST https://api.apify.com/v2/acts/usefulapi~astrology-api/run-sync-get-dataset-items
Authorization: Bearer <your Apify token>
Content-Type: application/json
{ "requests": [ { "type": "natal", "person": { "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" } } ] }

FAQ

Is there a free trial? Apify's free plan includes monthly platform credit that you can spend on this actor. At USD 1.50 per 1,000 results, it covers thousands of charts.

Does it write horoscope texts or readings? No. It returns numbers and facts: positions, signs, houses, aspects, dates, scores. You write the text, or give the JSON to your own AI model.

Which zodiacs and house systems? Tropical (Western) and sidereal with the Lahiri ayanamsa (Vedic); Placidus, Koch, Equal and Whole Sign houses; true or mean node.

What if the birth time is unknown? Leave time out. You get the planets for that day and the moments any planet changed sign, but no houses or Ascendant, because they cannot be known without a time.

How is it different from horoscope scrapers? It calculates everything itself from astronomical formulas, so nothing depends on another website and it does not break when one changes.

Can I call it from my own app? Yes: see "Use it as an API" above. One HTTP request returns the results as JSON.

Accuracy and method

• Planets: VSOP87 (truncated) with light time, aberration and nutation; Moon: Meeus chapter 47 full tables; Pluto: Meeus chapter 37; Chiron: a JPL table. Checked against NASA JPL Horizons at 500 random moments per body, 1900 to 2100, and against the Swiss Ephemeris on 400 random charts.
• Houses checked against a brute-force solver and the Swiss Ephemeris; Placidus and Koch switch to Whole Sign beyond about 66 degrees of latitude (they are undefined there), and the result says so. The Vertex is the western crossing of the prime vertical, as in the Swiss Ephemeris.
• Lilith is the mean lunar apogee from the standard (Meeus) polynomial. It differs from the Swiss Ephemeris' mean Lilith by up to 0.12 degree (a periodic difference), so Lilith can sit in a neighbouring pada.
• Sidereal: Lahiri (Chitrapaksha) ayanamsa with nutation. The Vedic chart was checked against a published AstroSage kundli.
• Sunrise, sunset and Moon phases checked against the US Naval Observatory; retrograde dates against JPL Horizons and the Old Farmer's Almanac.
• Kundli matching: tables from 26 sources (B. V. Raman's Muhurtha, Saravali, Drik Panchang and others), then checked against Prokerala's matching calculator on 25 test couples: every one of the 8 scores identical for all 25. It also reproduces the published Prokerala and AstroSage sample reports. AstroSage, checked on 17 more couples, gives the same scores for 7 of the 8 kootas; on Yoni it uses its own unpublished table (8 of 17 couples differ by 1 or 2 points), so totals from AstroSage can differ from Prokerala's and ours. Each result lists where traditions differ (knownDifferences).
• Vedic positions, dasha, Sade Sati and BaZi were spot-checked on a test chart (Mumbai, 1985): every planet within 2 arc-seconds of the Swiss Ephemeris (Lahiri). AstroSage's positions for the same chart differ from the Swiss Ephemeris by up to 2 arc-minutes (Jupiter), and its Moon by 23 arc-seconds, so its Vimshottari dates run 3 to 5 days later than ours (it also adds the dasha balance as calendar months and days). Sade Sati: the same Saturn crossings as AstroSage's table in 42 of 44 rows; AstroSage lists the sign Saturn holds at about noon each day, so a crossing after noon shows there one day later. Our dates are in the birth time zone, with the exact moment of each crossing. BaZi pillars match fixed published dates (for example 1 January 2000 is a 戊午 day, 1 October 1949 a 甲子 day).
• Korean Saju: the Korean lunar calendar matches every month of the Korea Astronomy and Space Science Institute (KASI) tables 1900 to 2050 (1,867 of 1,867, with their day pillars), and solar terms match KASI within one minute. On 11 test births against two Korean 만세력 sites, 29 of 33 charts are identical and the luck pillar start and direction match 22 of 22; the other 4 are documented method differences of those sites (a flat 32-minute correction that ignores Korea's 1954-61 time zone or keeps the clock date past midnight, and an assumed birth time on a solar-term day).
• Places: GeoNames places with over 1,000 people plus some smaller seats of government (CC BY 4.0); smaller villages need latitude and longitude. Time zones: IANA, with corrections for zones whose pre-1970 history is merged in common time zone libraries.

Not included: interpretation texts, ayanamsas other than Lahiri, asteroids other than Chiron, progressions, divisional charts other than D9, ashtakavarga, panchang. Labels are in English. Dates 1900 to 2100.

Not affiliated with or endorsed by NASA, the US Naval Observatory, the Swiss Ephemeris authors, AstroSage, Prokerala, the Old Farmer's Almanac or GeoNames; they are named only as the references the results were checked against.