Chinese Astrology API

A BaZi chart that tells you which school it came from.

BaZiFour PillarsChinese ZodiacChinese CalendarSolar TermsTong Shu Almanac …and so much more

99.95%+uptime

Start building in seconds.

Want to try without writing code? Try this domain live in API playground →

Terminal
npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.chineseAstrology.get(/* ... */)
SDK docs

Want to ship faster? Clone a free template and go from zero to production in 30 minutes.

Building with Cursor, Claude Code, or Bolt? Use our AI prompts to generate a complete app in minutes.

Building on WordPress? Install the RoxyAPI plugin and drop a shortcode, no code required.

POST /api/v2/chinese-astrology/bazi/chart
{
  "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."
}

Structured JSON with documented fields. Not hallucinated text. See all endpoints

Works with your stack

Claude CodeCursorAntigravityChatGPTWindsurfVS Code CopilotOpenAI AgentsGeminiLangChainCrewAIVercel AI SDK

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.

Every Chinese Astrology calculation is covered by 8,896 automated tests per deploy, 1,983 of them gold-standard tests locked to named external references such as NASA JPL Horizons, with a public MIT benchmark repo anyone can clone and re-run. See how we test.

Multi-language API responses

EnglishDeutschEspanolFrancaisHindiPortuguesRusskiyTurkcezh-Hanszh-Hant

Key Features

Everything you need from our Chinese Astrology API, built for production:

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

All 16 Endpoints

Every one is live in the public OpenAPI spec and callable as an MCP tool. Click any endpoint to view detailed documentation, parameters, and response examples.

Generate BaZi chart - Four Pillars of Destiny calculator APICalculate a complete BaZi chart, the Four Pillars of Destiny, from a birth moment. Returns the year, month, day and hour pillars with every Heavenly Stem and Earthly Branch, the stems hidden inside each branch, the Ten God relation each one holds to the Day Master, the Na Yin sound element of each pair, the five-element balance across the chart, and the combinations and clashes running between the pillars. The day boundary, year boundary and hour clock are all selectable and the applied conventions come back on every response, so a chart is self-describing. Built for astrology apps, matchmaking services, and agents that need a Four Pillars reading they can reproduce.Calculate luck pillars - BaZi Da Yun ten-year cycle APICalculate the da yun luck pillars, the ten-year periods a BaZi chart walks through after birth. Returns the direction the sequence runs, the age it begins at with the day count behind that age, each ten-year pillar with the Ten God relation its stem holds to the natal Day Master, and an optional year-by-year annual overlay. Direction follows the classical rule: a male born in a yang-stem year and a female born in a yin-stem year run forward through the sexagenary cycle, the other two combinations run backward. Built for astrology apps, life-timing features, and agents that need a reproducible forecast spine.Calculate Day Master strength - BaZi favorable element APIAssess how well the Day Master is supported by the rest of a BaZi chart, and which of the five elements help it. Uses the classical three-factor method: whether the birth month season backs the Day Master element, whether any branch stores a root for it, and whether the other stems help or spend it. Returns the verdict, an auditable score with each factor contribution, the seasonal state, the root count, the element headcount, and the favorable and unfavorable element lists that follow from the verdict. Built for chart readers, remedy features, and agents that need the usable half of a Four Pillars reading.Calculate BaZi compatibility - Four Pillars matchmaking APICompare two BaZi charts pillar by pillar. Returns both resolved charts, how the two Day Masters stand to each other on the five-phase cycle, and every combination, clash, harm and punishment that crosses between them, each naming the two positions it joins. A tallied score summarises the balance and the interaction list behind it is returned in full, so a caller that disagrees with the weighting can recompute its own. Built for matchmaking products, relationship features, and agents that need a defensible two-chart reading.Calculate BaZi annual forecast - Liu Nian yearly pillar APIRead one Gregorian year against a natal BaZi chart. Returns the annual pillar for that year, the Ten God relation its stem holds to the natal Day Master, the same reading for the hidden stem of its branch, how the annual branch stands to the natal year branch including the ben ming nian return of the birth animal, and every combination, clash, harm and punishment the annual pillar forms with each of the four natal pillars. Built for yearly horoscope features, timing tools, and agents that need a year read against a specific chart rather than against an animal sign.List the 12 Chinese zodiac animals - Sheng Xiao sign catalogueRetrieve all twelve Chinese zodiac animals in cycle order, from Rat through Pig. Each entry returns the machine id, the Chinese character and tone-marked pinyin for the animal, its Earthly Branch, the fixed Five Element phase and yin or yang polarity of that branch, and a set of trait keywords. Built for sign pickers, zodiac cards and compatibility widgets that need the whole set in one call.Get one Chinese zodiac animal - Full sign profile with compatibility partnersRetrieve the complete profile of one Chinese zodiac animal: character summary, strengths, weaknesses, trait keywords, the double-hour its Earthly Branch governs, and its five element variants with the Gregorian years that carry each one. Also returns the four classical branch relationships, the three-harmony trine it belongs to, its six-harmony secret friend, its clashing opposite and its harming partner. Built for sign detail pages and compatibility features.Find the Chinese zodiac animal for a birth date - Sheng Xiao calculatorResolve a birth date to its Chinese zodiac animal, the sexagenary year pillar behind it, and the Five Element phase of that year, so a 1990 birth returns Horse as a Metal Horse rather than merely a Horse. The year boundary is a request parameter because the two schools genuinely disagree for dates in January and early February, and the resolved convention is echoed back so the answer is self-describing. Built for sign lookups, onboarding forms and birthday features.Chinese zodiac compatibility - Trine, six harmony, clash and harm analysisScore and explain the relationship between two Chinese zodiac animals from the classical branch relations rather than from a lookup table of opinions. Returns which of the six relations the pair stands in, a score out of 100, the phase the two branches combine into where they combine at all, and a composed reading with strengths, frictions and advice. The six relations are mutually exclusive by construction, so exactly one applies to any pair. Built for matchmaking features, relationship reports and compatibility widgets.Daily Chinese zodiac reading - Day pillar forecast by animal signGet the daily reading for one Chinese zodiac animal, built from the sexagenary day pillar rather than from a rotation of stock text. The day carries its own Earthly Branch, that branch stands in exactly one of six classical relations to the requested sign, and the reading is that relation applied to the sign temperament. Returns the day pillar, the relation, an energy rating, overview, love and career guidance, advice, and the sexagenary year in force with its Ben Ming Nian flag. Content is fixed for a given date and rolls over at midnight, by default UTC.List the 24 solar terms - Jie Qi calendar API with exact instantsReturn all 24 solar terms of a year as astronomical instants rather than dates, each computed from the moment the sun reaches its exact apparent longitude at 15 degree steps. The year is the SOLAR year, which opens at Li Chun in early February, so Minor Cold and Major Cold, the last two terms, are dated in the January of the following Gregorian year. Every instant is returned twice, once in UTC and once at the UTC+8 reference meridian the Chinese calendar is defined on. Built for calendar apps, festival scheduling, and any BaZi feature that has to place a birth on the correct side of a term boundary.Convert lunar and Gregorian dates - Chinese lunisolar calendar APIConvert a Gregorian date to the Chinese lunisolar calendar or convert a lunar date back, in one endpoint. The calendar is computed at the UTC+8 reference meridian with the month containing the winter solstice fixed as month 11 and the leap month placed as the first month of the cycle carrying no major solar term, so a lunar date is the same worldwide rather than shifting with the caller timezone. The response reports the length of the lunar month, whether the date sits in a leap month, and which month the year doubles if any. Built for festival calendars, birthday features that follow the lunar date, and any app that has to survive a leap month without shifting every date after it.
Show all endpoints
Get the almanac for a day - Tong Shu API with day officers and mansionsReturn the full almanac reading of one day: its lunisolar date, the year, month and day pillars with their Na Yin, the day officer from the twelve jian chu sequence, the lunar mansion on duty, the zodiac animal the day clashes with, and the activities the officer favours or opposes. The day officer is the layer a printed almanac reaches its verdict from first, and the response says exactly what it rules on rather than reducing the day to a single score. The year and month pillars here are attributed by whole days, which is what an almanac prints: the day a solar term falls on belongs to the new period for its whole length, however late in the day the term arrives. Built for date pickers, daily calendar widgets, and wedding or opening date tools.Get a month of almanac days - Chinese calendar month view APIReturn every day of one Gregorian month with its lunisolar date, its three pillars, its day officer, its lunar mansion and its clash animal, plus the solar terms that fall inside the month. This is the month view a calendar widget renders in one call rather than thirty one. Omit the year and month to get the month in progress. Built for calendar UIs, almanac pages, and planning tools that show a whole month at a glance.Find auspicious days - Chinese date selection API for weddings and openingsSearch a date range for the days a chosen activity is favoured on, ranked by the jian chu day officer and filtered against a zodiac animal to protect. Every candidate day comes back with its officer, its pillars, its lunar date and the animal it clashes with, so a caller can show the reasoning rather than a bare verdict. The range is capped at 93 days, which is a quarter, because date selection is done inside a planning window rather than across a lifetime. Built for wedding planners, business opening tools, and moving and travel date pickers.List the five elements - Wu Xing API with generating and controlling cyclesReturn the five phases of Wu Xing with the Chinese character, the season and direction each governs, the Heavenly Stems and Earthly Branches that carry it, and both of the cycles that connect them. The generating cycle and the controlling cycle are returned as ordered rings as well as on each phase, so a caller can render either without deriving it. This is the one place the five phase vocabulary is defined: BaZi charts, Na Yin, zodiac element variants and every feng shui star reuse these identifiers rather than restating them.

What You Can Build with Chinese Astrology API

Real-world applications and use cases for integrating Chinese Astrology API into your projects:

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

What developers are saying

DM

Dhani M.

Indie App Developer

Shipped an astrology app over a long weekend. Birth charts, nakshatras, KP cusps, significators. I verified the Lahiri ayanamsha values independently and they line up with my reference. One API key for all of it.

Email feedback
TH

Tom H.

Senior Developer

The OpenAPI spec is the most complete I have seen in this space. Generated a type-safe TypeScript client from it in seconds. Every field has descriptions and examples. Production-grade documentation.

Email feedback
CW

Chris W.

Backend Engineer

Response times consistently under 50ms for numerology and tarot endpoints. The API returns structured JSON with every field documented. Integrated it into our platform in an afternoon.

Email feedback

Do not take our word for it. Ask the agents.

The receipts are public: the testing methodology, the open MIT benchmark, the transparency report, and the live API playground. Let ChatGPT, Perplexity, or Claude search the web and tell you what they find about RoxyAPI accuracy, MCP, SDKs, and pricing.

Opens a live web search in a new tab.

Getting started with Chinese Astrology API.

From zero to production in 3 steps. No signup required for testing.

3 Steps to Ship

1Install the SDKnpm i @roxyapi/sdk
2Get your API keyView Plans
3Make your first callView Docs

Agent-Ready Infrastructure

MCP

Remote MCP, llms.txt, and AGENTS.md. The full agent-readiness stack for 14+ domains under one key.

  • Remote MCP server — every endpoint auto-discovered as a tool by Claude, ChatGPT, Cursor over Streamable HTTP. No Docker.
  • Token-optimized responses — opt-in compact mode returns the same data with each field name sent once, cutting the tokens your agent reads per call by roughly 40 to 52 percent. Lossless, and one call still counts as one request.
  • llms.txt — AI-native discovery surface for ChatGPT, Perplexity, and Gemini citation
  • AGENTS.md — 2026 execution playbook for Cursor, Codex, Windsurf, Aider, Claude Code, Gemini CLI. Bundled in the SDK.

From your AI agent to a verified Chinese Astrology answer.

Your AI agentyour model, your voice
Remote MCPauto-discovered, no local setupToken-optimized
Roxy Ephemeris8,896 tests, 1983 vs NASA JPL
Verified result12 domains, one flat rate

Your agent grounds every answer in verified calculations and replies in your own voice, so it never hallucinates a chart, date, or reading. No local setup, no AGPL, no hosted-AI markup.

Audit it yourself: every Chinese Astrology endpoint runs live in the API playground

Chinese Astrology API 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.

Start using Chinese Astrology API today.

A BaZi chart that tells you which school it came from.

All 14 domains included with every plan. Every endpoint, MCP server, SDK, and starters.

Plans from $39/mo, starting at $2.32 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key