
Astrology API Accuracy Benchmark
Benchmark / Open Source5 minIndependent proof, domain by domain. Every reference value cited, rerun monthly.
A BaZi Four Pillars chart and Chinese zodiac sign that tell you which school they came from.
BaZiFour PillarsLuck PillarsDay MasterBaZi CompatibilityBaZi Annual ForecastChinese ZodiacChinese Zodiac CompatibilityDaily Chinese ZodiacChinese Lunar CalendarTong Shu AlmanacChinese Date SelectionSolar TermsFive Elements and 6 more
Included with every plan (at no extra cost)
Chinese zodiac and BaZi astrology API: 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 13,405 automated tests per deploy, 3,620 of them gold-standard tests locked to the named references on our methodology page. See how we test.
Interpretations in English, Deutsch, Español, Français, हिन्दी, Português, Русский, Türkçe, 简体中文, 繁體中文, one query parameter away.
Typed SDKs for TypeScript, Python, PHP, C#, and Go, generated from the live spec, each with an AGENTS.md so your coding assistant calls the Chinese Astrology API correctly.
A Remote MCP server exposes every endpoint as a tool for Claude, ChatGPT, Cursor and any MCP client, with no local install. Opt-in compact responses cut the tokens your agent reads by roughly 40 to 52 percent, and one call stays one request.
Paste a widget into any site builder, install the WordPress plugin, or start from an MIT template you can white-label. Results render from the Chinese Astrology API with no backend.
The depth behind every line above, written out in full.
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)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.
Full MCP setup guidecurl -H "X-API-Key: YOUR_KEY" \
https://roxyapi.com/api/v2/chinese-astrology/Want to ship faster? Clone a free template and white-label it as your own app.
Building with Cursor, Claude Code, or Bolt? Use our AI prompts to generate a complete app.
Building on WordPress? Install the RoxyAPI plugin and drop a shortcode, no code required.
{
"birthData": {
"date": "1990-06-15",
"time": "14:30:00",
"timezone": -4,
"latitude": 0,
"longitude": 116.4
},
"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
Render Chinese Astrology API responses without building charts yourself. Install the npm package and drop these into Next.js, React, Vue, Svelte, Angular, or plain HTML, or embed the very same component on Squarespace, Wix, or WordPress by pasting one snippet, with no backend and no build step. They belong to one library that covers the entire spiritual stack rather than astrology alone, MIT licensed and included in every plan at no extra cost, never a separate product and never an upsell. The Chinese Astrology API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.
Luck pillars widget snippet
Zodiac card widget snippet
Almanac day widget snippet
The complete UI libraryExplore Roxy UI| Element | Renders |
|---|---|
| <roxy-bazi-chart> | Year, month, day and hour pillars in hanzi with hidden stems, Ten Gods, Na Yin, element balance and interactions |
| <roxy-luck-pillars> | Ten-year luck pillars as a strip with ages and years, the annual pillars, and the direction and start age behind them |
| <roxy-zodiac-card> | The animal for a date, one animal in full, a daily reading, or a pair scored |
| <roxy-almanac-day> | Day officer, favours and avoids, clash animal and pillars, as one day, a month, or a date search |
Clone. Edit. Ship. Free and open source by Team Roxy.

Independent proof, domain by domain. Every reference value cited, rerun monthly.
Browse all template or use AI prompts to generate a custom app.
The products teams ship on the Chinese Astrology API.
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.
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.
Your agent uses calculated charts and readings in its replies, with your model and your own voice. Planetary positions are verified against NASA JPL Horizons. No local setup, no AGPL, no hosted-AI markup.
Audit it yourself: every Chinese Astrology endpoint runs live in the API playground
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.
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.
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.
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.
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.
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.
A BaZi Four Pillars chart and Chinese zodiac sign that tell you which school they came from.
All 18 domains included with every plan. Every endpoint, MCP server, SDK, and templates.
Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.
View Pricing & Get API KeyHi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.