# Astrology API: Natal Chart, Kundli & Horoscope Matching (`usefulapi/astrology-api`) Actor

Astrology API for apps and sites: natal birth charts, transits, synastry, Vedic kundli, dasha, horoscope (kundli) matching, BaZi and Korean Saju (사주) as JSON, with chart wheel images. NASA JPL-checked accuracy, 171,000 cities built in. USD 1.50 per 1,000 results, no subscription.

- **URL**: https://apify.com/usefulapi/astrology-api.md
- **Developed by:** [Useful API](https://apify.com/usefulapi) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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.

```json
{
  "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.

```json
{
  "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:

```json
{
  "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](https://www.geonames.org/) 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.

# Actor input Schema

## `calculation` (type: `string`):

One calculation for every person in People (two-person charts use pairs; sky calculations such as Moon phase need no person). Choose None if you only use Requests below, otherwise this example runs too.

## `people` (type: `array`):

Birth data, one object per person: date (YYYY-MM-DD, 1900-2100), time (HH:MM, 24-hour; leave out if unknown), and the place as city ("Paris, FR", "Houston, TX") or latitude + longitude + timezone (IANA name such as "America/New_York") or utcOffset ("+05:30"). Optional: name or id (copied to the result), sex ("male" or "female", for the Saju luck pillars), calendar ("lunar" for a Korean lunar birthday, with leapMonth true for a leap month), ambiguousTime ("earlier" or "later", for a local time that happened twice when clocks went back).

## `pairing` (type: `string`):

How People are paired for synastry, composite, Davison and kundli matching (for kundli matching the first of each pair is the boy, the second the girl).

## `options` (type: `object`):

Settings for the calculation, for example { "houseSystem": "whole" }. Common: houseSystem (placidus, koch, equal, whole), svg (true adds a chart wheel image; svgTheme light or dark), orbs ({ "conjunction": 6 }, 0 turns a type off). By type: transits at ({ "date": "2026-10-16", "time": "12:00", "timezone": "Europe/Paris" } or { "datetime": "2026-10-16T10:00:00Z" }; default now), orb (number or "natal"); solar_return year, returnPlace; lunar_return from, count (1-13); planet_return body (saturn, jupiter, chiron...); saju timeRule (korean, local_mean_time, true_solar_time, clock) and dayChange (rat_hour, midnight_late_rat, midnight); date-range types from, to (YYYY-MM-DD), timezone, bodies; vedic nodeType (true, mean), includeOuterPlanets; dasha yearLength (julian, sidereal, savana), levels (1-3); bazi trueSolarTime, dayStartsAt23; astrocartography lineMode (mundo, zodiac), near ({ "city": "Tokyo" }). Full list in the README.

## `requests` (type: `array`):

A list of calculations, each an object with a type and its own settings, for example \[{ "type": "natal", "person": { "date": "1990-07-14", "time": "08:30", "city": "Paris, FR" } }, { "type": "moon_phase" }]. Two-person types take person and partner. Add id to any request to find it in the results. Runs together with the calculation above unless Calculation is None. Up to 10,000 calculations per run.

## Actor input object example

```json
{
  "calculation": "natal",
  "people": [
    {
      "name": "Example",
      "date": "1990-07-14",
      "time": "08:30",
      "city": "Paris, FR"
    }
  ],
  "pairing": "consecutive",
  "options": {}
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "calculation": "natal",
    "people": [
        {
            "name": "Example",
            "date": "1990-07-14",
            "time": "08:30",
            "city": "Paris, FR"
        }
    ],
    "options": {}
};

// Run the Actor and wait for it to finish
const run = await client.actor("usefulapi/astrology-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "calculation": "natal",
    "people": [{
            "name": "Example",
            "date": "1990-07-14",
            "time": "08:30",
            "city": "Paris, FR",
        }],
    "options": {},
}

# Run the Actor and wait for it to finish
run = client.actor("usefulapi/astrology-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "calculation": "natal",
  "people": [
    {
      "name": "Example",
      "date": "1990-07-14",
      "time": "08:30",
      "city": "Paris, FR"
    }
  ],
  "options": {}
}' |
apify call usefulapi/astrology-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,usefulapi/astrology-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/emeRmjnTPJcBc4H38/builds/CJfwnl9GBRc5ppaDS/openapi.json