{"openapi":"3.1.0","info":{"title":"Chinese Astrology API","version":"2.0.0","description":"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.\n\n# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 14 domains (Astrology, Vedic Astrology, Forecast, Human Design, Chinese Astrology, Feng Shui, Numerology, Tarot Reading, Biorhythm, I-Ching Oracle, Crystals and Healing Stones, Dream Interpretation, Angel Numbers, Location and Timezone), 209+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (Remote MCP)\n\nRoxyAPI ships a Remote MCP server per product over Streamable HTTP, with no local setup and no Docker. Your AI agent auto-discovers all 209+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable and stable, so it is the one safe to switch on programmatically.\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset` (Unix timestamp, seconds). Quotas reset on the 1st of every calendar month at 12:00 AM UTC, not on your renewal date.\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 per month for 50K requests, up to 3M requests, with custom volume above that.\n\nSee [roxyapi.com/pricing](https://roxyapi.com/pricing)\n\n## Resources\n\n- [Quickstart guide](https://roxyapi.com/docs/quickstart) - first API call in 60 seconds\n- [Documentation](https://roxyapi.com/docs) - guides, tutorials, domain reference\n- [MCP setup](https://roxyapi.com/docs/mcp) - connect AI agents\n- [Starter apps](https://roxyapi.com/starters) - clone and deploy in 30 minutes\n- [FAQ](https://roxyapi.com/faq) - common questions\n- [Contact](https://roxyapi.com/contact) - support and API key recovery\n","contact":{"name":"RoxyAPI Support","url":"https://roxyapi.com/contact"},"license":{"name":"Proprietary","url":"https://roxyapi.com/policy/terms"}},"externalDocs":{"description":"Complete API Documentation with Examples","url":"https://roxyapi.com/docs"},"servers":[{"url":"/api/v2","description":"Production API v2"}],"security":[{"apiKey":[]}],"tags":[{"name":"Chinese Astrology","description":"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."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key for accessing RoxyAPI. Alternatively, you can pass the API key as a query parameter \"api_key\"."}},"schemas":{},"parameters":{}},"paths":{"/bazi/chart":{"post":{"operationId":"generateBaziChart","tags":["Chinese Astrology"],"summary":"Generate BaZi chart - Four Pillars of Destiny calculator API","description":"Calculate 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Four pillars, Day Master, element balance, interactions, and the conventions","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"type":"number","example":8,"description":"Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force on the birth date, so this is the literal number applied and never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."}},"required":["date","time","timezone"],"description":"Echo of the birth moment the chart was computed from."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."},"pillars":{"type":"array","items":{"type":"object","properties":{"position":{"type":"string","example":"year","description":"Which of the four pillars this is. One of year, month, day, hour. The year pillar reads ancestry and early life, the month career and parents, the day the self and the partner, the hour later life and children."},"id":{"type":"string","example":"geng-wu","description":"Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says."},"number":{"type":"number","example":7,"description":"Position of this pillar in the sexagenary cycle, 1 to 60, where jia-zi is 1. The cycle runs stems and branches together, which is why only 60 of the 120 possible pairings occur."},"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The Heavenly Stem of this pillar."},"branch":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that \"wu\" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position."},"chinese":{"type":"string","example":"午","description":"The branch in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"wǔ","description":"Tone-marked pinyin for the branch. Identical under every lang."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"element":{"type":"string","example":"Fire","description":"Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the branch, yang or yin."}},"required":["id","chinese","pinyin","animal","element","polarity"],"description":"The Earthly Branch of this pillar."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the pillar STEM holds to the Day Master. The day pillar carries day-master instead, because the day stem is the reference point every other position is measured from rather than a relation to itself."},"hiddenStems":{"type":"array","items":{"type":"object","properties":{"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The stem stored in the branch."},"role":{"type":"string","example":"principal","description":"Rank of this stem inside the branch, by the classical day-count that divides a thirty-day month 18, 9 and 3 days between the stems a branch holds. principal is the first-ranked stem and always matches the branch element; middle is the second-ranked; residual is the third. A branch holds one to three, always returned in rank order. What each rank CONTAINS depends on the branch family: on a storage branch the second-ranked stem is the seasonal carryover from the month before and the third is the stem that branch stores as the close of its trine, while on a growth branch the second-ranked stem is the one beginning its long-life phase there and the third is the carryover. Some schools name the same three positions by that function rather than by rank, which swaps the second and third labels on the four storage branches, so compare on rank rather than assuming a name."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation this hidden stem holds to the Day Master."}},"required":["stem","role","tenGod"]},"description":"Stems stored inside the branch, principal first. These carry the qi a branch holds without showing it, and they are where a Day Master finds a root."},"naYin":{"type":"string","example":"Earth by the Roadside","description":"Na Yin sound element of the pillar, an older elemental reading assigned to each of the 30 stem-and-branch pairs. The hanzi name sits beside it in naYinChinese."},"naYinChinese":{"type":"string","example":"路旁土","description":"The Na Yin name in hanzi. Identical under every lang."},"naYinElement":{"type":"string","example":"Earth","description":"Element the Na Yin resolves to. Independent of the stem element and often different from it, which is why it is reported separately rather than folded in."}},"required":["position","id","number","stem","branch","tenGod","hiddenStems","naYin","naYinChinese","naYinElement"]},"description":"The four pillars, year first. Each carries its stem, its branch, the hidden stems stored in the branch, the Ten God relation to the Day Master, and the Na Yin sound element of the pair."},"dayMaster":{"type":"object","properties":{"stem":{"type":"string","example":"xin","description":"Day stem identifier, which IS the Day Master. Always English pinyin, whatever the lang parameter says."},"chinese":{"type":"string","example":"辛","description":"The Day Master stem in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"xīn","description":"Tone-marked pinyin for the Day Master stem."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the Day Master. Every Ten God in the chart is measured from this element and this polarity. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yin","description":"Polarity of the Day Master, yang or yin."},"nature":{"type":"string","example":"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.","description":"What this particular stem is like as a Day Master, in the imagery the tradition uses to distinguish the two stems of each element. The yang and yin forms of one element behave very differently and this is where that difference lives."}},"required":["stem","chinese","pinyin","element","polarity","nature"],"description":"The day stem, which is the subject of the whole chart. Everything else in the response is named by what it does to this one."},"zodiacAnimal":{"type":"string","example":"horse","description":"Zodiac animal of the year branch, under the year boundary this request applied. Always English, whatever the lang parameter says. Use zodiacAnimalLocalized for anything a reader sees."},"zodiacAnimalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"fiveElements":{"type":"array","items":{"type":"object","properties":{"element":{"type":"string","example":"Fire","description":"Five-phase element. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"count":{"type":"number","example":2,"description":"How many of the eight chart characters carry this element, counting the four stems and the four branch elements one point each. Hidden stems are deliberately not counted here: a weighted total is a different quantity and mixing the two produces a number that matches no other calculator."},"level":{"type":"string","example":"balanced","description":"How represented the element is. deficient means absent from all eight characters, excess means three or more, balanced is one or two. Always English, whatever the lang parameter says."},"reading":{"type":"string","example":"Fire is present in proportion. There is enough heat to be seen and to convince, without the chart burning through what it builds.","description":"What this level of representation means for the chart."}},"required":["element","count","level","reading"]},"description":"Element balance across the eight chart characters, one entry per phase, with the reading for how represented each one is."},"interactions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"clash","description":"Kind of interaction. stem-combination and six-combination bind two positions, trine binds three, and clash, harm, punishment and stem-clash break them. Always English, whatever the lang parameter says."},"id":{"type":"string","example":"wu-zi","description":"Identifier of the pairing itself, the member ids joined by hyphens in canonical order."},"chinese":{"type":"string","example":"子午冲","description":"The interaction named in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"zǐ wǔ chōng","description":"Tone-marked pinyin for the interaction. Identical under every lang."},"quality":{"type":"string","example":"challenging","description":"Whether the interaction binds or breaks. harmonious for combinations and trines, challenging for clashes, harms and punishments. Always English, whatever the lang parameter says."},"positions":{"type":"array","items":{"type":"string"},"example":["year","month"],"description":"The chart positions taking part, in the same order as members. On a two-person reading these are prefixed with the subject, for example personA.day."},"members":{"type":"array","items":{"type":"string"},"example":["zi","wu"],"description":"The stem or branch ids taking part, in the same order as positions."},"transformsTo":{"type":"string","example":"Water","description":"Element the formation resolves to. Present on stem combinations and on complete trines, absent on everything else. Branch six combinations deliberately carry none: the classical sources assign transformed elements to the stem pairs and not to these, and one of the six is contested between schools."},"variety":{"type":"string","example":"ungrateful","description":"Class of a punishment, present on punishments only. ungrateful is the tiger, snake and monkey group, bullying the ox, dog and goat group, discourteous the rat and rabbit pair, and self a branch doubled against itself."},"complete":{"type":"boolean","example":false,"description":"Punishments only. True when the third branch of the group is also present in the chart, which is what a complete three-punishment means. False marks the partial case, where only two of the three are in play."},"meaning":{"type":"string","example":"Two Earthly Branches directly opposite on the cycle, six positions apart. A clash moves things: it breaks what was settled, and what it breaks is whatever the two positions govern. Not simply bad, and never quiet.","description":"What this kind of interaction does between the positions it joins."}},"required":["type","id","chinese","pinyin","quality","positions","members","meaning"]},"description":"Combinations, clashes, harms and punishments running between the four pillars. An empty array means the four pillars stand independently of each other, which is common and is not a defect."},"summary":{"type":"string","example":"A Metal Day Master born in a Fire month. 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. 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.","description":"One-paragraph reading composed from the Day Master nature and the seasonal state of its element in the birth month. The narrative entry point for a chart, for a consumer that renders one block before the detail."}},"required":["birthData","conventions","pillars","dayMaster","zodiacAnimal","fiveElements","interactions","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bazi/luck-pillars":{"post":{"operationId":"calculateLuckPillars","tags":["Chinese Astrology"],"summary":"Calculate luck pillars - BaZi Da Yun ten-year cycle API","description":"Calculate 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."},"gender":{"type":"string","enum":["male","female"],"example":"male","description":"Subject sex, used only to pick the luck-pillar direction: a male born in a yang-stem year and a female born in a yin-stem year run forward through the sexagenary cycle, and the other two combinations run backward. It affects nothing else in the response."},"count":{"type":"integer","minimum":1,"maximum":12,"default":8,"example":8,"description":"How many ten-year luck pillars to return, 1 to 12. Eight covers eighty years from the start age, which reaches past a normal lifetime for most start ages."},"annualFromYear":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"First Gregorian year of the annual pillar overlay. Omit it to leave annualPillars out of the response entirely. The annual pillar is the year the chart is currently walking through, read against the ten-year luck pillar underneath it."},"annualYears":{"type":"integer","minimum":1,"maximum":20,"default":10,"example":10,"description":"How many consecutive years the annual overlay covers, 1 to 20. Ignored unless annualFromYear is present."}},"required":["date","time","timezone","gender"]}}}},"responses":{"200":{"description":"Luck pillar sequence with start age, direction, and optional annual overlay","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"type":"number","example":8,"description":"Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force on the birth date, so this is the literal number applied and never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."}},"required":["date","time","timezone"],"description":"Echo of the birth moment the chart was computed from."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."},"gender":{"type":"string","example":"male","description":"Echo of the sex sent, which is what selected the direction below."},"direction":{"type":"string","example":"forward","description":"Which way the sequence walks the sexagenary cycle. A male born in a yang-stem year and a female born in a yin-stem year run forward, and the other two combinations run backward. Always English, whatever the lang parameter says."},"startAge":{"type":"number","example":7,"description":"Age in whole years at which the first luck pillar begins. Counted from the birth instant to the adjacent minor solar term at three days to the year, forward for a forward direction and backward for a reverse one."},"startAgeMonths":{"type":"number","example":2,"description":"Additional months past startAge, 0 to 11, from the remainder of the same count at one day to four months. Calculators that round the whole count to the nearest year will differ from this by up to six months."},"daysToTerm":{"type":"number","example":21.4,"description":"Days from the birth instant to the minor solar term the count ran to, before conversion. Published so the start age can be checked rather than taken on trust."},"boundaryTerm":{"type":"string","example":"xiao-shu","description":"The minor solar term the count ran to. One of the twelve that also move the month pillar. Always the pinyin identifier, whatever the lang parameter says."},"luckPillars":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","example":1,"description":"Position in the sequence, starting at 1 for the first ten-year period."},"id":{"type":"string","example":"gui-wei","description":"Pillar identifier, the stem id and the branch id joined by a hyphen."},"number":{"type":"number","example":20,"description":"Position of this pillar in the sexagenary cycle, 1 to 60. Consecutive luck pillars always differ by exactly one step, forward or backward, because the sequence walks the cycle from the birth month pillar."},"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The Heavenly Stem of this luck pillar, with its element and polarity."},"branch":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that \"wu\" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position."},"chinese":{"type":"string","example":"午","description":"The branch in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"wǔ","description":"Tone-marked pinyin for the branch. Identical under every lang."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"element":{"type":"string","example":"Fire","description":"Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the branch, yang or yin."}},"required":["id","chinese","pinyin","animal","element","polarity"],"description":"The Earthly Branch of this luck pillar, with its animal, element and polarity."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the luck pillar STEM holds to the natal Day Master. This is what tells you whether a decade supports the chart or spends it."},"startAge":{"type":"number","example":7,"description":"Age in whole years at which this ten-year period begins."},"endAge":{"type":"number","example":17,"description":"Age in whole years at which this period ends and the next one begins."},"startYear":{"type":"number","example":1997,"description":"Gregorian year this period begins, the birth year plus startAge."},"endYear":{"type":"number","example":2007,"description":"Gregorian year this period ends."}},"required":["index","id","number","stem","branch","tenGod","startAge","endAge","startYear","endYear"]},"description":"The ten-year periods in order, each with the relation its stem holds to the natal Day Master."},"annualPillars":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Gregorian year."},"id":{"type":"string","example":"bing-wu","description":"Annual pillar identifier for that year, under the year boundary applied."},"number":{"type":"number","example":43,"description":"Position of the annual pillar in the sexagenary cycle, 1 to 60."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the annual pillar STEM holds to the natal Day Master."},"luckPillarIndex":{"type":"number","example":4,"description":"Which returned luck pillar this year falls inside, by its index. 0 means the year falls before the first luck pillar begins, in the stretch still governed by the natal chart alone."}},"required":["year","id","number","tenGod","luckPillarIndex"]},"description":"Year-by-year overlay, present only when annualFromYear was sent. Each year names the luck pillar it falls inside."},"summary":{"type":"string","example":"The luck pillars run forward from the birth month pillar, beginning at age 7. Each pillar governs ten years, and the current decade colours how the natal chart is experienced rather than replacing it.","description":"One-paragraph reading of the sequence direction and its start."}},"required":["birthData","conventions","gender","direction","startAge","startAgeMonths","daysToTerm","boundaryTerm","luckPillars","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bazi/day-master":{"post":{"operationId":"calculateDayMasterStrength","tags":["Chinese Astrology"],"summary":"Calculate Day Master strength - BaZi favorable element API","description":"Assess 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Strength verdict, contributing factors, and favorable elements","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"type":"number","example":8,"description":"Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force on the birth date, so this is the literal number applied and never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."}},"required":["date","time","timezone"],"description":"Echo of the birth moment the chart was computed from."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."},"dayMaster":{"type":"object","properties":{"stem":{"type":"string","example":"xin","description":"Day stem identifier. Always English pinyin, whatever the lang parameter says."},"chinese":{"type":"string","example":"辛","description":"The Day Master stem in hanzi."},"pinyin":{"type":"string","example":"xīn","description":"Tone-marked pinyin for the Day Master stem."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the Day Master, the element whose support is being weighed. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yin","description":"Polarity of the Day Master, yang or yin."},"nature":{"type":"string","example":"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.","description":"What this particular stem is like as a Day Master."}},"required":["stem","chinese","pinyin","element","polarity","nature"],"description":"The day stem whose strength is being assessed."},"verdict":{"type":"string","example":"weak","description":"Strength verdict. One of very-weak, weak, balanced, strong, very-strong, banded on the composite score below: under -3 is very-weak, -3 to under -1 is weak, -1 to under 1 is balanced, 1 to under 3 is strong, 3 and above is very-strong. Always English, whatever the lang parameter says."},"score":{"type":"number","example":-2.2,"description":"Composite support score, negative for an under-supported Day Master and positive for a well-supported one. A RoxyAPI weighting of the three classical factors rather than a figure from any text, published so the verdict can be audited: the three factor contributions sum to exactly this number."},"seasonalState":{"type":"string","example":"dead","description":"State of the Day Master element in the birth month, the strongest single input. One of prosperous, supported, resting, imprisoned, dead, which render the classical five wang xiang xiu qiu si. Always English, whatever the lang parameter says; the translated reading is seasonalStateMeaning."},"seasonalStateChinese":{"type":"string","example":"死","description":"The seasonal state in hanzi. Identical under every lang."},"seasonalStateMeaning":{"type":"string","example":"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.","description":"What this seasonal state means for the chart."},"rootCount":{"type":"number","example":0,"description":"How many of the four branches store a stem of the Day Master element. Zero means the day stem is rootless, which is the single most decisive finding a strength reading can return."},"factors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"month-command","description":"Which classical factor this is. month-command is de ling, whether the birth month season backs the Day Master element. rooting is de di, whether any branch stores a stem of that element. party is de shi, whether the other three stems help or spend it. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Month command","description":"Display name of the factor. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"chinese":{"type":"string","example":"得令","description":"The factor named in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"dé lìng","description":"Tone-marked pinyin for the factor. Identical under every lang."},"contribution":{"type":"number","example":-2,"description":"Points this factor contributed to the composite score, positive for support and negative for drain. The three contributions sum to score, so a caller who weights the factors differently can rebuild its own total from the same findings."},"detail":{"type":"string","example":"Metal is dead in a Fire month","description":"What the factor actually found in this chart, in one clause."}},"required":["id","name","chinese","pinyin","contribution","detail"]},"description":"The three classical factors behind the verdict, each with what it found and what it contributed. These are the citable part of the reading; the score is our arithmetic over them."},"favorableElements":{"type":"array","items":{"type":"string"},"example":["Metal","Earth"],"description":"Elements that help this chart. A weak Day Master wants its own element and the one that generates it; a strong one wants the three that drain, spend, or restrain it. Empty when the verdict is balanced, because a centred chart has no categorically favourable element and the incoming luck pillar decides. Always English, whatever the lang parameter says."},"unfavorableElements":{"type":"array","items":{"type":"string"},"example":["Water","Wood","Fire"],"description":"Elements that burden this chart, the complement of favorableElements. Also empty when the verdict is balanced."},"fiveElements":{"type":"array","items":{"type":"object","properties":{"element":{"type":"string","example":"Fire","description":"Five-phase element. Always English, whatever the lang parameter says."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"count":{"type":"number","example":2,"description":"How many of the eight chart characters carry this element, four stems and four branch elements at one point each."},"level":{"type":"string","example":"balanced","description":"How represented the element is. deficient is absent, excess is three or more, balanced is one or two."},"reading":{"type":"string","example":"Fire is present in proportion. There is enough heat to be seen and to convince, without the chart burning through what it builds.","description":"What this level of representation means for the chart."}},"required":["element","count","level","reading"]},"description":"Element headcount across the eight characters, the plain distribution behind the weighted verdict."},"summary":{"type":"string","example":"The Day Master reads weak. The Day Master is under-supported. It can act, and each act costs it, so what the chart needs is help and reinforcement rather than more to do. Periods that bring resource and peer elements read as relief. 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. With no root among the branches, support has to come from the stems and from the luck pillars.","description":"One-paragraph reading composed from the verdict, the seasonal state, and the rooting finding."}},"required":["birthData","conventions","dayMaster","verdict","score","seasonalState","seasonalStateChinese","seasonalStateMeaning","rootCount","factors","favorableElements","unfavorableElements","fiveElements","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bazi/compatibility":{"post":{"operationId":"calculateBaziCompatibility","tags":["Chinese Astrology"],"summary":"Calculate BaZi compatibility - Four Pillars matchmaking API","description":"Compare 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."}},"required":["date","time","timezone"],"description":"Birth moment of the first person. Each subject carries its own school switches, so two charts built under different conventions can still be compared."},"personB":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."}},"required":["date","time","timezone"],"description":"Birth moment of the second person."}},"required":["personA","personB"]}}}},"responses":{"200":{"description":"Both charts, the cross-chart interactions, and the compatibility score","content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"type":"object","properties":{"pillars":{"type":"array","items":{"type":"object","properties":{"position":{"type":"string","example":"year","description":"Which of the four pillars this is. One of year, month, day, hour. The year pillar reads ancestry and early life, the month career and parents, the day the self and the partner, the hour later life and children."},"id":{"type":"string","example":"geng-wu","description":"Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says."},"number":{"type":"number","example":7,"description":"Position of this pillar in the sexagenary cycle, 1 to 60, where jia-zi is 1. The cycle runs stems and branches together, which is why only 60 of the 120 possible pairings occur."},"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The Heavenly Stem of this pillar."},"branch":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that \"wu\" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position."},"chinese":{"type":"string","example":"午","description":"The branch in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"wǔ","description":"Tone-marked pinyin for the branch. Identical under every lang."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"element":{"type":"string","example":"Fire","description":"Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the branch, yang or yin."}},"required":["id","chinese","pinyin","animal","element","polarity"],"description":"The Earthly Branch of this pillar."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the pillar STEM holds to the Day Master. The day pillar carries day-master instead, because the day stem is the reference point every other position is measured from rather than a relation to itself."},"hiddenStems":{"type":"array","items":{"type":"object","properties":{"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The stem stored in the branch."},"role":{"type":"string","example":"principal","description":"Rank of this stem inside the branch, by the classical day-count that divides a thirty-day month 18, 9 and 3 days between the stems a branch holds. principal is the first-ranked stem and always matches the branch element; middle is the second-ranked; residual is the third. A branch holds one to three, always returned in rank order. What each rank CONTAINS depends on the branch family: on a storage branch the second-ranked stem is the seasonal carryover from the month before and the third is the stem that branch stores as the close of its trine, while on a growth branch the second-ranked stem is the one beginning its long-life phase there and the third is the carryover. Some schools name the same three positions by that function rather than by rank, which swaps the second and third labels on the four storage branches, so compare on rank rather than assuming a name."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation this hidden stem holds to the Day Master."}},"required":["stem","role","tenGod"]},"description":"Stems stored inside the branch, principal first. These carry the qi a branch holds without showing it, and they are where a Day Master finds a root."},"naYin":{"type":"string","example":"Earth by the Roadside","description":"Na Yin sound element of the pillar, an older elemental reading assigned to each of the 30 stem-and-branch pairs. The hanzi name sits beside it in naYinChinese."},"naYinChinese":{"type":"string","example":"路旁土","description":"The Na Yin name in hanzi. Identical under every lang."},"naYinElement":{"type":"string","example":"Earth","description":"Element the Na Yin resolves to. Independent of the stem element and often different from it, which is why it is reported separately rather than folded in."}},"required":["position","id","number","stem","branch","tenGod","hiddenStems","naYin","naYinChinese","naYinElement"]},"description":"The four pillars of this person, year first."},"dayMaster":{"type":"object","properties":{"stem":{"type":"string","example":"xin","description":"Day stem identifier for this person."},"chinese":{"type":"string","example":"辛","description":"The Day Master stem in hanzi."},"pinyin":{"type":"string","example":"xīn","description":"Tone-marked pinyin for the Day Master stem."},"element":{"type":"string","example":"Metal","description":"Five-phase element of this Day Master. Always English, whatever the lang parameter says."},"elementLocalized":{"type":"string","example":"Metal","description":"Display copy of the element in the requested language. Absent for English, so an English response is unchanged."},"polarity":{"type":"string","example":"yin","description":"Polarity, yang or yin."},"nature":{"type":"string","example":"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.","description":"What this stem is like as a Day Master."}},"required":["stem","chinese","pinyin","element","polarity","nature"],"description":"The day stem of this person."},"strength":{"type":"string","example":"weak","description":"Day Master strength verdict for this person, so a reader can see which of the two chart carries more capacity. One of very-weak, weak, balanced, strong, very-strong."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."}},"required":["pillars","dayMaster","strength","conventions"],"description":"Resolved chart of the first person."},"personB":{"type":"object","properties":{"pillars":{"type":"array","items":{"type":"object","properties":{"position":{"type":"string","example":"year","description":"Which of the four pillars this is. One of year, month, day, hour. The year pillar reads ancestry and early life, the month career and parents, the day the self and the partner, the hour later life and children."},"id":{"type":"string","example":"geng-wu","description":"Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says."},"number":{"type":"number","example":7,"description":"Position of this pillar in the sexagenary cycle, 1 to 60, where jia-zi is 1. The cycle runs stems and branches together, which is why only 60 of the 120 possible pairings occur."},"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The Heavenly Stem of this pillar."},"branch":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that \"wu\" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position."},"chinese":{"type":"string","example":"午","description":"The branch in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"wǔ","description":"Tone-marked pinyin for the branch. Identical under every lang."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"element":{"type":"string","example":"Fire","description":"Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the branch, yang or yin."}},"required":["id","chinese","pinyin","animal","element","polarity"],"description":"The Earthly Branch of this pillar."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the pillar STEM holds to the Day Master. The day pillar carries day-master instead, because the day stem is the reference point every other position is measured from rather than a relation to itself."},"hiddenStems":{"type":"array","items":{"type":"object","properties":{"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"The stem stored in the branch."},"role":{"type":"string","example":"principal","description":"Rank of this stem inside the branch, by the classical day-count that divides a thirty-day month 18, 9 and 3 days between the stems a branch holds. principal is the first-ranked stem and always matches the branch element; middle is the second-ranked; residual is the third. A branch holds one to three, always returned in rank order. What each rank CONTAINS depends on the branch family: on a storage branch the second-ranked stem is the seasonal carryover from the month before and the third is the stem that branch stores as the close of its trine, while on a growth branch the second-ranked stem is the one beginning its long-life phase there and the third is the carryover. Some schools name the same three positions by that function rather than by rank, which swaps the second and third labels on the four storage branches, so compare on rank rather than assuming a name."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation this hidden stem holds to the Day Master."}},"required":["stem","role","tenGod"]},"description":"Stems stored inside the branch, principal first. These carry the qi a branch holds without showing it, and they are where a Day Master finds a root."},"naYin":{"type":"string","example":"Earth by the Roadside","description":"Na Yin sound element of the pillar, an older elemental reading assigned to each of the 30 stem-and-branch pairs. The hanzi name sits beside it in naYinChinese."},"naYinChinese":{"type":"string","example":"路旁土","description":"The Na Yin name in hanzi. Identical under every lang."},"naYinElement":{"type":"string","example":"Earth","description":"Element the Na Yin resolves to. Independent of the stem element and often different from it, which is why it is reported separately rather than folded in."}},"required":["position","id","number","stem","branch","tenGod","hiddenStems","naYin","naYinChinese","naYinElement"]},"description":"The four pillars of this person, year first."},"dayMaster":{"type":"object","properties":{"stem":{"type":"string","example":"xin","description":"Day stem identifier for this person."},"chinese":{"type":"string","example":"辛","description":"The Day Master stem in hanzi."},"pinyin":{"type":"string","example":"xīn","description":"Tone-marked pinyin for the Day Master stem."},"element":{"type":"string","example":"Metal","description":"Five-phase element of this Day Master. Always English, whatever the lang parameter says."},"elementLocalized":{"type":"string","example":"Metal","description":"Display copy of the element in the requested language. Absent for English, so an English response is unchanged."},"polarity":{"type":"string","example":"yin","description":"Polarity, yang or yin."},"nature":{"type":"string","example":"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.","description":"What this stem is like as a Day Master."}},"required":["stem","chinese","pinyin","element","polarity","nature"],"description":"The day stem of this person."},"strength":{"type":"string","example":"weak","description":"Day Master strength verdict for this person, so a reader can see which of the two chart carries more capacity. One of very-weak, weak, balanced, strong, very-strong."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."}},"required":["pillars","dayMaster","strength","conventions"],"description":"Resolved chart of the second person."},"dayMasterRelation":{"type":"string","example":"peer","description":"How the two Day Masters stand to each other by the five-phase cycle, read from person A. peer means the same element, output means A generates B, wealth means A controls B, influence means B controls A, resource means B generates A. Always English, whatever the lang parameter says."},"interactions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"clash","description":"Kind of interaction. stem-combination and six-combination bind two positions, trine binds three, and clash, harm, punishment and stem-clash break them. Always English, whatever the lang parameter says."},"id":{"type":"string","example":"wu-zi","description":"Identifier of the pairing itself, the member ids joined by hyphens in canonical order."},"chinese":{"type":"string","example":"子午冲","description":"The interaction named in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"zǐ wǔ chōng","description":"Tone-marked pinyin for the interaction. Identical under every lang."},"quality":{"type":"string","example":"challenging","description":"Whether the interaction binds or breaks. harmonious for combinations and trines, challenging for clashes, harms and punishments. Always English, whatever the lang parameter says."},"positions":{"type":"array","items":{"type":"string"},"example":["year","month"],"description":"The chart positions taking part, in the same order as members. On a two-person reading these are prefixed with the subject, for example personA.day."},"members":{"type":"array","items":{"type":"string"},"example":["zi","wu"],"description":"The stem or branch ids taking part, in the same order as positions."},"transformsTo":{"type":"string","example":"Water","description":"Element the formation resolves to. Present on stem combinations and on complete trines, absent on everything else. Branch six combinations deliberately carry none: the classical sources assign transformed elements to the stem pairs and not to these, and one of the six is contested between schools."},"variety":{"type":"string","example":"ungrateful","description":"Class of a punishment, present on punishments only. ungrateful is the tiger, snake and monkey group, bullying the ox, dog and goat group, discourteous the rat and rabbit pair, and self a branch doubled against itself."},"complete":{"type":"boolean","example":false,"description":"Punishments only. True when the third branch of the group is also present in the chart, which is what a complete three-punishment means. False marks the partial case, where only two of the three are in play."},"meaning":{"type":"string","example":"Two Earthly Branches directly opposite on the cycle, six positions apart. A clash moves things: it breaks what was settled, and what it breaks is whatever the two positions govern. Not simply bad, and never quiet.","description":"What this kind of interaction does between the positions it joins."}},"required":["type","id","chinese","pinyin","quality","positions","members","meaning"]},"description":"Every combination, clash, harm and punishment that crosses between the two charts, with each position prefixed by its subject. Only cross-chart pairs are searched: a three-branch formation assembled from two different people is not a formation either chart holds, so trines are not reported here."},"score":{"type":"number","example":50,"description":"Compatibility score from 0 to 100. A RoxyAPI tally over the interactions listed above rather than a figure from any classical text: it starts at a neutral 50, adds for each binding interaction and subtracts for each breaking one. Recompute it yourself from the interactions array if you want a different weighting."},"harmoniousCount":{"type":"number","example":1,"description":"How many of the interactions bind the two charts together."},"challengingCount":{"type":"number","example":2,"description":"How many of the interactions break between them."},"summary":{"type":"string","example":"The two charts form 1 binding interactions and 2 breaking ones across their pillars.","description":"One-paragraph reading of the balance between binding and breaking interactions."}},"required":["personA","personB","dayMasterRelation","interactions","score","harmoniousCount","challengingCount","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bazi/annual-forecast":{"post":{"operationId":"calculateAnnualForecast","tags":["Chinese Astrology"],"summary":"Calculate BaZi annual forecast - Liu Nian yearly pillar API","description":"Read 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."},"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"default":"split-zi","example":"split-zi","description":"Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. \"midnight\" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. \"early-zi\" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. \"split-zi\" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which instant starts the sexagenary YEAR. \"li-chun\" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. \"lunar-new-year\" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"default":"clock","example":"clock","description":"Which clock the HOUR branch is read from. \"clock\" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. \"local-mean\" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. \"solar\" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need \"longitude\" in the request and return 400 without it."},"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Gregorian year to read against the natal chart. The annual pillar for that year is resolved under the same year boundary the request selected, so a li-chun reading and a lunar-new-year reading of the same calendar year can differ."}},"required":["date","time","timezone","year"]}}}},"responses":{"200":{"description":"Annual pillar, its relation to the Day Master, and the natal interactions","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere."},"timezone":{"type":"number","example":8,"description":"Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force on the birth date, so this is the literal number applied and never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":116.4,"description":"Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is \"local-mean\" or \"solar\", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is \"clock\"."}},"required":["date","time","timezone"],"description":"Echo of the birth moment the chart was computed from."},"conventions":{"type":"object","properties":{"dayBoundary":{"type":"string","enum":["split-zi","midnight","early-zi"],"example":"split-zi","description":"Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"example":"li-chun","description":"Year-boundary school actually applied. Echoes the request, or the default when it was omitted."},"hourClock":{"type":"string","enum":["clock","local-mean","solar"],"example":"clock","description":"Hour clock actually applied. Echoes the request, or the default when omitted."}},"required":["dayBoundary","yearBoundary","hourClock"],"description":"The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding."},"year":{"type":"number","example":2026,"description":"Echo of the year requested, which the annual pillar below was resolved for."},"annualPillar":{"type":"object","properties":{"id":{"type":"string","example":"bing-wu","description":"Annual pillar identifier, the stem id and the branch id joined by a hyphen."},"number":{"type":"number","example":43,"description":"Position of the annual pillar in the sexagenary cycle, 1 to 60."},"stem":{"type":"object","properties":{"id":{"type":"string","example":"geng","description":"Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on."},"chinese":{"type":"string","example":"庚","description":"The stem in hanzi. Data rather than display copy, so it is identical under every lang."},"pinyin":{"type":"string","example":"gēng","description":"Tone-marked pinyin for the stem. Identical under every lang."},"element":{"type":"string","example":"Metal","description":"Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Metal","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart."}},"required":["id","chinese","pinyin","element","polarity"],"description":"Heavenly Stem of the year."},"branch":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that \"wu\" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position."},"chinese":{"type":"string","example":"午","description":"The branch in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"wǔ","description":"Tone-marked pinyin for the branch. Identical under every lang."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"element":{"type":"string","example":"Fire","description":"Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Polarity of the branch, yang or yin."}},"required":["id","chinese","pinyin","animal","element","polarity"],"description":"Earthly Branch of the year."},"naYin":{"type":"string","example":"Water of the Sky River","description":"Na Yin sound element of the annual pillar."},"naYinChinese":{"type":"string","example":"天河水","description":"The Na Yin name in hanzi. Identical under every lang."}},"required":["id","number","stem","branch","naYin","naYinChinese"],"description":"The sexagenary pillar of the year being read."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the year branch. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees."},"animalLocalized":{"type":"string","example":"Caballo","description":"Display copy of the animal name in the requested language. Absent for English, so an English response is unchanged."},"tenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the ANNUAL STEM holds to the natal Day Master. This is the single most useful line of an annual reading: it says what the year asks of the chart."},"branchTenGod":{"type":"object","properties":{"id":{"type":"string","example":"rob-wealth","description":"Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says."},"name":{"type":"string","example":"Rob Wealth","description":"Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Roba Riqueza","description":"Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"劫财","description":"The relation in simplified hanzi. Identical under every lang; the traditional forms arrive through the zh-Hant response."},"pinyin":{"type":"string","example":"jié cái","description":"Tone-marked pinyin for the relation. Identical under every lang."},"category":{"type":"string","example":"peer","description":"Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says."},"keynote":{"type":"string","example":"Drive, nerve, and competition for the same ground","description":"One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning."}},"required":["id","name","chinese","pinyin","category","keynote"],"description":"Relation the principal hidden stem of the annual branch holds to the natal Day Master, the slower half of the same reading."},"yearBranchRelation":{"type":"string","example":"same","description":"How the annual branch stands to the NATAL YEAR branch. same is the twelve-yearly return of the birth animal, the year commonly called ben ming nian. clash, harm and punishment are the three breaking relations, and none means the two branches form no structural relation at all. Always English, whatever the lang parameter says."},"benMingNian":{"type":"boolean","example":true,"description":"True when the year returns the birth animal, which is exactly the case where yearBranchRelation is same. Surfaced as its own boolean because it is the one relation most consumers render on its own."},"yearBranchRelationMeaning":{"type":"string","example":"The year returns the birth animal, which happens once every twelve years and is the year known as ben ming nian. Tradition treats the return of the natal branch as a year for care and consolidation rather than for expansion, on the reasoning that the year and the chart occupy the same position and neither can give ground.","description":"What this relation between the annual branch and the natal year branch means."},"interactions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"clash","description":"Kind of interaction. stem-combination and six-combination bind two positions, trine binds three, and clash, harm, punishment and stem-clash break them. Always English, whatever the lang parameter says."},"id":{"type":"string","example":"wu-zi","description":"Identifier of the pairing itself, the member ids joined by hyphens in canonical order."},"chinese":{"type":"string","example":"子午冲","description":"The interaction named in hanzi. Identical under every lang."},"pinyin":{"type":"string","example":"zǐ wǔ chōng","description":"Tone-marked pinyin for the interaction. Identical under every lang."},"quality":{"type":"string","example":"challenging","description":"Whether the interaction binds or breaks. harmonious for combinations and trines, challenging for clashes, harms and punishments. Always English, whatever the lang parameter says."},"positions":{"type":"array","items":{"type":"string"},"example":["year","month"],"description":"The chart positions taking part, in the same order as members. On a two-person reading these are prefixed with the subject, for example personA.day."},"members":{"type":"array","items":{"type":"string"},"example":["zi","wu"],"description":"The stem or branch ids taking part, in the same order as positions."},"transformsTo":{"type":"string","example":"Water","description":"Element the formation resolves to. Present on stem combinations and on complete trines, absent on everything else. Branch six combinations deliberately carry none: the classical sources assign transformed elements to the stem pairs and not to these, and one of the six is contested between schools."},"variety":{"type":"string","example":"ungrateful","description":"Class of a punishment, present on punishments only. ungrateful is the tiger, snake and monkey group, bullying the ox, dog and goat group, discourteous the rat and rabbit pair, and self a branch doubled against itself."},"complete":{"type":"boolean","example":false,"description":"Punishments only. True when the third branch of the group is also present in the chart, which is what a complete three-punishment means. False marks the partial case, where only two of the three are in play."},"meaning":{"type":"string","example":"Two Earthly Branches directly opposite on the cycle, six positions apart. A clash moves things: it breaks what was settled, and what it breaks is whatever the two positions govern. Not simply bad, and never quiet.","description":"What this kind of interaction does between the positions it joins."}},"required":["type","id","chinese","pinyin","quality","positions","members","meaning"]},"description":"Every combination, clash, harm and punishment the annual pillar forms with each of the four natal pillars. Positions are named natal.year through natal.hour against annual."},"summary":{"type":"string","example":"In 2026 the annual pillar is bing-wu, which meets the Day Master as Direct Officer. That relation works like this: Control arriving at the opposite polarity, which makes it structure rather than force: rules, office, standing, and the discipline of answering to something. It steadies a strong chart and confines a weak one, because either way it asks the Day Master to spend.","description":"One-paragraph reading of what the year asks of this chart."}},"required":["birthData","conventions","year","annualPillar","animal","tenGod","branchTenGod","yearBranchRelation","benMingNian","yearBranchRelationMeaning","interactions","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/zodiac/animals":{"get":{"operationId":"listZodiacAnimals","tags":["Chinese Astrology"],"summary":"List the 12 Chinese zodiac animals - Sheng Xiao sign catalogue","description":"Retrieve 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":12,"default":12,"example":12,"description":"Maximum items to return per page. Range: 1-12, default 12."},"required":false,"description":"Maximum items to return per page. Range: 1-12, default 12.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The zodiac animal catalogue.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":12,"description":"Total animals in the cycle. Always 12; the zodiac is a closed set."},"limit":{"type":"number","example":12,"description":"Maximum items returned for this page."},"offset":{"type":"number","example":0,"description":"Number of items skipped before this page."},"animals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Rat","description":"Display name of the animal in English. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier. The twelve branches are zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai, and they run in the same order as the animals. Every animal element, polarity and double-hour is a property of this branch."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."},"traits":{"type":"array","items":{"type":"string"},"example":["quick-witted","resourceful","observant","thrifty","adaptable","sociable"],"description":"Short trait keywords for the sign, lowercase in English. Built for tag clouds, sign cards and compatibility widgets that need a glanceable character sketch rather than a paragraph."}},"required":["id","name","chinese","pinyin","branch","element","polarity","traits"]},"description":"Animals for the current page, in cycle order. Use /zodiac/animals/{id} for the full record with strengths, weaknesses, element variants and relationship partners."}},"required":["total","limit","offset","animals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/zodiac/animals/{id}":{"get":{"operationId":"getZodiacAnimal","tags":["Chinese Astrology"],"summary":"Get one Chinese zodiac animal - Full sign profile with compatibility partners","description":"Retrieve 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["rat","ox","tiger","rabbit","dragon","snake","horse","goat","monkey","rooster","dog","pig"],"example":"rat","description":"Animal id, case-insensitive and punctuation-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. The sheep and the ram are the same animal as the goat and resolve to goat."},"required":true,"description":"Animal id, case-insensitive and punctuation-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. The sheep and the ram are the same animal as the goat and resolve to goat.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Full animal profile.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Rat","description":"Display name of the animal in English. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier. The twelve branches are zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai, and they run in the same order as the animals. Every animal element, polarity and double-hour is a property of this branch."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."},"traits":{"type":"array","items":{"type":"string"},"example":["quick-witted","resourceful","observant","thrifty","adaptable","sociable"],"description":"Short trait keywords for the sign, lowercase in English. Built for tag clouds, sign cards and compatibility widgets that need a glanceable character sketch rather than a paragraph."},"summary":{"type":"string","example":"First of the twelve and the sign the cycle opens on, the Rat is the water branch at the top of the night, when the world is still and the alert are awake.","description":"Character sketch of the sign, drawn from the season, the double-hour and the phase its branch occupies."},"strengths":{"type":"array","items":{"type":"string"},"example":["Reads a room and a situation faster than almost anyone, and turns the reading into a plan"],"description":"What the sign does well, as full sentences rather than keywords."},"weaknesses":{"type":"array","items":{"type":"string"},"example":["Overthinks the entry point and lets a good opening close while the analysis runs"],"description":"Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw."},"compatibilitySummary":{"type":"string","example":"The Rat is easiest with signs that give its speed somewhere to land.","description":"How the sign behaves toward the other eleven in general. For a specific pair, call /zodiac/compatibility/{sign1}/{sign2}."},"hours":{"type":"object","properties":{"start":{"type":"number","example":23,"description":"First hour of the double-hour this branch governs, on a 24-hour local clock. The zi branch starts at 23, so the cycle begins the evening before midnight."},"end":{"type":"number","example":1,"description":"Hour the double-hour ends, exclusive, on a 24-hour local clock. Each branch governs exactly two hours."}},"required":["start","end"],"description":"The two-hour period of the day this animal branch governs. Used for the hour pillar in a Four Pillars chart, which is always read on local time."},"trine":{"type":"object","properties":{"id":{"type":"string","example":"first","description":"Machine id of the trine: first, second, third or fourth. Always English."},"number":{"type":"number","example":1,"description":"Position of the trine in the order the tradition lists them, 1 to 4. Not a ranking."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"申子辰","description":"The three Earthly Branches of the trine in classical notation, in the order the texts give them."},"pinyin":{"type":"string","example":"shēn zǐ chén","description":"Tone-marked pinyin of the three branches."},"members":{"type":"array","items":{"type":"string"},"example":["rat","dragon","monkey"],"description":"The three animal ids in this trine, including the one requested. Members sit four branches apart, so the four trines partition all twelve animals with none shared and none left over."},"theme":{"type":"string","example":"Intelligence put to work. The water trine thinks its way through, and its members trust each other with information before they trust each other with anything else.","description":"What the alliance is traditionally said to produce. The three branches combine into the element above, which is not any one member own phase."}},"required":["id","number","element","chinese","pinyin","members","theme"],"description":"The three-harmony group (San He) this animal belongs to. Every animal belongs to exactly one."},"secretFriend":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Horse","description":"Display name of the related animal in English. Always English; use nameLocalized for display."},"nameLocalized":{"type":"string","example":"Caballo","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"马","description":"Simplified Chinese character for the related animal."},"pinyin":{"type":"string","example":"mǎ","description":"Tone-marked pinyin for the related animal."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Tierra","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["id","name","chinese","pinyin","element"],"description":"The six-harmony partner (Liu He), traditionally called the secret friend because the support it gives arrives unasked. The element is the phase the two branches combine into, which is generally neither animal own phase."},"clashPartner":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Horse","description":"Display name of the related animal in English. Always English; use nameLocalized for display."},"nameLocalized":{"type":"string","example":"Caballo","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"马","description":"Simplified Chinese character for the related animal."},"pinyin":{"type":"string","example":"mǎ","description":"Tone-marked pinyin for the related animal."}},"required":["id","name","chinese","pinyin"],"description":"The clashing animal (Liu Chong): the branch directly opposite, six positions away. The tradition reads this as the most charged pairing in the cycle and the least restful."},"harmPartner":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Horse","description":"Display name of the related animal in English. Always English; use nameLocalized for display."},"nameLocalized":{"type":"string","example":"Caballo","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"马","description":"Simplified Chinese character for the related animal."},"pinyin":{"type":"string","example":"mǎ","description":"Tone-marked pinyin for the related animal."}},"required":["id","name","chinese","pinyin"],"description":"The harming animal (Liu Hai). Treated as less violent than a clash and harder to spot, because it works through accumulation rather than confrontation."},"elementVariants":{"type":"array","items":{"type":"object","properties":{"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Metal","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."},"stem":{"type":"string","example":"geng","description":"Heavenly Stem of the year, as its pinyin identifier. The ten stems are jia, yi, bing, ding, wu, ji, geng, xin, ren, gui."},"pillar":{"type":"string","example":"geng-zi","description":"Sexagenary pillar id for this variant, stem then branch. This pair returns once every sixty years."},"years":{"type":"array","items":{"type":"number"},"example":[1960,2020],"description":"Gregorian years in the published window that carry this variant. Two per variant, sixty years apart."}},"required":["element","polarity","stem","pillar","years"]},"description":"The five phase variants of this sign across the sixty-year cycle, listed over 1924 to 2043. Exactly five, always, because a branch pairs only with the five Heavenly Stems of its own polarity and those five carry one phase each. A year number here names the sexagenary year, not a calendar range: a birth in January or early February may still belong to the previous year, which is what /zodiac/sign resolves."}},"required":["id","name","chinese","pinyin","branch","element","polarity","traits","summary","strengths","weaknesses","compatibilitySummary","hours","trine","secretFriend","clashPartner","harmPartner","elementVariants"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/zodiac/sign":{"post":{"operationId":"calculateZodiacAnimal","tags":["Chinese Astrology"],"summary":"Find the Chinese zodiac animal for a birth date - Sheng Xiao calculator","description":"Resolve 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD format. Only the date is needed: the zodiac animal is a property of the year, so no time, timezone or place changes the answer."},"yearBoundary":{"type":"string","enum":["lunar-new-year","li-chun"],"default":"lunar-new-year","example":"lunar-new-year","description":"Which instant starts the zodiac year. lunar-new-year is the folk rule and the default on this route, because it is the rule people mean when they say what animal they are: the sign turns on Chinese New Year, between late January and late February. li-chun is the classical rule every Four Pillars text uses, turning the year at the solar term Beginning of Spring around 4 February. The two agree for roughly eleven months of every year and disagree for the weeks between them, so a 14 February 2026 birth is a Snake under lunar-new-year and a Horse under li-chun. The BaZi routes default to li-chun instead, because a chart and a folk sign are answering different questions."}},"required":["date"]}}}},"responses":{"200":{"description":"The zodiac animal for this birth date.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"1990-06-15","description":"Echo of the birth date the answer was resolved from."},"animal":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Rat","description":"Display name of the animal in English. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier. The twelve branches are zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai, and they run in the same order as the animals. Every animal element, polarity and double-hour is a property of this branch."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."}},"required":["id","name","chinese","pinyin","branch","element","polarity"],"description":"The zodiac animal for this date. The element on this block is the animal own fixed branch phase, which for a Horse is always Fire. The year phase is the sibling element field below."},"yearPillar":{"type":"object","properties":{"id":{"type":"string","example":"geng-wu","description":"Sexagenary year pillar id, Heavenly Stem then Earthly Branch. Always English pinyin."},"number":{"type":"number","example":7,"description":"Position of this pillar in the sixty-year sexagenary cycle, 1 to 60, where jia-zi is 1."},"stem":{"type":"string","example":"geng","description":"Heavenly Stem of the year, as its pinyin identifier."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the year, as its pinyin identifier. This is the branch the animal names."}},"required":["id","number","stem","branch"],"description":"The sexagenary year the date falls in, under the resolved boundary. Stem and branch together repeat once every sixty years."},"element":{"type":"string","example":"Metal","description":"Five Element phase of the year Heavenly Stem. This is what distinguishes a Metal Horse from a Fire Horse and it changes every two years. It is NOT the animal own fixed phase, which sits on the animal block above. Always English so it stays safe to compare against."},"elementLocalized":{"type":"string","example":"Metall","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."},"interpretation":{"type":"string","example":"Born under the Horse in a Metal year. The sign supplies the temperament and the year phase supplies the register it plays in.","description":"Composed reading of the sign under its year phase. The sign contributes the temperament and the phase contributes the register."},"conventions":{"type":"object","properties":{"yearBoundary":{"type":"string","example":"lunar-new-year","description":"The year boundary actually applied, whether it was requested or defaulted. Store this beside any sign you persist: the same date resolves to two different animals under the two schools, and a sign with no convention recorded cannot be reproduced."}},"required":["yearBoundary"],"description":"The school parameters this answer was computed under, echoed so the result is self-describing."}},"required":["date","animal","yearPillar","element","polarity","interpretation","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/zodiac/compatibility/{sign1}/{sign2}":{"get":{"operationId":"getZodiacCompatibility","tags":["Chinese Astrology"],"summary":"Chinese zodiac compatibility - Trine, six harmony, clash and harm analysis","description":"Score 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["rat","ox","tiger","rabbit","dragon","snake","horse","goat","monkey","rooster","dog","pig"],"example":"rat","description":"First animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"required":true,"description":"First animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig.","name":"sign1","in":"path"},{"schema":{"type":"string","enum":["rat","ox","tiger","rabbit","dragon","snake","horse","goat","monkey","rooster","dog","pig"],"example":"dragon","description":"Second animal id, case-insensitive. The relation is symmetric, so swapping the two returns the same relationship and the same score, with the reading written from the first sign point of view."},"required":true,"description":"Second animal id, case-insensitive. The relation is symmetric, so swapping the two returns the same relationship and the same score, with the reading written from the first sign point of view.","name":"sign2","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Compatibility between the two signs.","content":{"application/json":{"schema":{"type":"object","properties":{"signs":{"type":"object","properties":{"first":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Rat","description":"Display name of the animal in English. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier. The twelve branches are zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai, and they run in the same order as the animals. Every animal element, polarity and double-hour is a property of this branch."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."}},"required":["id","name","chinese","pinyin","branch","element","polarity"]},"second":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Stable machine identifier for the animal. Always English and lowercase, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The twelve ids are rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"name":{"type":"string","example":"Rat","description":"Display name of the animal in English. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier. The twelve branches are zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai, and they run in the same order as the animals. Every animal element, polarity and double-hour is a property of this branch."},"element":{"type":"string","example":"Water","description":"Fixed Five Element (Wu Xing) phase of the animal own branch: Wood, Fire, Earth, Metal or Water. This never changes for a sign. It is NOT the year phase that makes a Metal Rat differ from a Water Rat, which comes from the year Heavenly Stem. Always English so it stays safe to compare against and to key colours off."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch. The twelve branches alternate, starting yang at zi, so the six odd-numbered animals are yang and the six even-numbered are yin."}},"required":["id","name","chinese","pinyin","branch","element","polarity"]}},"required":["first","second"],"description":"The two signs compared, in the order they were requested. Always one object, never an array."},"relationship":{"type":"string","example":"trine","description":"Which of the six classical branch relations the pair stands in. One of secret-friend (Liu He, the six harmonies), trine (San He, the three harmonies), same (both signs share a branch), neutral (no formal relation), harm (Liu Hai) or clash (Liu Chong, branches six apart). Exactly one applies to any pair, because no two of the conditions can hold at once. Always English so it stays safe to switch on."},"relationshipName":{"type":"string","example":"Three Harmonies","description":"Display name of the relation in English. Always English; use relationshipNameLocalized for anything a reader sees."},"relationshipNameLocalized":{"type":"string","example":"Tres Armonias","description":"Branch relation name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"relationshipChinese":{"type":"string","example":"三合","description":"Classical name of the relation in simplified Chinese."},"relationshipPinyin":{"type":"string","example":"sān hé","description":"Tone-marked pinyin of the classical relation name."},"score":{"type":"number","example":85,"description":"Compatibility score out of 100 for this relation. Fixed per relation rather than per pair, because the branch relation is what the tradition actually rates: 92 for a six-harmony pair, 85 for a trine, 65 for two of the same sign, 60 for no relation, 40 for a harm and 30 for a clash."},"verdict":{"type":"string","example":"strong","description":"Coarse band the score falls in: excellent, strong, workable, challenging or difficult. Built for badges and filters that should not hard-code score thresholds."},"sharedElement":{"type":"string","example":"Water","description":"The Five Element phase the two branches combine into. Present only for a trine or a six-harmony pair, which are the two relations that combine; absent otherwise. This is generally neither animal own phase, which is the point of the combination."},"sharedElementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"summary":{"type":"string","example":"The Rat and the Dragon sit in the same Water trine, four branches apart, which is the alliance the tradition rates most reliable over time.","description":"Composed reading of the pair. The branch relation supplies the shape and the two temperaments supply the substance, so the reading is specific to this pair without being authored for it."},"strengths":{"type":"array","items":{"type":"string"},"example":["Reads a room and a situation faster than almost anyone, and turns the reading into a plan"],"description":"What the pair has going for it, drawn from what each sign does well. Favourable relations contribute from both signs; the rest from the first."},"frictions":{"type":"array","items":{"type":"string"},"example":["Overthinks the entry point and lets a good opening close while the analysis runs"],"description":"Where the pair is most likely to grind, drawn from each sign own weaknesses. Difficult relations contribute from both signs; the rest from the first."},"advice":{"type":"string","example":"Do not mistake ease for effort already made. Trines coast, and the pairing rewards whichever side keeps putting work in.","description":"The one thing worth doing differently, specific to this relation rather than generic relationship guidance."}},"required":["signs","relationship","relationshipName","relationshipChinese","relationshipPinyin","score","verdict","summary","strengths","frictions","advice"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/zodiac/{id}/daily":{"get":{"operationId":"getDailyZodiacReading","tags":["Chinese Astrology"],"summary":"Daily Chinese zodiac reading - Day pillar forecast by animal sign","description":"Get 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["rat","ox","tiger","rabbit","dragon","snake","horse","goat","monkey","rooster","dog","pig"],"example":"rat","description":"Animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."},"required":true,"description":"Animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Reading date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current day in the timezone parameter."},"required":false,"description":"Reading date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current day in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which day counts as current when date is omitted. Defaults to UTC, so the reading rolls over at 00:00 UTC each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which day counts as current when date is omitted. Defaults to UTC, so the reading rolls over at 00:00 UTC each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"The daily reading for this sign.","content":{"application/json":{"schema":{"type":"object","properties":{"animal":{"type":"object","properties":{"id":{"type":"string","example":"rat","description":"Machine identifier of the sign this reading is for. Always English and lowercase, so it stays safe to compare against in code."},"name":{"type":"string","example":"Rat","description":"Display name of the sign in English. Always English; use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Rata","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"chinese":{"type":"string","example":"鼠","description":"Simplified Chinese character for the animal."},"pinyin":{"type":"string","example":"shǔ","description":"Tone-marked pinyin for the animal name."},"branch":{"type":"string","example":"zi","description":"Earthly Branch this animal names, as its pinyin identifier."},"element":{"type":"string","example":"Water","description":"Fixed Five Element phase of the sign own branch. Always English so it stays safe to compare against."},"elementLocalized":{"type":"string","example":"Agua","description":"Five Element phase name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"polarity":{"type":"string","example":"yang","description":"Yin or yang polarity of the branch."}},"required":["id","name","chinese","pinyin","branch","element","polarity"],"description":"The sign this reading was requested for."},"date":{"type":"string","example":"2026-04-03","description":"Date of this reading in YYYY-MM-DD format. Echoes the date requested, or the current day in the timezone parameter when it was omitted."},"dayPillar":{"type":"object","properties":{"id":{"type":"string","example":"jia-zi","description":"Sexagenary day pillar id, Heavenly Stem then Earthly Branch. Always English pinyin."},"number":{"type":"number","example":1,"description":"Position of this pillar in the sixty-day sexagenary cycle, 1 to 60, where jia-zi is 1. The day cycle runs unbroken and is independent of the lunar and solar calendars."},"stem":{"type":"string","example":"jia","description":"Heavenly Stem of the day, as its pinyin identifier."},"branch":{"type":"string","example":"zi","description":"Earthly Branch of the day, as its pinyin identifier."},"animal":{"type":"string","example":"rat","description":"The animal the day branch carries, which the tradition calls the day animal. This is what the requested sign is being read against."},"element":{"type":"string","example":"Wood","description":"Five Element phase of the day Heavenly Stem. Together with the sign own phase this sets the energy rating, through the classical generating and controlling cycles."}},"required":["id","number","stem","branch","animal","element"],"description":"The sexagenary pillar of this calendar day, evaluated at the reference meridian for the Chinese calendar."},"relationship":{"type":"string","example":"trine","description":"How the day branch stands to the sign branch. One of secret-friend, trine, same, neutral, harm or clash. Exactly one applies, because no two of the conditions can hold at once. Always English so it stays safe to switch on, and the same vocabulary /zodiac/compatibility returns."},"energyRating":{"type":"number","minimum":1,"maximum":10,"example":9,"description":"Overall energy for this sign on this day, 1 to 10. Derived from the branch relation plus how the day phase treats the sign phase on the generating and controlling cycles, so a favourable relation in a draining phase lands lower than a favourable relation in a supporting one. Built for content widgets and visual indicators."},"overview":{"type":"string","example":"The day sits in the Water trine with the Rat, one of the three-sign alliances the cycle divides into.","description":"What the day does to this sign, from the branch relation and the phase of the day stem."},"love":{"type":"string","example":"An easy day for closeness. The trine removes the translation step, so what you meant is roughly what lands.","description":"Relationship guidance for the day, specific to the branch relation."},"career":{"type":"string","example":"Good for anything collaborative. Trine partners cooperate without negotiating first, so meetings run short.","description":"Work guidance for the day. Clash and harm days carry the traditional cautions about signings and launches."},"advice":{"type":"string","example":"Ask for the thing. Trine days are when a request costs the other person least.","description":"The one thing worth doing differently today, drawn from the relation and from this sign own habitual weak point."},"year":{"type":"object","properties":{"pillar":{"type":"string","example":"bing-wu","description":"Sexagenary year pillar in force on this date, resolved on the lunar new year rule."},"animal":{"type":"string","example":"horse","description":"Animal of the year in force. Always English so it stays safe to compare against."},"animalLocalized":{"type":"string","example":"Caballo","description":"Animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"relationship":{"type":"string","example":"clash","description":"How the year branch stands to the requested sign, from the same six-value vocabulary as the daily relationship. This is the slower background the day sits inside."},"note":{"type":"string","example":"The year branch clashes with the Rat, so the year asks for decisions the sign would rather defer.","description":"One line on the year relationship, or on the Ben Ming Nian year when the year animal matches the sign."}},"required":["pillar","animal","relationship","note"],"description":"The sexagenary year this date falls in, resolved on the LUNAR NEW YEAR rule to match the folk zodiac this route family answers. The Four Pillars routes use the classical Li Chun rule and can name a different year for dates in early February."},"benMingNian":{"type":"boolean","example":false,"description":"True when the year animal is the same as the requested sign, the return of your own branch that comes round every twelve years. The tradition treats a Ben Ming Nian as a year to be deliberate in rather than one to fear, because the sign own qualities run at full strength and that cuts both ways."}},"required":["animal","date","dayPillar","relationship","energyRating","overview","love","career","advice","year","benMingNian"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/calendar/solar-terms/{year}":{"get":{"operationId":"listSolarTerms","tags":["Chinese Astrology"],"summary":"List the 24 solar terms - Jie Qi calendar API with exact instants","description":"Return 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","example":2026,"description":"Solar year, 1900 to 2100. The year opens at Li Chun rather than on 1 January, so its last two terms fall in the following January."},"required":true,"description":"Solar year, 1900 to 2100. The year opens at Li Chun rather than on 1 January, so its last two terms fall in the following January.","name":"year","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The 24 solar terms of the year, in chronological order from Li Chun.","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Echo of the solar year requested."},"referenceOffset":{"type":"number","example":8,"description":"Decimal UTC offset of the reference meridian the local fields are given at. Fixed at 8 for the Chinese calendar."},"total":{"type":"number","example":24,"description":"Number of terms returned, which is always 24."},"terms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"li-chun","description":"Solar term identifier in kebab case pinyin. Always English pinyin, whatever the lang parameter says, because the English names are not standardised and would not be safe to compare against."},"name":{"type":"string","example":"Beginning of Spring","description":"Display name of the term. Several English renderings are in circulation, so treat this as a label and the id as the value."},"chinese":{"type":"string","example":"立春","description":"The term in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"lì chūn","description":"Tone marked pinyin for the characters."},"longitude":{"type":"number","example":315,"description":"Apparent solar longitude in degrees that defines the term. A multiple of 15, and the only thing about a term that is not a convention."},"type":{"type":"string","example":"minor","description":"Either minor or major. The month pillar changes at the twelve MINOR terms, and a lunar month containing no MAJOR term is the leap month."},"instantUtc":{"type":"string","example":"2026-02-03T20:01:54.000Z","description":"The instant the sun reaches the longitude, in UTC."},"localDate":{"type":"string","example":"2026-02-04","description":"Calendar date of the instant at the reference meridian. This is the date printed in an almanac."},"localTime":{"type":"string","example":"04:01:54","description":"Time of day of the instant at the reference meridian."}},"required":["id","name","chinese","pinyin","longitude","type","instantUtc","localDate","localTime"]}}},"required":["year","referenceOffset","total","terms"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/calendar/lunar-date":{"post":{"operationId":"calculateLunarDate","tags":["Chinese Astrology"],"summary":"Convert lunar and Gregorian dates - Chinese lunisolar calendar API","description":"Convert 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Gregorian date to convert to the lunisolar calendar. Send this OR the lunar fields, never both."},"lunarYear":{"type":"integer","minimum":1900,"maximum":2100,"example":1990,"description":"Lunisolar year to convert back to a Gregorian date. Requires lunarMonth and lunarDay."},"lunarMonth":{"type":"integer","minimum":1,"maximum":12,"example":5,"description":"Lunar month, 1 to 12. Requires lunarYear and lunarDay."},"lunarDay":{"type":"integer","minimum":1,"maximum":30,"example":23,"description":"Day of the lunar month, 1 to 30. Requires lunarYear and lunarMonth."},"isLeapMonth":{"type":"boolean","default":false,"example":false,"description":"Set true to address the leap repetition of lunarMonth rather than the first pass. Requesting a leap month a year does not have returns 400."}},"description":"Send a Gregorian date to convert forward, or a lunar year, month and day to convert back."}}}},"responses":{"200":{"description":"The converted date, in both calendars.","content":{"application/json":{"schema":{"type":"object","properties":{"gregorianDate":{"type":"string","example":"1990-06-15","description":"The Gregorian date, echoed when one was sent and computed when the lunar fields were. Echoes the request, or the current UTC date when neither side was supplied."},"lunar":{"type":"object","properties":{"year":{"type":"number","example":1990,"description":"Lunisolar year. It advances on the first day of month 1, not at Li Chun, so it can lag the Gregorian year by up to seven weeks."},"month":{"type":"number","example":5,"description":"Lunar month, 1 to 12. A leap month repeats the number of the month it follows."},"day":{"type":"number","example":23,"description":"Day of the lunar month, 1 to 30. A lunar month never has 31 days."},"isLeapMonth":{"type":"boolean","example":false,"description":"True when this is the leap repetition of the month number rather than the first pass through it."},"monthLength":{"type":"number","example":30,"description":"Days in this lunar month, 29 for a short month or 30 for a long one. It is the interval between two new moons, so it varies month to month."},"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date this lunar day covers, evaluated at the reference meridian."}},"required":["year","month","day","isLeapMonth","monthLength","date"]},"leapMonthOfYear":{"type":"number","example":5,"description":"The month this lunisolar year repeats, when it has thirteen months. Absent in a twelve month year, so a caller can branch on presence rather than on a sentinel."},"referenceOffset":{"type":"number","example":8,"description":"Decimal UTC offset the calendar was evaluated at. Fixed at 8, which is what makes a Chinese lunar date a world constant."}},"required":["gregorianDate","lunar","referenceOffset"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/calendar/day/{date}":{"get":{"operationId":"getAlmanacDay","tags":["Chinese Astrology"],"summary":"Get the almanac for a day - Tong Shu API with day officers and mansions","description":"Return 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"1990-06-15","description":"Gregorian date in YYYY-MM-DD format, evaluated at the reference meridian. Years 1900 to 2100."},"required":true,"description":"Gregorian date in YYYY-MM-DD format, evaluated at the reference meridian. Years 1900 to 2100.","name":"date","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The almanac reading for the day.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date of the day, at the reference meridian."},"lunar":{"type":"object","properties":{"year":{"type":"number","example":1990,"description":"Lunisolar year. It advances on the first day of month 1, not at Li Chun, so it can lag the Gregorian year by up to seven weeks."},"month":{"type":"number","example":5,"description":"Lunar month, 1 to 12. A leap month repeats the number of the month it follows."},"day":{"type":"number","example":23,"description":"Day of the lunar month, 1 to 30. A lunar month never has 31 days."},"isLeapMonth":{"type":"boolean","example":false,"description":"True when this is the leap repetition of the month number rather than the first pass through it."},"monthLength":{"type":"number","example":30,"description":"Days in this lunar month, 29 for a short month or 30 for a long one. It is the interval between two new moons, so it varies month to month."},"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date this lunar day covers, evaluated at the reference meridian."}},"required":["year","month","day","isLeapMonth","monthLength","date"]},"yearPillar":{"type":"object","properties":{"id":{"type":"string","example":"geng-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":7,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"geng","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary year pillar of the day. Attributed by whole days, so the day Li Chun falls on belongs to the new year for its whole length. A BaZi chart built from a birth TIME uses the term instant instead, so a birth in the hours before the term on that same day carries the previous year pillar."},"monthPillar":{"type":"object","properties":{"id":{"type":"string","example":"ren-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":19,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"ren","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary month pillar of the day, and the pillar the day officer is counted from. Attributed by whole days like the year pillar, so the day a minor solar term falls on belongs to the new month even when the term arrives late in the evening. This is what an almanac prints, and it is not the same as the month pillar of a birth moment inside that day."},"dayPillar":{"type":"object","properties":{"id":{"type":"string","example":"xin-hai","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":48,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"xin","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"hai","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"]},"dayOfficer":{"type":"object","properties":{"id":{"type":"string","example":"zhi","description":"Day officer identifier, one of jian chu man ping ding zhi po wei cheng shou kai bi. Always English pinyin, so it stays safe to compare against in code."},"nameLocalized":{"type":"string","example":"Halten","description":"Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged."},"name":{"type":"string","example":"Hold","description":"English display name of the officer."},"chinese":{"type":"string","example":"執","description":"The officer in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"zhí","description":"Tone marked pinyin for the character."},"quality":{"type":"string","example":"inauspicious","description":"Whether the officer falls on the auspicious or the inauspicious side of the coarse yellow and black split. Read favours and avoids for what the day actually rules on."},"meaning":{"type":"string","example":"A day for keeping hold of what is already yours. Rites and safekeeping suit it; letting go of a place, by moving or travelling, works against it.","description":"What the officer means, in the terms a date choice uses it in."}},"required":["id","name","chinese","pinyin","quality","meaning"]},"mansion":{"type":"object","properties":{"number":{"type":"number","example":2,"description":"Mansion number, 1 to 28, counted from the Horn. This is the identifier: three mansions share the pinyin wei and two share bi, so there is no unique pinyin key."},"name":{"type":"string","example":"Neck","description":"English display name of the mansion."},"chinese":{"type":"string","example":"亢","description":"The mansion in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"Kàng","description":"Tone marked pinyin for the character."},"palace":{"type":"string","example":"azure-dragon","description":"One of the four palaces, seven mansions each: azure-dragon, black-tortoise, white-tiger, vermilion-bird. Always English, so it stays safe to compare against in code."},"planet":{"type":"string","example":"Metal","description":"The luminary the mansion belongs to, one of Wood Metal Earth Sun Moon Fire Water. Twenty eight mansions over seven luminaries is four weeks exactly, which is why a mansion always falls on the same weekday."},"animal":{"type":"string","example":"Dragon","description":"Animal emblem of the mansion, the third character of its full Chinese name."}},"required":["number","name","chinese","pinyin","palace","planet","animal"]},"clashAnimal":{"type":"string","example":"snake","description":"The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important."},"clashAnimalLocalized":{"type":"string","example":"Schlange","description":"Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged."},"favours":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."},"avoids":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."}},"required":["date","lunar","yearPillar","monthPillar","dayPillar","dayOfficer","mansion","clashAnimal","favours","avoids"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"The date is outside the supported range.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/calendar/monthly":{"get":{"operationId":"getMonthlyAlmanac","tags":["Chinese Astrology"],"summary":"Get a month of almanac days - Chinese calendar month view API","description":"Return 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"number","example":1990,"description":"Gregorian year, 1900 to 2100. Defaults to the current UTC year when omitted, together with month."},"required":false,"description":"Gregorian year, 1900 to 2100. Defaults to the current UTC year when omitted, together with month.","name":"year","in":"query"},{"schema":{"type":"number","example":6,"description":"Gregorian month, 1 to 12. Defaults to the current UTC month when omitted, together with year."},"required":false,"description":"Gregorian month, 1 to 12. Defaults to the current UTC month when omitted, together with year.","name":"month","in":"query"}],"responses":{"200":{"description":"Every day of the month, with the solar terms it contains.","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":1990,"description":"Year of the month returned. Echoes the year requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":6,"description":"Month returned, 1 to 12. Echoes the month requested, or the current UTC month when it was omitted."},"total":{"type":"number","example":30,"description":"Number of days in the month."},"solarTerms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mang-zhong","description":"Solar term identifier in kebab case pinyin."},"name":{"type":"string","example":"Grain in Ear","description":"Display name of the term."},"type":{"type":"string","example":"minor","description":"Either minor or major. A minor term inside the month is where the month pillar changes and where the day officer repeats for a day."},"date":{"type":"string","example":"1990-06-06","description":"Date the term falls on at the reference meridian."},"instantUtc":{"type":"string","example":"1990-06-05T22:31:00.000Z","description":"The exact instant of the term, in UTC."}},"required":["id","name","type","date","instantUtc"]}},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date of the day, at the reference meridian."},"lunar":{"type":"object","properties":{"year":{"type":"number","example":1990,"description":"Lunisolar year. It advances on the first day of month 1, not at Li Chun, so it can lag the Gregorian year by up to seven weeks."},"month":{"type":"number","example":5,"description":"Lunar month, 1 to 12. A leap month repeats the number of the month it follows."},"day":{"type":"number","example":23,"description":"Day of the lunar month, 1 to 30. A lunar month never has 31 days."},"isLeapMonth":{"type":"boolean","example":false,"description":"True when this is the leap repetition of the month number rather than the first pass through it."},"monthLength":{"type":"number","example":30,"description":"Days in this lunar month, 29 for a short month or 30 for a long one. It is the interval between two new moons, so it varies month to month."},"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date this lunar day covers, evaluated at the reference meridian."}},"required":["year","month","day","isLeapMonth","monthLength","date"]},"yearPillar":{"type":"object","properties":{"id":{"type":"string","example":"geng-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":7,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"geng","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary year pillar of the day. Attributed by whole days, so the day Li Chun falls on belongs to the new year for its whole length. A BaZi chart built from a birth TIME uses the term instant instead, so a birth in the hours before the term on that same day carries the previous year pillar."},"monthPillar":{"type":"object","properties":{"id":{"type":"string","example":"ren-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":19,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"ren","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary month pillar of the day, and the pillar the day officer is counted from. Attributed by whole days like the year pillar, so the day a minor solar term falls on belongs to the new month even when the term arrives late in the evening. This is what an almanac prints, and it is not the same as the month pillar of a birth moment inside that day."},"dayPillar":{"type":"object","properties":{"id":{"type":"string","example":"xin-hai","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":48,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"xin","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"hai","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"]},"dayOfficer":{"type":"object","properties":{"id":{"type":"string","example":"zhi","description":"Day officer identifier, one of jian chu man ping ding zhi po wei cheng shou kai bi. Always English pinyin, so it stays safe to compare against in code."},"nameLocalized":{"type":"string","example":"Halten","description":"Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged."},"name":{"type":"string","example":"Hold","description":"English display name of the officer."},"chinese":{"type":"string","example":"執","description":"The officer in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"zhí","description":"Tone marked pinyin for the character."},"quality":{"type":"string","example":"inauspicious","description":"Whether the officer falls on the auspicious or the inauspicious side of the coarse yellow and black split. Read favours and avoids for what the day actually rules on."},"meaning":{"type":"string","example":"A day for keeping hold of what is already yours. Rites and safekeeping suit it; letting go of a place, by moving or travelling, works against it.","description":"What the officer means, in the terms a date choice uses it in."}},"required":["id","name","chinese","pinyin","quality","meaning"]},"mansion":{"type":"object","properties":{"number":{"type":"number","example":2,"description":"Mansion number, 1 to 28, counted from the Horn. This is the identifier: three mansions share the pinyin wei and two share bi, so there is no unique pinyin key."},"name":{"type":"string","example":"Neck","description":"English display name of the mansion."},"chinese":{"type":"string","example":"亢","description":"The mansion in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"Kàng","description":"Tone marked pinyin for the character."},"palace":{"type":"string","example":"azure-dragon","description":"One of the four palaces, seven mansions each: azure-dragon, black-tortoise, white-tiger, vermilion-bird. Always English, so it stays safe to compare against in code."},"planet":{"type":"string","example":"Metal","description":"The luminary the mansion belongs to, one of Wood Metal Earth Sun Moon Fire Water. Twenty eight mansions over seven luminaries is four weeks exactly, which is why a mansion always falls on the same weekday."},"animal":{"type":"string","example":"Dragon","description":"Animal emblem of the mansion, the third character of its full Chinese name."}},"required":["number","name","chinese","pinyin","palace","planet","animal"]},"clashAnimal":{"type":"string","example":"snake","description":"The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important."},"clashAnimalLocalized":{"type":"string","example":"Schlange","description":"Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged."},"favours":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."},"avoids":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."}},"required":["date","lunar","yearPillar","monthPillar","dayPillar","dayOfficer","mansion","clashAnimal","favours","avoids"]},"description":"Every day of the month, in order."}},"required":["year","month","total","solarTerms","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/calendar/auspicious-days":{"post":{"operationId":"lookupAuspiciousDays","tags":["Chinese Astrology"],"summary":"Find auspicious days - Chinese date selection API for weddings and openings","description":"Search 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"activity":{"type":"string","enum":["wedding","travel","moving-house","opening-business","signing-contracts","construction","groundbreaking","burial","medical-treatment","praying"],"example":"wedding","description":"Activity to choose a date for. One of wedding, travel, moving-house, opening-business, signing-contracts, construction, groundbreaking, burial, medical-treatment, praying. Matching folds case and punctuation, so moving-house and MOVING_HOUSE both resolve."},"startDate":{"type":"string","format":"date","example":"2026-03-01","description":"First date of the range to search, inclusive."},"endDate":{"type":"string","format":"date","example":"2026-04-30","description":"Last date of the range to search, inclusive. The range may not exceed 93 days."},"avoidAnimal":{"type":"string","enum":["rat","ox","tiger","rabbit","dragon","snake","horse","goat","monkey","rooster","dog","pig"],"example":"rat","description":"Zodiac animal to protect. Days that clash with this animal are dropped from the results, which is how a date is chosen around the people attending rather than in the abstract. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig."}},"required":["activity","startDate","endDate"]}}}},"responses":{"200":{"description":"The favoured days inside the range.","content":{"application/json":{"schema":{"type":"object","properties":{"activity":{"type":"string","example":"wedding","description":"Echo of the activity searched for, folded to its canonical identifier."},"activityLabel":{"type":"string","example":"Wedding","description":"Display label for the activity in the requested language."},"startDate":{"type":"string","example":"2026-03-01","description":"Echo of the first date of the range."},"endDate":{"type":"string","example":"2026-04-30","description":"Echo of the last date of the range."},"daysSearched":{"type":"number","example":61,"description":"Number of days in the range, counting both ends."},"avoidAnimal":{"type":"string","example":"rat","description":"Echo of the animal protected. Absent when none was sent, rather than null."},"total":{"type":"number","example":8,"description":"Number of favoured days found. This is the count after the clash filter, not the number of days searched."},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date of the day, at the reference meridian."},"lunar":{"type":"object","properties":{"year":{"type":"number","example":1990,"description":"Lunisolar year. It advances on the first day of month 1, not at Li Chun, so it can lag the Gregorian year by up to seven weeks."},"month":{"type":"number","example":5,"description":"Lunar month, 1 to 12. A leap month repeats the number of the month it follows."},"day":{"type":"number","example":23,"description":"Day of the lunar month, 1 to 30. A lunar month never has 31 days."},"isLeapMonth":{"type":"boolean","example":false,"description":"True when this is the leap repetition of the month number rather than the first pass through it."},"monthLength":{"type":"number","example":30,"description":"Days in this lunar month, 29 for a short month or 30 for a long one. It is the interval between two new moons, so it varies month to month."},"date":{"type":"string","example":"1990-06-15","description":"The Gregorian date this lunar day covers, evaluated at the reference meridian."}},"required":["year","month","day","isLeapMonth","monthLength","date"]},"yearPillar":{"type":"object","properties":{"id":{"type":"string","example":"geng-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":7,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"geng","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary year pillar of the day. Attributed by whole days, so the day Li Chun falls on belongs to the new year for its whole length. A BaZi chart built from a birth TIME uses the term instant instead, so a birth in the hours before the term on that same day carries the previous year pillar."},"monthPillar":{"type":"object","properties":{"id":{"type":"string","example":"ren-wu","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":19,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"ren","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"wu","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"],"description":"Sexagenary month pillar of the day, and the pillar the day officer is counted from. Attributed by whole days like the year pillar, so the day a minor solar term falls on belongs to the new month even when the term arrives late in the evening. This is what an almanac prints, and it is not the same as the month pillar of a birth moment inside that day."},"dayPillar":{"type":"object","properties":{"id":{"type":"string","example":"xin-hai","description":"Pillar identifier as stem-branch, e.g. jia-zi. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code."},"number":{"type":"number","example":48,"description":"Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60."},"stem":{"type":"string","example":"xin","description":"Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui."},"branch":{"type":"string","example":"hai","description":"Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai."},"chinese":{"type":"string","example":"辛亥","description":"The pillar in Chinese characters. A data field, identical in every language."},"naYin":{"type":"string","example":"Metal of Hairpin and Bracelet","description":"Na Yin sound element of the pillar. It is a property of the pair, not of the stem, so it often names a different phase from the stem itself."},"naYinElement":{"type":"string","example":"Metal","description":"Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code."}},"required":["id","number","stem","branch","chinese","naYin","naYinElement"]},"dayOfficer":{"type":"object","properties":{"id":{"type":"string","example":"zhi","description":"Day officer identifier, one of jian chu man ping ding zhi po wei cheng shou kai bi. Always English pinyin, so it stays safe to compare against in code."},"nameLocalized":{"type":"string","example":"Halten","description":"Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged."},"name":{"type":"string","example":"Hold","description":"English display name of the officer."},"chinese":{"type":"string","example":"執","description":"The officer in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"zhí","description":"Tone marked pinyin for the character."},"quality":{"type":"string","example":"inauspicious","description":"Whether the officer falls on the auspicious or the inauspicious side of the coarse yellow and black split. Read favours and avoids for what the day actually rules on."},"meaning":{"type":"string","example":"A day for keeping hold of what is already yours. Rites and safekeeping suit it; letting go of a place, by moving or travelling, works against it.","description":"What the officer means, in the terms a date choice uses it in."}},"required":["id","name","chinese","pinyin","quality","meaning"]},"mansion":{"type":"object","properties":{"number":{"type":"number","example":2,"description":"Mansion number, 1 to 28, counted from the Horn. This is the identifier: three mansions share the pinyin wei and two share bi, so there is no unique pinyin key."},"name":{"type":"string","example":"Neck","description":"English display name of the mansion."},"chinese":{"type":"string","example":"亢","description":"The mansion in Chinese. A data field, identical in every language."},"pinyin":{"type":"string","example":"Kàng","description":"Tone marked pinyin for the character."},"palace":{"type":"string","example":"azure-dragon","description":"One of the four palaces, seven mansions each: azure-dragon, black-tortoise, white-tiger, vermilion-bird. Always English, so it stays safe to compare against in code."},"planet":{"type":"string","example":"Metal","description":"The luminary the mansion belongs to, one of Wood Metal Earth Sun Moon Fire Water. Twenty eight mansions over seven luminaries is four weeks exactly, which is why a mansion always falls on the same weekday."},"animal":{"type":"string","example":"Dragon","description":"Animal emblem of the mansion, the third character of its full Chinese name."}},"required":["number","name","chinese","pinyin","palace","planet","animal"]},"clashAnimal":{"type":"string","example":"snake","description":"The zodiac animal the day clashes with, which is the animal six branches away from the day branch. Anyone born in that animal year traditionally avoids the day for anything important."},"clashAnimalLocalized":{"type":"string","example":"Schlange","description":"Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged."},"favours":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."},"avoids":{"type":"array","items":{"type":"string"},"example":["moving-house","travel"],"description":"Activity identifiers, always English kebab case so they stay safe to compare against in code. Use the /calendar/auspicious-days endpoint to search a date range for one of them."}},"required":["date","lunar","yearPillar","monthPillar","dayPillar","dayOfficer","mansion","clashAnimal","favours","avoids"]},"description":"The favoured days, in date order."}},"required":["activity","activityLabel","startDate","endDate","daysSearched","total","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/elements":{"get":{"operationId":"listFiveElements","tags":["Chinese Astrology"],"summary":"List the five elements - Wu Xing API with generating and controlling cycles","description":"Return 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":5,"default":5,"example":5,"description":"Maximum items to return per page. Range: 1-5, default 5."},"required":false,"description":"Maximum items to return per page. Range: 1-5, default 5.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The five phases with both cycles.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":5,"description":"Total number of phases, which is always five."},"limit":{"type":"number","example":5,"description":"Maximum phases returned in this page."},"offset":{"type":"number","example":0,"description":"Number of phases skipped before this page."},"generatingCycle":{"type":"array","items":{"type":"string"},"example":["Wood","Fire","Earth","Metal","Water"],"description":"The producing ring in order. Each phase generates the next and the last generates the first, so the list wraps."},"controllingCycle":{"type":"array","items":{"type":"string"},"example":["Wood","Earth","Water","Fire","Metal"],"description":"The restraining ring in order. Each phase controls the next and the last controls the first, so this list wraps too. It is the same five phases walked two steps at a time."},"elements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"Wood","description":"Five phase identifier. Always English, whatever the lang parameter says, so it stays safe to compare against in code. The same five values appear on stems, branches, pillars, Na Yin and every feng shui star."},"nameLocalized":{"type":"string","example":"Holz","description":"Display name of the phase in the requested language. Absent when lang is en, so an English response is unchanged."},"chinese":{"type":"string","example":"木","description":"Chinese character for the phase. A data field, identical in every language."},"pinyin":{"type":"string","example":"mù","description":"Tone marked pinyin for the character. A data field, identical in every language."},"season":{"type":"string","example":"Spring","description":"Season the phase governs. Earth governs the transitions rather than a season of its own, and is reported as Late Summer."},"direction":{"type":"string","example":"East","description":"Compass direction of the phase. Earth returns Center, because it sits at the middle of the arrangement rather than on the ring."},"generates":{"type":"string","example":"Fire","description":"The phase this one produces in the generating cycle. Wood feeds Fire, Fire makes Earth, Earth bears Metal, Metal condenses Water, Water grows Wood."},"generatedBy":{"type":"string","example":"Water","description":"The phase that produces this one. The inverse of the generates field."},"controls":{"type":"string","example":"Earth","description":"The phase this one restrains in the controlling cycle. Wood breaks Earth, Earth dams Water, Water quenches Fire, Fire melts Metal, Metal cuts Wood."},"controlledBy":{"type":"string","example":"Metal","description":"The phase that restrains this one. The inverse of the controls field."},"stems":{"type":"array","items":{"type":"string"},"example":["jia","yi"],"description":"The two Heavenly Stems that carry this phase, yang first. Every phase has exactly two, which is why ten stems cover five phases."},"branches":{"type":"array","items":{"type":"string"},"example":["yin","mao"],"description":"The Earthly Branches that carry this phase. Wood, Fire, Metal and Water take two each and Earth takes four, the branches that sit between the seasons."},"meaning":{"type":"string","example":"Growth with a direction to it. Wood pushes outward and upward, plans ahead, and needs room; hemmed in it turns to frustration rather than stopping.","description":"What the phase is and how it behaves, in the terms a reading uses it in. Translated in place."}},"required":["id","chinese","pinyin","season","direction","generates","generatedBy","controls","controlledBy","stems","branches","meaning"]},"description":"The phases for this page, in generating cycle order."}},"required":["total","limit","offset","generatingCycle","controllingCycle","elements"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}},"webhooks":{}}