# Life Manual (`awake_froghopper/chinese-bazi-four-pillars`) Actor

Chinese astrology & BaZi API: Four Pillars of Destiny (Saju) birth chart, Chinese zodiac horoscope, Day Master personality, Five Elements (Wu Xing), lucky colors & numbers, Feng Shui Kua, 2026 Year of the Horse forecast, love compatibility. No LLM, no stored data. From $0.30.

- **URL**: https://apify.com/awake_froghopper/chinese-bazi-four-pillars.md
- **Developed by:** [Wayne Blomfield](https://apify.com/awake_froghopper) (community)
- **Categories:** AI, Agents, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Life Manual — Chinese Astrology, BaZi & Four Pillars of Destiny API (Chinese Zodiac, Birth Chart, Feng Shui, Compatibility)

**Your Chinese "life manual" from one birth date.** Enter a birth date, time and city timezone and get a complete **Chinese astrology profile** as clean JSON:
your **Chinese zodiac animal + element** (e.g. *Fire Horse*), **Day Master personality archetype** (The Sun, The Ocean, The Jewel...), **Five Elements balance**,
**lucky colors, numbers, directions & gemstones**, **Feng Shui Kua number**, **2026 Year of the Fire Horse / 2027 Fire Goat forecast themes**, your 10-year luck pillar,
a **Western sun sign crossover** — and optional **love compatibility** with a partner. Under the hood: a full, verified **BaZi / Four Pillars of Destiny (八字)** chart.

🔮 Deterministic rules from classical BaZi — **no LLM, no random text, no stored birth data.** Same input → same output, every time.

**In one sentence:** Life Manual is a Chinese astrology and Chinese horoscope API that turns a birth date, time and timezone into a full BaZi birth chart (Four Pillars of Destiny, 八字, also called Saju 사주 in Korea) plus a plain-English reading: Chinese zodiac sign and element, Day Master personality test-style archetype, Five Elements (Wu Xing) balance, lucky colors, lucky numbers, lucky directions and lucky gemstones, Feng Shui Kua number, a yearly horoscope for 2026 Year of the Fire Horse and 2027 Year of the Fire Goat (Tai Sui), 10-year luck pillars, Western zodiac sun sign crossover, and love compatibility / couple compatibility for dating apps.

### ✨ What you get (one row per person — pick modules, or take the Full Life Manual)

| Feature | Output field | Example |
|---|---|---|
| Chinese zodiac animal + element, traits, best matches, clash | `zodiacProfile` | Metal Horse · best: Goat, Tiger, Dog · clashes: Rat |
| Day Master personality (10 archetypes) | `dayMasterProfile` | Yang Metal "The Sword / Axe" — strengths, challenges, career affinities |
| Five Elements balance & Day Master strength | `elementBalance` | Fire dominant, Wood weakest · favourable: Wood, Water |
| Lucky colors / numbers / directions / gemstones / seasons | `luckyCharms` | green, navy · 3, 8, 1, 6 · East, North · jade, obsidian |
| Feng Shui Kua number (Eight Mansions) | `fengShuiKua` | Kua 1 (East group) · Sheng Qi = SE |
| 2026 & 2027 yearly forecast themes, Tai Sui | `forecast.thisYear/nextYear` | 2026 Fire Horse: Ben Ming year (Tai Sui) |
| Current & next 10-year luck pillar in plain English | `forecast.currentLuckPillar` | 2017–2026: opportunities, windfalls, networking |
| Western zodiac crossover | `westernCrossover` | Metal Horse × Taurus |
| 💞 Compatibility (with `partner` input) | `compatibility` | score 0–100, zodiac + Day Master + spouse-palace relations |
| Full BaZi chart: pillars, ten gods, hidden stems, luck pillars (大运), annual pillars (流年), shen sha (神煞), lunar date | `pillars`, `daYun`, `liuNian`, `shenSha`... | 庚午 辛巳 庚辰 壬午 |

#### Sample output (abridged)

```json
{
  "fourPillars": "庚午 辛巳 庚辰 壬午",
  "zodiacProfile": { "label": "Metal Horse", "traits": "Energetic, free-spirited and warm; loves movement and adventure.",
                     "bestMatches": ["Goat", "Tiger", "Dog"], "clashesWith": "Rat" },
  "dayMasterProfile": { "archetype": "The Sword / Axe", "element": "Yang Metal", "strength": "balanced",
                        "careerAffinities": ["engineering", "sports", "surgery", "operations"] },
  "elementBalance": { "dominantElement": "Fire", "weakestElement": "Wood", "favorableElements": ["Wood", "Water"] },
  "luckyCharms": { "colors": ["green", "teal", "black", "navy"], "numbers": [3, 8, 1, 6], "directions": ["East", "Southeast", "North"] },
  "fengShuiKua": { "number": 1, "group": "East" },
  "westernCrossover": { "sunSign": "Taurus", "eastWestLabel": "Metal Horse x Taurus with a Yang Metal Day Master" },
  "forecast": { "thisYear": { "label": "Fire Horse", "tenGod": "七杀",
                "taiSui": "Ben Ming Nian: your own zodiac year (Tai Sui year) - traditionally a year to stay humble and steady." } },
  "compatibility": { "score": 68, "label": "moderate", "dayMasterRelation": "generating cycle (Earth nourishes Metal)" }
}
```

### 🔎 Chinese astrology terms this Actor covers (glossary)

- **Chinese astrology / Chinese horoscope / Eastern astrology:** the classical Chinese metaphysics (Mingli, 命理) system of reading a birth chart from the Chinese calendar.
- **BaZi, Four Pillars of Destiny, Saju:** the year, month, day and hour pillars of a birth chart (natal chart) written in heavenly stems and earthly branches. BaZi (Chinese) and Saju (Korean) use the same Four Pillars, which this Actor computes.
- **Chinese zodiac sign:** your animal sign (Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Goat/Sheep, Monkey, Rooster, Dog, Pig) plus its element, e.g. Fire Horse or Water Rabbit, with personality traits, best zodiac compatibility matches and clashes.
- **Day Master:** the day stem that represents you; mapped to ten personality archetypes (a personality test for astrology fans) with strengths, challenges and career ideas.
- **Five Elements / Wu Xing:** Wood, Fire, Earth, Metal and Water balance of the chart, element strength and favourable elements.
- **Lucky colors, lucky numbers, lucky directions, lucky gemstones and crystals:** derived from your favourable elements.
- **Feng Shui Kua number:** the Eight Mansions life gua with four lucky and four unlucky directions for home and desk placement.
- **Yearly horoscope and Tai Sui:** 2026 Year of the Horse (Fire Horse) and 2027 Year of the Goat (Fire Goat) themes for Chinese New Year content, including Ben Ming Nian (your own zodiac year).
- **Luck pillars (Da Yun) and annual pillars (Liu Nian):** 10-year destiny cycles and year-by-year pillars.
- **Love compatibility / synastry-style match:** compares two BaZi charts (zodiac, spouse palace, Day Master and elements) and returns a 0–100 love match score for couples, friends and dating apps.
- **Western zodiac crossover:** your sun sign (e.g. Taurus, Leo) combined with your Chinese zodiac sign, e.g. Metal Horse × Taurus.
- **Chinese lunar calendar:** accepts lunar birth dates (with leap months) and returns the lunar date, solar terms, ten gods, shen sha (symbolic stars) and hidden stems.

Not included: this Actor does not do tarot, I Ching, numerology life path numbers, Zi Wei Dou Shu (Purple Star astrology / Tu Vi) or Western natal chart planets. It pairs well with spiritual, tarot and numerology apps that want a Chinese birth chart layer.

### ❓ FAQ

- **Is this a Chinese horoscope API or a BaZi calculator?** Both: a BaZi / Four Pillars calculator underneath, with ready-to-show Chinese horoscope, zodiac and fortune-telling-style texts on top.
- **What is my Chinese zodiac sign?** The year pillar decides it, switching at Lichun (around Feb 4), not on Jan 1. Life Manual handles that boundary exactly.
- **Can I use it for a dating app or couple compatibility quiz?** Yes. Add a `partner` to get a love compatibility score with reasons.
- **Does it work for Korean Saju?** It returns the same Four Pillars (stems and branches, ten gods, luck pillars); readings are written in English with Chinese terms.
- **Is it fortune telling?** It is for entertainment, cultural education and self-reflection; texts are fixed rules, not predictions.
- **Can AI agents call it?** Yes, via the Apify MCP server (Claude, Cursor, ChatGPT and other MCP clients).

### 🚀 Use cases

- **Astrology & horoscope apps / websites** — instant "Chinese zodiac + BaZi reading" pages, daily/yearly content
- **Discord / Telegram / WhatsApp bots** — `/myzodiac`, `/luckycolor`, `/compatibility` commands
- **Personality quizzes & dating apps** — Day Master archetypes and love-match scores
- **Content creators** — batch 500 charts for Year of the Horse 2026 videos, newsletters, personalised readings
- **AI agents, ChatGPT/Claude tools & MCP clients** — give your agent a correct chart and rule-based facts instead of hallucinated calendar math
- **Feng Shui & wellness brands** — Kua directions, lucky elements and colors for product recommendations
- **Spiritual, metaphysics & esoteric apps** — add a Chinese astrology birth chart next to tarot or numerology features
- **Chinese New Year campaigns** — Year of the Horse 2026 and Year of the Goat 2027 zodiac content at scale

### 💵 Pricing — pay only for the modules you pick (Start at $0.30 · Full Life Manual from $1.99)

| Module (`modules` value) | What you get | Price per chart |
|---|---|---|
| `basic-chart` (always included) | Four Pillars, ten gods, hidden stems, luck & annual pillars, shen sha, lunar date | **$0.30** |
| `zodiac-profile` | Zodiac animal + element, traits, best matches, clash | $0.30 |
| `day-master-profile` | Day Master personality archetype, strengths, challenges, careers | $0.50 |
| `element-balance-lucky` | Five Elements balance + lucky colors, numbers, directions, gemstones | $0.50 |
| `feng-shui-kua` | Kua number, 4 lucky + 4 unlucky directions | $0.30 |
| `western-crossover` | Western sun sign × Chinese zodiac (e.g. Metal Horse × Taurus) | $0.20 |
| `forecast` | Current/next 10-year luck pillar + 2026 Fire Horse & 2027 Fire Goat themes | $1.00 |
| `compatibility` (needs `partner`) | 0–100 love/friendship match score with reasons | $1.50 |
| ⭐ **Full Life Manual** (`"plan": "full"`, no partner) | **Every module except compatibility** (basic chart + zodiac + Day Master + elements & lucky charms + Feng Shui Kua + Western crossover + forecast) | **$1.99 — best value, save ~36% vs $3.10 à la carte** |
| 💞 **Full Life Manual + Love** (`"plan": "full"` + `partner`) | **Everything above, including love compatibility** | **$2.99 — save ~35% vs $4.60 à la carte** |

- **Default** (no `modules` given): basic chart + zodiac profile = **$0.60** per chart — a cheap first try.
- With `"plan": "full"` you are charged **only one bundle event per chart** — `full-life-manual` ($1.99) without a partner, or `full-life-manual-love` ($2.99) when you add a `partner` — never the individual modules on top.
- 💞 **Compatibility is built for dating apps, couple quizzes and "are we a match?" content** — one call returns both charts' match score and reasons.
- Rows with an input error are **free**. Your **max charge per run** is respected: the Actor stops cleanly when the limit is reached.
- Actor start: Apify platform minimum ($0.00005).

### 🤖 Use with AI agents (MCP) — Claude, Cursor, VS Code, ChatGPT

Life Manual works as a ready-made tool for AI agents through the official **[Apify MCP server](https://docs.apify.com/platform/integrations/mcp)** (`mcp.apify.com`). Your agent gets one tool, **`awake_froghopper--chinese-bazi-four-pillars`**, with the full input schema, so it can compute a correct chart instead of guessing calendar math.

**Claude Desktop / claude.ai:** Settings → Connectors → Add custom connector → Remote MCP server URL:

```
https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars
```

Sign in to Apify in the browser window on first connect (OAuth, no token in the config).

**Cursor, VS Code and other JSON-config clients** (e.g. Cursor `~/.cursor/mcp.json`) — hosted server with OAuth:

```json
{
  "mcpServers": {
    "life-manual": {
      "url": "https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars"
    }
  }
}
```

**With an API token instead of OAuth** (token from Apify Console → *API & Integrations*):

```json
{
  "mcpServers": {
    "life-manual": {
      "url": "https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}
```

**Local stdio** (clients without remote MCP support; the current server needs Node.js 22+):

```json
{
  "mcpServers": {
    "life-manual": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server@latest", "--tools", "awake_froghopper/chinese-bazi-four-pillars"],
      "env": { "APIFY_TOKEN": "<APIFY_TOKEN>" }
    }
  }
}
```

- Want discovery tools too? Use `https://mcp.apify.com?tools=actors,docs,awake_froghopper/chinese-bazi-four-pillars`, or pick tools visually in the [MCP configurator](https://mcp.apify.com/).
- Example prompt: *"Use Life Manual to read my Chinese zodiac and lucky colors: born 1990-05-15 12:00 in New York, male."* — the agent fills `birthDate`, `birthTime`, `gender`, `timezone: America/New_York`.
- Ask the agent for `"plan": "full"` for the complete reading, or add a `partner` for love compatibility. Pricing is the same as normal runs (default call = $0.60).
- The tool returns run info plus a `datasetId`; the agent reads the rows with `get-dataset-items` (added automatically).

### Why it is accurate

- Year pillar / zodiac switches at the **exact Lichun instant** (~Feb 4) — not Jan 1 or Lunar New Year; month pillar at exact **solar terms**
- Any **birth city timezone** worldwide, historical **daylight saving time**, optional **true solar time** from longitude
- Gregorian **or Chinese lunar date** input, leap months, **Zi-hour** options (子初换日 / 早晚子时)
- Cross-checked against an independent BaZi engine on 400 random charts
- Batch up to **500 people** per run; per-row errors
- 🔒 **No LLM, no external API calls, birth data is never logged or stored** outside your own run's dataset; set `includeInputEcho=false` to drop it there too

> **Disclaimer.** For entertainment, cultural education and self-reflection only. BaZi and Chinese astrology are traditional metaphysical systems, not science. Readings are fixed rule-based texts, not predictions, and are not medical, financial, legal, psychological or relationship advice.

### Method notes (transparent rules)

- **Favourable elements**: weighted Five Elements count (stems 1.0, hidden stems 1.0/0.5/0.3, month branch ×2). Support ratio ≥ 0.55 = strong Day Master → output/wealth/officer elements favourable; ≤ 0.42 = weak → resource/companion; otherwise balanced → the weakest elements. Lucky colors (五行色), Hetu numbers (河图数) and directions follow the favourable elements.
- **Kua**: Eight Mansions formula from the BaZi year and gender.
- **Forecast**: ten-god theme of the year/luck stem, element tone vs. favourable elements, and Tai Sui relation (same / clash / harm / harmony) with your zodiac.
- **Compatibility**: base 60; zodiac relation, spouse-palace (day branch) relation, Day Master stem relation (五合 / generating / controlling) and mutual favourable elements; full breakdown returned.

### How to run

1. Open [Life Manual on Apify Store](https://apify.com/awake_froghopper/chinese-bazi-four-pillars)
2. Paste one of the JSON examples below into Input
3. Click **Start** — results land in the default dataset (one row per person)

Or call the API / Actor client with the same JSON body.

### Copy-paste input examples

#### 0) ⭐ Full Life Manual ($1.99, best value)

```json
{
  "plan": "full",
  "birthDate": "1990-05-15", "birthTime": "12:00", "gender": "male", "timezone": "America/New_York"
}
```

#### 0a) 💞 Full Life Manual + Love compatibility ($2.99)

```json
{
  "plan": "full",
  "birthDate": "1990-05-15", "birthTime": "12:00", "gender": "male", "timezone": "America/New_York",
  "partner": { "birthDate": "1991-07-10", "birthTime": "10:00", "gender": "female", "timezone": "Europe/London" }
}
```

#### 0b) Pick modules (custom: $0.30 + $0.50 + $1.00 = $1.80)

```json
{ "birthDate": "1995-02-10", "birthTime": "08:15", "gender": "female", "timezone": "Europe/London",
  "modules": ["day-master-profile", "forecast"] }
```

#### 1) Single chart (Gregorian, China)

```json
{
  "birthDate": "1990-05-15",
  "birthTime": "12:00",
  "gender": "male",
  "timezone": "Asia/Shanghai"
}
```

#### 2) True solar time (New York) + specific annual years

```json
{
  "birthDatetime": "1988-07-01T09:05:00-04:00",
  "gender": "female",
  "longitude": -74.0,
  "solarTime": "trueSolar",
  "liuNianYears": [2026, 2027, 2028]
}
```

#### 3) Batch + Chinese lunar calendar date

```json
{
  "people": [
    {
      "id": "gregorian-a",
      "birthDate": "1990-05-15",
      "birthTime": "12:00",
      "gender": "male",
      "timezone": "+08:00"
    },
    {
      "id": "lunar-b",
      "birthDate": "1990-04-21",
      "birthTime": "08:30",
      "gender": "female",
      "calendar": "lunar",
      "lunarLeapMonth": false,
      "timezone": "Asia/Shanghai"
    }
  ],
  "includeInputEcho": false
}
```

Set `includeInputEcho` to `false` to keep raw birth date/time out of result rows.

### Main input fields

| Field | Default | Notes |
|---|---|---|
| `birthDate` | — | `YYYY-MM-DD` (Gregorian, or lunar if `calendar` = `lunar`) |
| `birthTime` | — | `HH:MM` local clock. Empty = unknown hour pillar |
| `plan` | `custom` | `custom` = charge per selected module; `full` = Full Life Manual bundle ($1.99 without partner; $2.99 with `partner`, adds compatibility) |
| `modules` | `["zodiac-profile"]` | Modules on top of the always-included basic chart (see Pricing) |
| `partner` | — | Second person `{birthDate, birthTime, gender, timezone}` — needed for `compatibility` |
| `gender` | `male` | `male` / `female` — luck-pillar direction |
| `timezone` | `Asia/Shanghai` | IANA name or offset (`+08:00`) |
| `birthDatetime` | — | ISO alternative, e.g. `1990-05-15T12:00:00+08:00` |
| `calendar` / `lunarLeapMonth` | `gregorian` / `false` | Chinese lunar calendar input |
| `solarTime` | `clock` | `clock`, `meanSolar`, `trueSolar` (needs `longitude`) |
| `longitude` | — | Decimal degrees, east positive |
| `ziHourRule` | `nextDayAt23` | or `sameDayLateZi` |
| `applyDst` | `true` | `false` if the recorded time is already standard time |
| `qiYunMethod` | `days` | `days` (3 days = 1 year) or `minutes` |
| `daYunCount` | `8` | 1–12 luck pillars |
| `liuNianFrom` / `liuNianTo` / `liuNianYears` | current year +4 | Annual pillars |
| `people` | — | Batch array (same fields + optional `id`) |
| `includeInputEcho` | `true` | `false` omits raw birth data from dataset rows |

### Output (one row per person, abbreviated)

```json
{
  "id": "a",
  "fourPillars": "庚午 辛巳 庚辰 壬午",
  "dayMaster": { "stem": "庚", "pinyin": "Geng", "element": "Metal", "yinYang": "yang" },
  "pillars": {
    "month": {
      "ganzhi": "辛巳",
      "stemTenGod": "劫财",
      "stemTenGodEn": "Rob Wealth",
      "hiddenStems": [
        { "stem": "丙", "tenGod": "七杀" },
        { "stem": "庚", "tenGod": "比肩" },
        { "stem": "戊", "tenGod": "偏印" }
      ],
      "nayin": "白蜡金",
      "lifeStage": "长生"
    }
  },
  "fiveElements": {
    "visibleCounts": { "Wood": 0, "Fire": 3, "Earth": 1, "Metal": 3, "Water": 1 },
    "missingVisible": ["Wood"]
  },
  "daYun": {
    "direction": "forward",
    "startDateUtc8": "1997-08-15",
    "pillars": [{ "index": 1, "ganzhi": "壬午", "startYear": 1997, "endYear": 2006 }]
  },
  "liuNian": [{ "year": 2026, "ganzhi": "丙午", "stemTenGod": "七杀" }],
  "shenSha": [{ "name": "天乙贵人", "nameEn": "Heavenly Noble (Tian Yi)" }],
  "voidBranches": ["申", "酉"],
  "conventions": { "ziHourRule": "Day changes at 23:00 (zi chu)..." },
  "warnings": [],
  "disclaimer": "For cultural, educational and entertainment purposes only. ..."
}
```

### Method notes

- **Year / month pillars** from the birth instant vs solar-term instants (China Standard Time, UTC+8). Births within 2 hours of a jie get a warning.
- **Day / hour pillars** use local time: clock (DST removed), mean solar, or true solar from `longitude`.
- **Luck pillars**: yang-year male / yin-year female go forward; others backward. Ages are nominal (虚岁).
- **Shen sha**: 22 common stars; only those present are listed, with lookup basis in `conventions`.
- Supported birth years: **1800–2100**.

### Accuracy

Anchor tests cover published charts (e.g. 1893-12-26 辰时; 1866-11-12 寅时), Lichun and zi-hour edges, China’s 1986–1991 DST, true solar time and lunar leap months. 400 random charts (1901–2099) were cross-checked against an independent MIT-licensed engine: identical pillars, luck direction, first luck pillar and shen sha.

### Privacy

No LLM. No external calls. Birth data is not logged and nothing is kept after the run beyond your own Apify dataset (your retention settings). Use `includeInputEcho: false` to keep raw birth fields out of result rows.

### Credits

Calendar math: [lunar-python](https://github.com/6tail/lunar-python) (MIT). Shen sha tables adapted from [bazi-skill](https://github.com/jinchenma94/bazi-skill) (MIT). See `THIRD_PARTY_NOTICES.md`.

***

### 中文简介（人生说明书 · 八字排盘）

确定性的四柱八字排盘 API：输入出生日期、时间、性别、时区，输出四柱、十神（含藏干）、五行、纳音、十二长生、大运、流年、神煞、空亡、胎元。年柱以立春精确时刻分界，月柱以十二节分界；支持真太阳时、早晚子时、任意时区与历史夏令时、农历（含闰月），可批量排盘。**不用大模型，不保存出生信息。按模块计费：基础盘 $0.30 起，全套 Full Life Manual $1.99（不含合盘）/ 含合盘 $2.99。仅供传统文化学习与娱乐参考。**

# Actor input Schema

## `plan` (type: `string`):

custom = pay only for the modules you tick below (basic chart $0.30 always included). full = Full Life Manual bundle, only the bundle is charged: $1.99 per chart without a partner (every module except compatibility, save ~36% vs $3.10) or $2.99 per chart when you add a partner (every module incl. 💞 love compatibility, save ~35% vs $4.60).

## `modules` (type: `array`):

Extra modules per chart, each charged separately on top of the basic chart ($0.30): zodiac-profile $0.30, day-master-profile $0.50, element-balance-lucky $0.50, feng-shui-kua $0.30, western-crossover $0.20, forecast $1.00, compatibility $1.50 (needs partner; skipped and not charged without one). Ignored when Plan = full.

## `fullLifeManual` (type: `boolean`):

Same as Plan = full. $1.99 per chart without a partner, $2.99 per chart with a partner (adds love compatibility).

## `birthDate` (type: `string`):

YYYY-MM-DD (Gregorian, or lunar if Calendar = lunar). Leave empty if you use the People array. If no birth data is given at all, the run returns one free demo chart for a sample person (nothing charged).

## `birthTime` (type: `string`):

HH:MM or HH:MM:SS, local clock time at the birthplace. Leave empty if unknown: the hour pillar is then omitted.

## `gender` (type: `string`):

Needed for the luck-pillar (da yun) direction and the Yuan Chen star.

## `timezone` (type: `string`):

IANA timezone of the birthplace, e.g. America/New_York, Europe/London, Europe/Paris, Asia/Singapore, Australia/Sydney, Asia/Shanghai, or a fixed offset like +08:00 / -05:00. Historical daylight saving time is handled automatically. Tip: use the city's zone, not where you live now.

## `partner` (type: `object`):

Second person for the 💞 compatibility module ($1.50 à la carte; with Plan = full, adding a partner switches the bundle to Full Life Manual + Love at $2.99 instead of $1.99). Fields: birthDate, birthTime, gender, timezone (optional: longitude, solarTime, calendar). Partner birth data is never echoed in the output.

## `birthDatetime` (type: `string`):

Alternative to Birth date + time, e.g. 1990-05-15T12:00:00+08:00. An offset inside the string overrides Timezone.

## `calendar` (type: `string`):

gregorian (default) or lunar (Chinese lunar calendar date).

## `lunarLeapMonth` (type: `boolean`):

Only for calendar = lunar: the month is the leap (intercalary) month.

## `solarTime` (type: `string`):

clock = local standard time (default). meanSolar = longitude-corrected mean solar time. trueSolar = apparent solar time (mean solar + equation of time). meanSolar/trueSolar need Longitude.

## `longitude` (type: `string`):

Decimal degrees, east positive (Shanghai 121.47, Shantou 116.68, New York -74.0). Required for solar time correction.

## `ziHourRule` (type: `string`):

nextDayAt23 = day changes at 23:00 (default). sameDayLateZi = 23:00-24:00 keeps the same day pillar (早晚子时 / late zi).

## `applyDst` (type: `boolean`):

If true (default), DST from the tz database is removed from the clock time. Set false if the recorded time is already standard time.

## `qiYunMethod` (type: `string`):

days = classic 3 days = 1 year (default). minutes = 4320 minutes = 1 year (finer).

## `daYunCount` (type: `integer`):

How many 10-year luck pillars to return (1-12).

## `liuNianFrom` (type: `integer`):

First year for liu nian (annual pillars). Default: current year.

## `liuNianTo` (type: `integer`):

Last year for liu nian. Default: current year + 4 (or From + 9 if From is set). Max 120 years.

## `liuNianYears` (type: `array`):

Optional explicit list of years, overrides From/To.

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

Batch mode, up to 500 charts. Each object accepts the same fields as above (birthDate, birthTime, gender, timezone, longitude, ...), plus an optional id to match results. Top-level options act as defaults.

## `includeInputEcho` (type: `boolean`):

Include the birth input in each result row. Set false to keep birth data out of the dataset (results then carry only id and the computed chart).

## Actor input object example

```json
{
  "plan": "custom",
  "modules": [
    "zodiac-profile"
  ],
  "fullLifeManual": false,
  "birthDate": "1990-05-15",
  "birthTime": "12:00",
  "gender": "male",
  "timezone": "Asia/Shanghai",
  "partner": {
    "birthDate": "1992-08-20",
    "birthTime": "08:30",
    "gender": "female",
    "timezone": "Europe/London"
  },
  "calendar": "gregorian",
  "lunarLeapMonth": false,
  "solarTime": "clock",
  "ziHourRule": "nextDayAt23",
  "applyDst": true,
  "qiYunMethod": "days",
  "daYunCount": 8,
  "people": [
    {
      "id": "a",
      "birthDate": "1990-05-15",
      "birthTime": "12:00",
      "gender": "male",
      "timezone": "+08:00"
    },
    {
      "id": "b",
      "birthDatetime": "1988-07-01T09:05:00-04:00",
      "gender": "female",
      "longitude": -74,
      "solarTime": "trueSolar"
    }
  ],
  "includeInputEcho": true
}
```

# Actor output Schema

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

All Four Pillars charts: pillars, ten gods, hidden stems, five elements, da yun luck pillars, liu nian annual pillars, shen sha, conventions and disclaimer. Plus zodiac profile, Day Master personality, lucky charms, Kua directions, forecast and compatibility.

## `overview` (type: `string`):

Four pillars, day master, luck direction and start age per person — quick Chinese astrology overview.

## `profile` (type: `string`):

Readable profile view: zodiac animal & element, Day Master personality, Five Elements, lucky colors/numbers, 2026/2027 forecast, compatibility.

# 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 = {
    "modules": [
        "zodiac-profile"
    ],
    "birthDate": "1990-05-15",
    "birthTime": "12:00"
};

// Run the Actor and wait for it to finish
const run = await client.actor("awake_froghopper/chinese-bazi-four-pillars").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 = {
    "modules": ["zodiac-profile"],
    "birthDate": "1990-05-15",
    "birthTime": "12:00",
}

# Run the Actor and wait for it to finish
run = client.actor("awake_froghopper/chinese-bazi-four-pillars").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 '{
  "modules": [
    "zodiac-profile"
  ],
  "birthDate": "1990-05-15",
  "birthTime": "12:00"
}' |
apify call awake_froghopper/chinese-bazi-four-pillars --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,awake_froghopper/chinese-bazi-four-pillars"
        }
    }
}
```

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/yEGpPrA1bPu3LrfAv/builds/ACjO5cbTkw6CVDbMI/openapi.json