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
Start building in seconds.
Want to try without writing code? Try this domain live in API playground →
npm install @roxyapi/sdkimport { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.chineseAstrology.get(/* ... */)pip install roxy-sdkfrom roxy_sdk import create_roxy
roxy = create_roxy("your-api-key")
result = roxy.chinese_astrology.get(...) # async: await roxy.chinese_astrology.get_async(...)composer require roxyapi/sdkuse function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->chineseAstrology->get(/* ... */);dotnet add package RoxyApi.Sdkusing RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
// await roxy.ChineseAstrology.<resource>.GetAsync() or .PostAsync(new() { ... })go get github.com/RoxyAPI/sdk-goimport roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
// resp, err := roxy.ChineseAstrology.<Method>(context.Background(), nil)curl -H "X-API-Key: YOUR_KEY" \
https://roxyapi.com/api/v2/chinese-astrology/claude mcp add --transport http \
roxy-chinese-astrology https://roxyapi.com/mcp/chinese-astrology \
--header "X-API-Key: YOUR_KEY"AI agents auto-discover all endpoints as callable tools. Zero configuration. Responses can come back token-optimized and lossless, cutting the tokens your agent spends per call by roughly 40 to 52 percent.
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.
{
"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
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
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.
Show all endpointsShow fewer endpoints
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
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.
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.
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.
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 SDK | npm i @roxyapi/sdk |
| 2Get your API key | View Plans |
| 3Make your first call | View Docs |
Agent-Ready Infrastructure
MCPRemote 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 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