# Chinese Astrology API > Calculate BaZi Four Pillars charts, Chinese zodiac signs, and the Chinese lunisolar calendar from any birth moment: year, month, day and hour pillars with hidden stems, Na Yin and Ten God relations, luck pillars, day master strength, and animal compatibility. The school splits that make two calculators disagree are typed parameters rather than hidden defaults, and every chart echoes the conventions it was computed under. Solar terms come back as astronomical instants, lunar dates convert in both directions with leap months placed correctly, and the Tong Shu almanac covers day officers, lunar mansions and date selection. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs. A BaZi chart that tells you which school it came from. - Product page: https://roxyapi.com/products/chinese-astrology-api - OpenAPI spec: https://roxyapi.com/api/v2/chinese-astrology/openapi.json - Remote MCP server: https://roxyapi.com/mcp/chinese-astrology - Authentication: `X-API-Key` header on every request - Pricing: https://roxyapi.com/pricing (all domains included in every plan) ## Stats - uptime: 99.95%+ ## Features - Four Pillars (BaZi) chart from one birth moment: the year, month, day and hour pillars, each with its Heavenly Stem, Earthly Branch, hidden stems, Na Yin sound element and Ten God relation, plus the day master and a five element balance - The three school splits that make two BaZi calculators disagree are typed request parameters, never hidden defaults: the year boundary (Li Chun or Lunar New Year), the day boundary (split zi, midnight or early zi), and the hour clock (civil, local mean or apparent solar). Every response echoes the conventions the chart was computed under, so a saved chart stays reproducible - Luck pillars (Da Yun) with the forward or reverse direction resolved from year polarity and gender, the start age, and optional annual pillars (Liu Nian) for a target year with the Ben Ming Nian year flagged - The 24 solar terms as astronomical instants rather than table lookups, computed from apparent solar longitude at 15 degree steps, with the twelve minor terms that move the month pillar marked as such - Gregorian to lunisolar conversion in both directions at the 120 degrees east reference meridian, with leap months placed by the no major term rule so a lunar date is the same worldwide - Tong Shu almanac days: day pillar, the twelve day officers, the 28 lunar mansions, the clashing animal, and the activities a day favours or opposes, plus a bounded date search for picking a wedding, an opening or a move - Chinese zodiac past the animal alone: element year variants, the four trines, the six clashes, the six harms and the secret friends, plus a deterministic daily reading built from the day pillar ## Includes The Chinese Astrology API bundles these sub-APIs under one key: - BaZi API - Four Pillars API - Chinese Zodiac API - Chinese Calendar API - Solar Terms API - Tong Shu Almanac API ## Use Cases - Astrology and divination apps: full Four Pillars charts, luck pillars, and zodiac compatibility from a birth date and time - Chinese calendar and holiday features: lunar date conversion, leap months, solar terms and Lunar New Year for any year - Date selection tools: almanac day quality, day officers and lunar mansions for weddings, openings, moves and travel - AI chatbots and coaching assistants: BaZi and zodiac data over Remote MCP tool calls for readings and follow up questions - Practitioner software: hidden stems, Na Yin and Ten Gods on every pillar, with the school conventions recorded on the chart - Content and editorial platforms: zodiac animal, solar term and element reference lookups for explainer pages and yearly guides ## FAQ ### How do I add a BaZi Four Pillars chart to my app? Send a birth date, time and timezone to the Chinese Astrology API and the full Four Pillars chart comes back in one response: year, month, day and hour pillars, the hidden stems in each branch, the Na Yin sound element, the Ten God relation to the day master, and the five element balance. No lookup tables to ship and no calendar library to maintain. Typed SDKs and a Remote MCP server are available on the same key, along with every other RoxyAPI domain. ### Why do two BaZi calculators give different pillars for the same birth? Almost always because they follow different schools and say nothing about it. Three choices move the answer: whether the year turns at Li Chun or at Lunar New Year, whether the day turns at midnight or at 23:00, and whether the hour branch is read from civil time, local mean time or apparent solar time. Each of those is a typed parameter on this API with a named default, and the resolved set comes back on the response, so you can reproduce a chart later or match another calculator on purpose rather than by accident. ### How accurate are the solar terms and lunar dates? Solar terms are computed as instants, not read from a table of dates: each of the 24 is the moment the sun reaches its exact apparent longitude, at 15 degree steps, so a birth an hour either side of Li Chun lands in the right year. Lunar dates follow the published national standard frame, evaluated at the 120 degrees east reference meridian with the winter solstice fixed in month 11 and the leap month placed by the no major term rule. Values are verified against an independent national observatory calendar. ### Can I pick an auspicious date with the API? Yes. The almanac endpoints return a day pillar, its day officer from the twelve jian chu sequence, the lunar mansion, the animal the day clashes with, and the activities the day favours or opposes. A bounded search takes an activity and a date range and returns the days that suit it, optionally skipping the days that clash with a given zodiac animal. That is what powers wedding, opening, moving and travel date pickers without a human almanac reader in the loop. ### Which Chinese zodiac animal does a birthday near the new year return? Whichever one you ask for, stated plainly. The folk answer changes at Lunar New Year and the classical BaZi answer changes at Li Chun in early February, so a birth in late January or early February can be either animal depending on the rule. The zodiac endpoints default to the popular Lunar New Year rule because that is what a reader expects, the BaZi endpoints default to Li Chun because that is what the classical texts use, and both echo the rule that was applied. ### Do the responses come in Chinese? Yes, in both scripts. Simplified and Traditional Chinese are shipped alongside German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The hanzi and the tone marked pinyin for every stem, branch, animal and solar term are data fields present in every language, so a Simplified response still carries the pinyin and an English response still carries the characters. Machine identifiers stay English so they remain safe to compare in code. ## Endpoints - `POST /api/v2/chinese-astrology/bazi/chart` Generate BaZi chart - Four Pillars of Destiny calculator API - `POST /api/v2/chinese-astrology/bazi/luck-pillars` Calculate luck pillars - BaZi Da Yun ten-year cycle API - `POST /api/v2/chinese-astrology/bazi/day-master` Calculate Day Master strength - BaZi favorable element API - `POST /api/v2/chinese-astrology/bazi/compatibility` Calculate BaZi compatibility - Four Pillars matchmaking API - `POST /api/v2/chinese-astrology/bazi/annual-forecast` Calculate BaZi annual forecast - Liu Nian yearly pillar API - `GET /api/v2/chinese-astrology/zodiac/animals` List the 12 Chinese zodiac animals - Sheng Xiao sign catalogue - `GET /api/v2/chinese-astrology/zodiac/animals/{id}` Get one Chinese zodiac animal - Full sign profile with compatibility partners - `POST /api/v2/chinese-astrology/zodiac/sign` Find the Chinese zodiac animal for a birth date - Sheng Xiao calculator - `GET /api/v2/chinese-astrology/zodiac/compatibility/{sign1}/{sign2}` Chinese zodiac compatibility - Trine, six harmony, clash and harm analysis - `GET /api/v2/chinese-astrology/zodiac/{id}/daily` Daily Chinese zodiac reading - Day pillar forecast by animal sign - `GET /api/v2/chinese-astrology/calendar/solar-terms/{year}` List the 24 solar terms - Jie Qi calendar API with exact instants - `POST /api/v2/chinese-astrology/calendar/lunar-date` Convert lunar and Gregorian dates - Chinese lunisolar calendar API - `GET /api/v2/chinese-astrology/calendar/day/{date}` Get the almanac for a day - Tong Shu API with day officers and mansions - `GET /api/v2/chinese-astrology/calendar/monthly` Get a month of almanac days - Chinese calendar month view API - `POST /api/v2/chinese-astrology/calendar/auspicious-days` Find auspicious days - Chinese date selection API for weddings and openings - `GET /api/v2/chinese-astrology/elements` List the five elements - Wu Xing API with generating and controlling cycles ## Example Response ``` POST /api/v2/chinese-astrology/bazi/chart ``` ```json { "birthData": { "date": "1990-06-15", "time": "14:30:00", "timezone": 9, "latitude": 0 }, "conventions": { "dayBoundary": "split-zi", "yearBoundary": "li-chun", "hourClock": "clock" }, "pillars": [ { "position": "year", "id": "geng-wu", "number": 7, "stem": { "id": "geng", "chinese": "庚", "pinyin": "gēng", "element": "Metal", "polarity": "yang" }, "branch": { "id": "wu", "chinese": "午", "pinyin": "wǔ", "animal": "horse", "element": "Fire", "polarity": "yang" }, "tenGod": { "id": "rob-wealth", "name": "Rob Wealth", "chinese": "劫财", "pinyin": "jié cái", "category": "peer", "keynote": "Drive, nerve, and competition for the same ground" }, "hiddenStems": [ { "stem": { "id": "ding", "chinese": "丁", "pinyin": "dīng", "element": "Fire", "polarity": "yin" }, "role": "principal", "tenGod": { "id": "seven-killings", "name": "Seven Killings", "chinese": "七杀", "pinyin": "qī shā", "category": "influence", "keynote": "Pressure, command, and anything won under real risk" } }, { "stem": { "id": "ji", "chinese": "己", "pinyin": "jǐ", "element": "Earth", "polarity": "yin" }, "role": "middle", "tenGod": { "id": "indirect-resource", "name": "Indirect Resource", "chinese": "偏印", "pinyin": "piān yìn", "category": "resource", "keynote": "Unusual learning and skill in narrow subjects" } } ], "naYin": "Earth by the Roadside", "naYinChinese": "路旁土", "naYinElement": "Earth" }, { "position": "month", "id": "ren-wu", "number": 19, "stem": { "id": "ren", "chinese": "壬", "pinyin": "rén", "element": "Water", "polarity": "yang" }, "branch": { "id": "wu", "chinese": "午", "pinyin": "wǔ", "animal": "horse", "element": "Fire", "polarity": "yang" }, "tenGod": { "id": "hurting-officer", "name": "Hurting Officer", "chinese": "伤官", "pinyin": "shāng guān", "category": "output", "keynote": "Talent, invention, and impatience with authority" }, "hiddenStems": [ { "stem": { "id": "ding", "chinese": "丁", "pinyin": "dīng", "element": "Fire", "polarity": "yin" }, "role": "principal", "tenGod": { "id": "seven-killings", "name": "Seven Killings", "chinese": "七杀", "pinyin": "qī shā", "category": "influence", "keynote": "Pressure, command, and anything won under real risk" } }, { "stem": { "id": "ji", "chinese": "己", "pinyin": "jǐ", "element": "Earth", "polarity": "yin" }, "role": "middle", "tenGod": { "id": "indirect-resource", "name": "Indirect Resource", "chinese": "偏印", "pinyin": "piān yìn", "category": "resource", "keynote": "Unusual learning and skill in narrow subjects" } } ], "naYin": "Wood of the Willow", "naYinChinese": "楊柳木", "naYinElement": "Wood" }, { "position": "day", "id": "xin-hai", "number": 48, "stem": { "id": "xin", "chinese": "辛", "pinyin": "xīn", "element": "Metal", "polarity": "yin" }, "branch": { "id": "hai", "chinese": "亥", "pinyin": "hài", "animal": "pig", "element": "Water", "polarity": "yin" }, "tenGod": { "id": "day-master", "name": "Day Master", "chinese": "日主", "pinyin": "rì zhǔ", "category": "self", "keynote": "The self the whole chart is read from" }, "hiddenStems": [ { "stem": { "id": "ren", "chinese": "壬", "pinyin": "rén", "element": "Water", "polarity": "yang" }, "role": "principal", "tenGod": { "id": "hurting-officer", "name": "Hurting Officer", "chinese": "伤官", "pinyin": "shāng guān", "category": "output", "keynote": "Talent, invention, and impatience with authority" } }, { "stem": { "id": "jia", "chinese": "甲", "pinyin": "jiǎ", "element": "Wood", "polarity": "yang" }, "role": "middle", "tenGod": { "id": "direct-wealth", "name": "Direct Wealth", "chinese": "正财", "pinyin": "zhèng cái", "category": "wealth", "keynote": "Earned assets and the commitments that hold them" } } ], "naYin": "Metal of Hairpin and Bracelet", "naYinChinese": "釵釧金", "naYinElement": "Metal" }, { "position": "hour", "id": "yi-wei", "number": 32, "stem": { "id": "yi", "chinese": "乙", "pinyin": "yǐ", "element": "Wood", "polarity": "yin" }, "branch": { "id": "wei", "chinese": "未", "pinyin": "wèi", "animal": "goat", "element": "Earth", "polarity": "yin" }, "tenGod": { "id": "indirect-wealth", "name": "Indirect Wealth", "chinese": "偏财", "pinyin": "piān cái", "category": "wealth", "keynote": "Opportunity, circulation, and money that moves" }, "hiddenStems": [ { "stem": { "id": "ji", "chinese": "己", "pinyin": "jǐ", "element": "Earth", "polarity": "yin" }, "role": "principal", "tenGod": { "id": "indirect-resource", "name": "Indirect Resource", "chinese": "偏印", "pinyin": "piān yìn", "category": "resource", "keynote": "Unusual learning and skill in narrow subjects" } }, { "stem": { "id": "ding", "chinese": "丁", "pinyin": "dīng", "element": "Fire", "polarity": "yin" }, "role": "middle", "tenGod": { "id": "seven-killings", "name": "Seven Killings", "chinese": "七杀", "pinyin": "qī shā", "category": "influence", "keynote": "Pressure, command, and anything won under real risk" } }, { "stem": { "id": "yi", "chinese": "乙", "pinyin": "yǐ", "element": "Wood", "polarity": "yin" }, "role": "residual", "tenGod": { "id": "indirect-wealth", "name": "Indirect Wealth", "chinese": "偏财", "pinyin": "piān cái", "category": "wealth", "keynote": "Opportunity, circulation, and money that moves" } } ], "naYin": "Metal in the Sand", "naYinChinese": "沙中金", "naYinElement": "Metal" } ], "dayMaster": { "stem": "xin", "chinese": "辛", "pinyin": "xīn", "element": "Metal", "polarity": "yin", "nature": "Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine." }, "zodiacAnimal": "horse", "fiveElements": [ { "element": "Wood", "count": 1, "level": "balanced", "reading": "Wood is present in proportion. There is enough initiative to begin things and enough give to change course without the chart being governed by either." }, { "element": "Fire", "count": 2, "level": "balanced", "reading": "Fire is present in proportion. There is enough heat to be seen and to convince, without the chart burning through what it builds." }, { "element": "Earth", "count": 1, "level": "balanced", "reading": "Earth is present in proportion. There is enough ground to hold what the chart produces without so much that nothing moves." }, { "element": "Metal", "count": 2, "level": "balanced", "reading": "Metal is present in proportion. There is enough edge to finish and to decide without the chart cutting into what should have been left standing." }, { "element": "Water", "count": 2, "level": "balanced", "reading": "Water is present in proportion. Ideas and information move through the chart without washing away the structure they move through." } ], "interactions": [ { "type": "punishment", "id": "wu-wu", "chinese": "午自刑", "pinyin": "wǔ zì xíng", "quality": "challenging", "positions": [ "year", "month" ], "members": [ "wu", "wu" ], "variety": "self", "complete": true, "meaning": "Branches that grind against each other rather than colliding. A punishment works slowly and internally: friction that accumulates, obligations that turn on their holder, situations that were entered willingly and become difficult to leave. A branch doubled against itself. Nothing external is involved, which is what makes it the hardest of the four to see: the pattern repeats because the chart keeps supplying it." }, { "type": "stem-combination", "id": "geng-yi", "chinese": "乙庚合", "pinyin": "yǐ gēng hé", "quality": "harmonious", "positions": [ "year", "hour" ], "members": [ "geng", "yi" ], "transformsTo": "Metal", "meaning": "Two Heavenly Stems that pair off. The bond is the strongest tie between two stems and it works both ways: it can settle a stem that was causing trouble, and it can occupy a stem that was needed elsewhere. A stem that is busy being bonded is not doing its job in the chart." }, { "type": "six-combination", "id": "wei-wu", "chinese": "午未合", "pinyin": "wǔ wèi hé", "quality": "harmonious", "positions": [ "year", "hour" ], "members": [ "wu", "wei" ], "meaning": "Two Earthly Branches that bind. The pairing is astronomical in origin, the branch the sun and moon meet in set against the branch the Dipper handle points to in the same month, which is why the six are exactly the pairs they are. In a chart it reads as attachment and cooperation, and as a tie that is not easily walked away from." }, { "type": "six-combination", "id": "wei-wu", "chinese": "午未合", "pinyin": "wǔ wèi hé", "quality": "harmonious", "positions": [ "month", "hour" ], "members": [ "wu", "wei" ], "meaning": "Two Earthly Branches that bind. The pairing is astronomical in origin, the branch the sun and moon meet in set against the branch the Dipper handle points to in the same month, which is why the six are exactly the pairs they are. In a chart it reads as attachment and cooperation, and as a tie that is not easily walked away from." }, { "type": "stem-clash", "id": "xin-yi", "chinese": "乙辛冲", "pinyin": "yǐ xīn chōng", "quality": "challenging", "positions": [ "day", "hour" ], "members": [ "xin", "yi" ], "meaning": "Two Heavenly Stems standing directly opposite, each controlling the other by element. Stems act faster than branches, so a stem clash shows up quickly and on the surface: open disagreement, a decision forced early, a position that has to be defended." } ], "summary": "This chart has a Metal Day Master born in a Fire month. The stem itself reads this way: Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine. As for the season: The season controls the Day Master element, the weakest of the five seasonal states. Everything the chart does from here has to be paid for by support found elsewhere." } ``` ## MCP Tool Naming Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/chinese-astrology`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`: ``` POST /chinese-astrology/bazi/chart -> post_chinese_astrology_bazi_chart POST /chinese-astrology/bazi/luck-pillars -> post_chinese_astrology_bazi_luck_pillars POST /chinese-astrology/bazi/day-master -> post_chinese_astrology_bazi_day_master ``` `tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call). ## Multi-language Support Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr, zh-Hans, zh-Hant`. English is the default. The `lang` param is ignored on endpoints that have no translatable text. ## Error Contract Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable): - `validation_error` (400, returns `issues[]` with all field errors at once) - `api_key_required` (401), `invalid_api_key` (401) - `subscription_inactive` (403), `subscription_not_found` (404) - `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field) - `rate_limit_exceeded` (429) - `internal_error` (500) Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff. ## Related Surfaces - [Multilingual Astrology API: How to Verify Language Support](https://roxyapi.com/blogs/multilingual-astrology-api-verify-language-support.md) - [Composite Chart Houses: Why Two Calculators Disagree](https://roxyapi.com/blogs/composite-chart-house-cusps-midpoint-reference-place.md) - [Astrology API Data Residency: A GDPR Buyer Checklist](https://roxyapi.com/blogs/astrology-api-data-residency-gdpr-checklist.md) - [Astrology API Contract Terms: A Vendor Diligence Guide](https://roxyapi.com/blogs/astrology-api-vendor-diligence-contract-terms.md) ## Full Reference For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/chinese-astrology/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.