# BaZi Chart API (八字排盤) (`kelvin.kwong/bazi-chart-api`) Actor Compute Chinese Four Pillars (BaZi / 八字) charts from birth data: pillars, hidden stems, Na Yin, Ten Gods, five-element distribution, luck cycles (大運) and current-year pillar. Pay per chart. - **URL**: https://apify.com/kelvin.kwong/bazi-chart-api.md - **Developed by:** [Kelvin Kwong](https://apify.com/kelvin.kwong) (community) - **Categories:** AI, Agents, Other - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event + usage This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## BaZi Chart API (八字排盤) — Chinese Four Pillars as a JSON API Turn any birth date and time into a complete, structured **BaZi (八字) chart**: the four pillars with heavenly stems and earthly branches, hidden stems, Na Yin, Ten Gods (十神), five-element distribution, day-master strength, 10-year luck cycles (大運), and the current year's pillar (流年) — all as clean JSON, in Traditional Chinese, Simplified Chinese, or English. Built on battle-tested calendar math (the 6tail `lunar-typescript` library), with correct lunar-calendar input, leap-month handling, and timezone conversion. Pay only per chart generated. **Keywords:** 八字 · 四柱 · BaZi · Four Pillars of Destiny · Chinese astrology API · 排盤 · fortune telling API · Chinese metaphysics · 大運 · 十神 · lunar calendar conversion ### Quick example Input: ```json { "birthDatetime": "1995-08-17T14:30:00", "calendarType": "solar", "gender": "male", "timezone": "Asia/Hong_Kong", "ziHourMode": "late", "language": "zh-Hant", "includeLuckCycles": true } ```` Output (abridged — every stem/branch is returned with hanzi, pinyin, element, and yin-yang): ```json { "pillars": { "year": { "ganZhi": { "hanzi": "乙亥", "pinyin": "yǐ hài" }, "heavenlyStem": { "hanzi": "乙", "pinyin": "yǐ", "element": { "key": "wood", "label": "木" }, "yinYang": "yin", "tenGod": { "hant": "正財", "hans": "正财", "pinyin": "zhèng cái", "en": "Direct Wealth", "label": "正財" } }, "earthlyBranch": { "hanzi": "亥", "pinyin": "hài", "element": { "key": "water", "label": "水" }, "yinYang": "yin" }, "hiddenStems": [ { "hanzi": "壬", "tenGod": { "label": "食神" } }, { "hanzi": "甲", "tenGod": { "label": "偏財" } } ], "naYin": { "hant": "山頭火", "hans": "山头火", "en": "Fire on the Mountain Top", "label": "山頭火" } }, "month": { "ganZhi": { "hanzi": "甲申" }, "...": "..." }, "day": { "ganZhi": { "hanzi": "庚辰" }, "...": "..." }, "hour": { "ganZhi": { "hanzi": "癸未" }, "...": "..." } }, "dayMaster": { "stem": { "hanzi": "庚", "pinyin": "gēng", "element": { "key": "metal", "label": "金" }, "yinYang": "yang" }, "strength": { "value": "balanced", "label": "中和", "supportRatio": 0.391, "method": "weighted five-element count ..." } }, "fiveElements": { "counts": { "wood": 3.5, "fire": 0.5, "earth": 2.5, "metal": 2, "water": 3 }, "percentages": { "wood": 30.4, "fire": 4.3, "earth": 21.7, "metal": 17.4, "water": 26.1 } }, "tenGods": { "year": { "label": "正財" }, "month": { "label": "偏財" }, "day": { "label": "日主" }, "hour": { "label": "傷官" } }, "luckCycles": { "direction": { "value": "backward", "label": "逆行" }, "startAge": 4, "startDate": "1998-09-17", "cycles": [ { "index": 1, "ganZhi": { "hanzi": "癸未" }, "startAge": 4, "endAge": 13, "startYear": 1998, "endYear": 2007 }, { "index": 2, "ganZhi": { "hanzi": "壬午" }, "startAge": 14, "endAge": 23, "startYear": 2008, "endYear": 2017 } ] }, "currentYear": { "year": 2026, "ganZhi": { "hanzi": "丙午" }, "heavenlyStem": { "tenGod": { "label": "七殺" } } }, "meta": { "localBirthDatetime": "1995-08-17T14:30:00", "solarDate": "1995-08-17 14:30:00", "lunarDate": "一九九五年七月廿二", "ganZhiDateTime": "乙亥 甲申 庚辰 癸未", "library": "lunar-typescript@1.8.6" } } ``` ### Use cases - **Horoscope & astrology apps** — full chart data ready to render or feed to an LLM for reading generation. - **Dating & compatibility features** — compare two charts' day masters, elements, and ten-god relations (八字合婚). - **Newsletters & content generation** — batch mode produces hundreds of charts in one run for personalized content. - **AI agents via MCP** — Apify Actors are callable as MCP tools, so agents can compute deterministic charts instead of hallucinating calendar math. ### Input | Field | Type | Default | Notes | |---|---|---|---| | `birthDatetime` | string (ISO 8601) | — required | Without a UTC offset it is local wall-clock time in `timezone`; with an offset/`Z` it is converted into `timezone` first. | | `calendarType` | `"solar"` | `"lunar"` | `solar` | For `lunar`, the Y-M-D of `birthDatetime` are lunar-calendar numbers (no UTC offset allowed). | | `isLeapMonth` | boolean | `false` | Lunar only: birth month is the leap (閏) month. | | `gender` | `"male"` | `"female"` | — required | Determines luck-cycle direction (大運順逆). | | `timezone` | IANA string | `Asia/Hong_Kong` | Applied before any pillar calculation. | | `ziHourMode` | `"late"` | `"early"` | `late` | See conventions below. | | `language` | `"zh-Hant"` | `"zh-Hans"` | `"en"` | `zh-Hant` | Label language; hanzi + pinyin always included. | | `includeLuckCycles` | boolean | `true` | Include 大運. | | `charts` | array | — | **Batch mode**: array of records of the same shape. Top-level single-chart fields are then ignored. One invalid record never fails the run — it yields an `{ "error": ... }` item and processing continues. | ### REST API (Standby mode) This Actor supports **Actor Standby**, so you can call it like a regular low-latency REST API without waiting for container start: ```bash curl -X POST "https://--bazi-chart-api.apify.actor/" \ -H "Authorization: Bearer $APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"birthDatetime": "1995-08-17T14:30:00", "gender": "male", "timezone": "Asia/Hong_Kong"}' ``` The response is the chart JSON (or `{ "results": [...] }` for batch bodies). Invalid input returns HTTP 400 with `{ "error": "..." }`. ### Pricing — pay per chart You are charged one **`chart-generated`** event per successfully computed chart — nothing else. A batch of 10 valid records = 10 events; invalid or rejected records are **never charged**. The same applies to Standby/API requests. ### Accuracy, conventions & limitations - **Calendar math** comes from [`lunar-typescript`](https://github.com/6tail/lunar-typescript) (the 6tail library), the de-facto standard open-source implementation; solar-term boundaries, lunar conversion, and leap months are handled by the library, not hand-rolled. - **子時 boundary (`ziHourMode`)** — `late` (default, 晚子時 convention): a birth at 23:00–23:59 keeps the **current** day's day pillar; `early`: the day pillar advances to the next day at 23:00. Births at 00:00–00:59 always use the current calendar day. The hour pillar is 子時 either way. - **Luck-cycle start (起運)** uses the classic method: 3 days between birth and the governing solar term = 1 year, remainder rounded to months and days. - **Year pillar** for the current year (流年) switches at 立春, per standard BaZi convention. - **Day-master strength** is a simple, documented weighted five-element count (see `method` in the output) — a screening heuristic, not a full 旺衰/格局 analysis. Use the raw counts and ten gods for your own logic. - **True solar time is not applied**: the chart uses clock time in the given IANA timezone. If you need 真太陽時, adjust `birthDatetime` by the birthplace's longitude correction before calling. - Timezone conversion uses the IANA tz database (via `luxon`), including historical offsets and DST. *** Built by the team behind [xuanzhang.app](https://www.xuanzhang.app) — AI-powered Chinese metaphysics readings. # Actor input Schema ## `birthDatetime` (type: `string`): ISO 8601 date-time of birth, e.g. `1995-08-17T14:30:00`. Without a UTC offset it is interpreted as local wall-clock time in `timezone`; with an offset (or `Z`) it is converted into `timezone` first. Required unless `charts` (batch mode) is used. ## `calendarType` (type: `string`): Whether `birthDatetime` is a Gregorian (solar) or Chinese lunar date. ## `isLeapMonth` (type: `boolean`): Only relevant when `calendarType` is `lunar`: set to true if the birth month is the leap (閏) month. ## `gender` (type: `string`): Biological gender at birth — determines the direction of the luck cycles (大運順逆). Required unless `charts` (batch mode) is used. ## `timezone` (type: `string`): IANA timezone of the birth place, e.g. `Asia/Hong_Kong`, `America/New_York`. The birth time is resolved to local wall-clock time in this zone before any pillar calculation. ## `ziHourMode` (type: `string`): How a 23:00–23:59 birth is assigned to a day pillar. `late` (晚子時): the day pillar stays on the current calendar day. `early`: the day pillar advances to the next day at 23:00. Births at 00:00–00:59 always use the current calendar day. ## `language` (type: `string`): Language of human-readable labels in the output. Stems and branches always include hanzi (Traditional & Simplified) and pinyin regardless of this setting. ## `includeLuckCycles` (type: `boolean`): Include the 10-year luck cycles (大運) in the output. ## `charts` (type: `array`): Optional array of birth records with the same shape as the top-level fields (`birthDatetime`, `gender`, `calendarType`, `isLeapMonth`, `timezone`, `ziHourMode`, `language`, `includeLuckCycles`). When present, the top-level single-chart fields are ignored and each record is processed independently — one invalid record does not fail the run. Each successfully computed chart is charged as one `chart-generated` event. ## Actor input object example ```json { "birthDatetime": "1995-08-17T14:30:00", "calendarType": "solar", "isLeapMonth": false, "gender": "male", "timezone": "Asia/Hong_Kong", "ziHourMode": "late", "language": "zh-Hant", "includeLuckCycles": true } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "birthDatetime": "1995-08-17T14:30:00", "gender": "male" }; // Run the Actor and wait for it to finish const run = await client.actor("kelvin.kwong/bazi-chart-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "birthDatetime": "1995-08-17T14:30:00", "gender": "male", } # Run the Actor and wait for it to finish run = client.actor("kelvin.kwong/bazi-chart-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "birthDatetime": "1995-08-17T14:30:00", "gender": "male" }' | apify call kelvin.kwong/bazi-chart-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kelvin.kwong/bazi-chart-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "BaZi Chart API (八字排盤)", "description": "Compute Chinese Four Pillars (BaZi / 八字) charts from birth data: pillars, hidden stems, Na Yin, Ten Gods, five-element distribution, luck cycles (大運) and current-year pillar. Pay per chart.", "version": "1.0", "x-build-id": "eu0gdIPHOzezlZBpT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kelvin.kwong~bazi-chart-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kelvin.kwong-bazi-chart-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/kelvin.kwong~bazi-chart-api/runs": { "post": { "operationId": "runs-sync-kelvin.kwong-bazi-chart-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/kelvin.kwong~bazi-chart-api/run-sync": { "post": { "operationId": "run-sync-kelvin.kwong-bazi-chart-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "birthDatetime": { "title": "Birth date & time", "type": "string", "description": "ISO 8601 date-time of birth, e.g. `1995-08-17T14:30:00`. Without a UTC offset it is interpreted as local wall-clock time in `timezone`; with an offset (or `Z`) it is converted into `timezone` first. Required unless `charts` (batch mode) is used." }, "calendarType": { "title": "Calendar type", "enum": [ "solar", "lunar" ], "type": "string", "description": "Whether `birthDatetime` is a Gregorian (solar) or Chinese lunar date.", "default": "solar" }, "isLeapMonth": { "title": "Lunar leap month (閏月)", "type": "boolean", "description": "Only relevant when `calendarType` is `lunar`: set to true if the birth month is the leap (閏) month.", "default": false }, "gender": { "title": "Gender", "enum": [ "male", "female" ], "type": "string", "description": "Biological gender at birth — determines the direction of the luck cycles (大運順逆). Required unless `charts` (batch mode) is used." }, "timezone": { "title": "Timezone", "type": "string", "description": "IANA timezone of the birth place, e.g. `Asia/Hong_Kong`, `America/New_York`. The birth time is resolved to local wall-clock time in this zone before any pillar calculation.", "default": "Asia/Hong_Kong" }, "ziHourMode": { "title": "子時 (Zi hour) mode", "enum": [ "late", "early" ], "type": "string", "description": "How a 23:00–23:59 birth is assigned to a day pillar. `late` (晚子時): the day pillar stays on the current calendar day. `early`: the day pillar advances to the next day at 23:00. Births at 00:00–00:59 always use the current calendar day.", "default": "late" }, "language": { "title": "Label language", "enum": [ "zh-Hant", "zh-Hans", "en" ], "type": "string", "description": "Language of human-readable labels in the output. Stems and branches always include hanzi (Traditional & Simplified) and pinyin regardless of this setting.", "default": "zh-Hant" }, "includeLuckCycles": { "title": "Include luck cycles (大運)", "type": "boolean", "description": "Include the 10-year luck cycles (大運) in the output.", "default": true }, "charts": { "title": "Batch mode: multiple charts", "type": "array", "description": "Optional array of birth records with the same shape as the top-level fields (`birthDatetime`, `gender`, `calendarType`, `isLeapMonth`, `timezone`, `ziHourMode`, `language`, `includeLuckCycles`). When present, the top-level single-chart fields are ignored and each record is processed independently — one invalid record does not fail the run. Each successfully computed chart is charged as one `chart-generated` event." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```