Chinese Astrology API reference

Chinese zodiac and BaZi astrology API: Four Pillars charts, Chinese zodiac signs and the Chinese lunisolar calendar from any birth moment: year, month, day and hour pillars with hidden stems, Na Yin and Ten God relations, luck pillars, day master strength, and animal compatibility. The school splits that make two calculators disagree are typed parameters rather than hidden defaults, and every chart echoes the conventions it was computed under. Solar terms come back as astronomical instants, lunar dates convert in both directions with leap months placed correctly, and the Tong Shu almanac covers day officers, lunar mansions and date selection. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.

16 endpoints. Product page. Typed SDKs in six languages carry every operation below.

Your API keyKept in this tab only. Without a key, a small daily allowance still answers every request below.

Generate BaZi chart - Four Pillars of Destiny calculator API

POST /api/v2/chinese-astrology/bazi/chart

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	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` required	string (time)	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` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`latitude`	number	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`	number	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`	string enum	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`	string enum	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`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/bazi/chart" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York"}'

Response fields

Field	Type	Description
`birthData` required	object	Echo of the birth moment the chart was computed from.
`birthData.date` required	string (date)	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.
`birthData.time` required	string (time)	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.
`birthData.timezone` required	number	Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth, so this is the literal number applied and never the name. A local time that never happened (the skipped hour of a daylight-saving change) is moved forward past the gap, and date, time and timezone then echo the clock that was running, which the day and hour pillars are read from.
`birthData.latitude`	number	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.
`birthData.longitude`	number	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".
`conventions` required	object	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.
`conventions.dayBoundary` required	string enum	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.
`conventions.yearBoundary` required	string enum	Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
`conventions.hourClock` required	string enum	Hour clock actually applied. Echoes the request, or the default when omitted.
`pillars` required	array of object	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.
`pillars[].position` required	string	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.
`pillars[].id` required	string	Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says.
`pillars[].number` required	number	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.

Show all fieldsShow fewer fields

Field	Type	Description
`pillars[].stem` required	object	The Heavenly Stem of this pillar.
`pillars[].stem.id` required	string	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.
`pillars[].stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`pillars[].stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`pillars[].stem.element` required	string	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.
`pillars[].stem.elementLocalized`	string	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.
`pillars[].stem.polarity` required	string	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.
`pillars[].branch` required	object	The Earthly Branch of this pillar.
`pillars[].branch.id` required	string	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.
`pillars[].branch.chinese` required	string	The branch in hanzi. Identical under every lang.
`pillars[].branch.pinyin` required	string	Tone-marked pinyin for the branch. Identical under every lang.
`pillars[].branch.animal` required	string	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.
`pillars[].branch.animalLocalized`	string	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.
`pillars[].branch.element` required	string	Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`pillars[].branch.elementLocalized`	string	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.
`pillars[].branch.polarity` required	string	Polarity of the branch, yang or yin.
`pillars[].tenGod` required	object	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.
`pillars[].tenGod.id` required	string	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.
`pillars[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`pillars[].tenGod.nameLocalized`	string	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.
`pillars[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`pillars[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`pillars[].tenGod.category` required	string	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.
`pillars[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`pillars[].hiddenStems` required	array of object	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.
`pillars[].hiddenStems[].stem` required	object	The stem stored in the branch.
`pillars[].hiddenStems[].stem.id` required	string	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.
`pillars[].hiddenStems[].stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`pillars[].hiddenStems[].stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`pillars[].hiddenStems[].stem.element` required	string	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.
`pillars[].hiddenStems[].stem.elementLocalized`	string	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.
`pillars[].hiddenStems[].stem.polarity` required	string	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.
`pillars[].hiddenStems[].role` required	string	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.
`pillars[].hiddenStems[].tenGod` required	object	Relation this hidden stem holds to the Day Master.
`pillars[].hiddenStems[].tenGod.id` required	string	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.
`pillars[].hiddenStems[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`pillars[].hiddenStems[].tenGod.nameLocalized`	string	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.
`pillars[].hiddenStems[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`pillars[].hiddenStems[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`pillars[].hiddenStems[].tenGod.category` required	string	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.
`pillars[].hiddenStems[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`pillars[].naYin` required	string	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.
`pillars[].naYinChinese` required	string	The Na Yin name in hanzi. Identical under every lang.
`pillars[].naYinElement` required	string	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. Always English, whatever the lang parameter says. Use naYinElementLocalized for anything a reader sees.
`pillars[].naYinElementLocalized`	string	Na Yin 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.
`dayMaster` required	object	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.
`dayMaster.stem` required	string	Day stem identifier, which IS the Day Master. Always English pinyin, whatever the lang parameter says.
`dayMaster.chinese` required	string	The Day Master stem in hanzi. Identical under every lang.
`dayMaster.pinyin` required	string	Tone-marked pinyin for the Day Master stem.
`dayMaster.element` required	string	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.
`dayMaster.elementLocalized`	string	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.
`dayMaster.polarity` required	string	Polarity of the Day Master, yang or yin.
`dayMaster.nature` required	string	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.
`zodiacAnimal` required	string	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`	string	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` required	array of object	Element balance across the eight chart characters, one entry per phase, with the reading for how represented each one is.
`fiveElements[].element` required	string	Five-phase element. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`fiveElements[].elementLocalized`	string	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.
`fiveElements[].count` required	number	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.
`fiveElements[].level` required	string	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.
`fiveElements[].reading` required	string	What this level of representation means for the chart.
`interactions` required	array of object	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.
`interactions[].type` required	string	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.
`interactions[].id` required	string	Identifier of the pairing itself, the member ids joined by hyphens in canonical order.
`interactions[].chinese` required	string	The interaction named in hanzi. Identical under every lang.
`interactions[].pinyin` required	string	Tone-marked pinyin for the interaction. Identical under every lang.

Example response

{
  "birthData": {
    "date": "1990-06-15",
    "time": "14:30:00",
    "timezone": 8,
    "latitude": 0,
    "longitude": 116.4
  },
  "conventions": {
    "dayBoundary": "split-zi",
    "yearBoundary": "li-chun",
    "hourClock": "clock"
  },
  "pillars": [
    {
      "position": "year",
      "id": "geng-wu",
      "number": 7,
      "stem": {
        "id": "geng",
        "chinese": "庚",
        "pinyin": "gēng",
        "element": "Metal",
        "elementLocalized": "Metal",
        "polarity": "yang"
      },
      "branch": {
        "id": "wu",
        "chinese": "午",
        "pinyin": "wǔ",
        "animal": "horse",
        "animalLocalized": "Caballo",
        "element": "Fire",
        "elementLocalized": "Fuego",
        "polarity": "yang"
      },
      "tenGod": {
        "id": "rob-wealth",
        "name": "Rob Wealth",
        "nameLocalized": "Roba Riqueza",
        "chinese": "劫財",
        "pinyin": "jié cái",
        "category": "peer",
        "keynote": "Drive, nerve, and competition for the same ground"
      },
      "hiddenStems": [
        {
          "stem": {
            "id": "geng",
            "chinese": "庚",
            "pinyin": "gēng",
            "element": "Metal",
            "elementLocalized": "Metal",
            "polarity": "yang"
          },
          "role": "principal",
          "tenGod": {
            "id": "rob-wealth",
            "name": "Rob Wealth",
            "nameLocalized": "Roba Riqueza",
            "chinese": "劫財",
            "pinyin": "jié cái",
            "category": "peer",
            "keynote": "Drive, nerve, and competition for the same ground"
          }
        }
      ],
      "naYin": "Earth by the Roadside",
      "naYinChinese": "路旁土",
      "naYinElement": "Earth",
      "naYinElementLocalized": "Earth"
    }
  ],
  "dayMaster": {
    "stem": "xin",
    "chinese": "辛",
    "pinyin": "xīn",
    "element": "Metal",
    "elementLocalized": "Metal",
    "polarity": "yin",
    "nature": "Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine."
  },
  "zodiacAnimal": "horse",
  "zodiacAnimalLocalized": "Caballo",
  "fiveElements": [
    {
      "element": "Fire",
      "elementLocalized": "Fuego",
      "count": 2,
      "level": "balanced",
      "reading": "Fire is present in proportion. There is enough heat to be seen and to convince, without the chart burning through what it builds."
    }
  ],
  "interactions": [
    {
      "type": "clash",
      "id": "wu-zi",
      "chinese": "子午沖",
      "pinyin": "zǐ wǔ chōng",
      "quality": "challenging",
      "positions": [
        "year",
        "month"
      ],
      "members": [
        "zi",
        "wu"
      ],
      "transformsTo": "Water",
      "variety": "ungrateful",
      "complete": false,
      "meaning": "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."
    }
  ],
  "summary": "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."
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

Calculate luck pillars - BaZi Da Yun ten-year cycle API

POST /api/v2/chinese-astrology/bazi/luck-pillars

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	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` required	string (time)	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` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`latitude`	number	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`	number	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`	string enum	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`	string enum	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`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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` required	string enum	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`	integer	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`	integer	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`	integer	How many consecutive years the annual overlay covers, 1 to 20. Ignored unless annualFromYear is present.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/bazi/luck-pillars" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York","gender":"male"}'

Response fields

Field	Type	Description
`birthData` required	object	Echo of the birth moment the chart was computed from.
`birthData.date` required	string (date)	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.
`birthData.time` required	string (time)	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.
`birthData.timezone` required	number	Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth, so this is the literal number applied and never the name. A local time that never happened (the skipped hour of a daylight-saving change) is moved forward past the gap, and date, time and timezone then echo the clock that was running, which the day and hour pillars are read from.
`birthData.latitude`	number	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.
`birthData.longitude`	number	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".
`conventions` required	object	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.
`conventions.dayBoundary` required	string enum	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.
`conventions.yearBoundary` required	string enum	Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
`conventions.hourClock` required	string enum	Hour clock actually applied. Echoes the request, or the default when omitted.
`gender` required	string	Echo of the sex sent, which is what selected the direction below.
`direction` required	string	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` required	number	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` required	number	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.

Show all fieldsShow fewer fields

Field	Type	Description
`daysToTerm` required	number	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` required	string	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.
`boundaryTermName` required	string	Display name of that same term, in the requested language. Always present, and English when lang is en. Several English renderings of a term are in circulation, so treat this as the label and boundaryTerm as the value.
`luckPillars` required	array of object	The ten-year periods in order, each with the relation its stem holds to the natal Day Master.
`luckPillars[].index` required	number	Position in the sequence, starting at 1 for the first ten-year period.
`luckPillars[].id` required	string	Pillar identifier, the stem id and the branch id joined by a hyphen.
`luckPillars[].number` required	number	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.
`luckPillars[].stem` required	object	The Heavenly Stem of this luck pillar, with its element and polarity.
`luckPillars[].stem.id` required	string	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.
`luckPillars[].stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`luckPillars[].stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`luckPillars[].stem.element` required	string	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.
`luckPillars[].stem.elementLocalized`	string	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.
`luckPillars[].stem.polarity` required	string	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.
`luckPillars[].branch` required	object	The Earthly Branch of this luck pillar, with its animal, element and polarity.
`luckPillars[].branch.id` required	string	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.
`luckPillars[].branch.chinese` required	string	The branch in hanzi. Identical under every lang.
`luckPillars[].branch.pinyin` required	string	Tone-marked pinyin for the branch. Identical under every lang.
`luckPillars[].branch.animal` required	string	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.
`luckPillars[].branch.animalLocalized`	string	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.
`luckPillars[].branch.element` required	string	Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`luckPillars[].branch.elementLocalized`	string	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.
`luckPillars[].branch.polarity` required	string	Polarity of the branch, yang or yin.
`luckPillars[].tenGod` required	object	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.
`luckPillars[].tenGod.id` required	string	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.
`luckPillars[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`luckPillars[].tenGod.nameLocalized`	string	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.
`luckPillars[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`luckPillars[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`luckPillars[].tenGod.category` required	string	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.
`luckPillars[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`luckPillars[].startAge` required	number	Age in whole years at which this ten-year period begins.
`luckPillars[].endAge` required	number	Age in whole years at which this period ends and the next one begins.
`luckPillars[].startYear` required	number	Gregorian year this period begins, the birth year plus startAge.
`luckPillars[].endYear` required	number	Gregorian year this period ends.
`annualPillars`	array of object	Year-by-year overlay, present only when annualFromYear was sent. Each year names the luck pillar it falls inside.
`annualPillars[].year` required	number	Gregorian year.
`annualPillars[].id` required	string	Annual pillar identifier for that year, under the year boundary applied.
`annualPillars[].number` required	number	Position of the annual pillar in the sexagenary cycle, 1 to 60.
`annualPillars[].tenGod` required	object	Relation the annual pillar STEM holds to the natal Day Master.
`annualPillars[].tenGod.id` required	string	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.
`annualPillars[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`annualPillars[].tenGod.nameLocalized`	string	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.
`annualPillars[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`annualPillars[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`annualPillars[].tenGod.category` required	string	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.
`annualPillars[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`annualPillars[].luckPillarIndex` required	number	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.
`summary` required	string	One-paragraph reading of the sequence direction and its start.

Example response

{
  "birthData": {
    "date": "1990-06-15",
    "time": "14:30:00",
    "timezone": 8,
    "latitude": 0,
    "longitude": 116.4
  },
  "conventions": {
    "dayBoundary": "split-zi",
    "yearBoundary": "li-chun",
    "hourClock": "clock"
  },
  "gender": "male",
  "direction": "forward",
  "startAge": 7,
  "startAgeMonths": 2,
  "daysToTerm": 21.4,
  "boundaryTerm": "xiao-shu",
  "boundaryTermName": "Minor Heat",
  "luckPillars": [
    {
      "index": 1,
      "id": "gui-wei",
      "number": 20,
      "stem": {
        "id": "geng",
        "chinese": "庚",
        "pinyin": "gēng",
        "element": "Metal",
        "elementLocalized": "Metal",
        "polarity": "yang"
      },
      "branch": {
        "id": "wu",
        "chinese": "午",
        "pinyin": "wǔ",
        "animal": "horse",
        "animalLocalized": "Caballo",
        "element": "Fire",
        "elementLocalized": "Fuego",
        "polarity": "yang"
      },
      "tenGod": {
        "id": "rob-wealth",
        "name": "Rob Wealth",
        "nameLocalized": "Roba Riqueza",
        "chinese": "劫財",
        "pinyin": "jié cái",
        "category": "peer",
        "keynote": "Drive, nerve, and competition for the same ground"
      },
      "startAge": 7,
      "endAge": 17,
      "startYear": 1997,
      "endYear": 2007
    }
  ],
  "annualPillars": [
    {
      "year": 2026,
      "id": "bing-wu",
      "number": 43,
      "tenGod": {
        "id": "rob-wealth",
        "name": "Rob Wealth",
        "nameLocalized": "Roba Riqueza",
        "chinese": "劫財",
        "pinyin": "jié cái",
        "category": "peer",
        "keynote": "Drive, nerve, and competition for the same ground"
      },
      "luckPillarIndex": 4
    }
  ],
  "summary": "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."
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

Calculate Day Master strength - BaZi favorable element API

POST /api/v2/chinese-astrology/bazi/day-master

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 and the branches outside the month 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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	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` required	string (time)	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` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`latitude`	number	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`	number	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`	string enum	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`	string enum	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`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/bazi/day-master" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York"}'

Response fields

Field	Type	Description
`birthData` required	object	Echo of the birth moment the chart was computed from.
`birthData.date` required	string (date)	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.
`birthData.time` required	string (time)	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.
`birthData.timezone` required	number	Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth, so this is the literal number applied and never the name. A local time that never happened (the skipped hour of a daylight-saving change) is moved forward past the gap, and date, time and timezone then echo the clock that was running, which the day and hour pillars are read from.
`birthData.latitude`	number	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.
`birthData.longitude`	number	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".
`conventions` required	object	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.
`conventions.dayBoundary` required	string enum	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.
`conventions.yearBoundary` required	string enum	Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
`conventions.hourClock` required	string enum	Hour clock actually applied. Echoes the request, or the default when omitted.
`dayMaster` required	object	The day stem whose strength is being assessed.
`dayMaster.stem` required	string	Day stem identifier. Always English pinyin, whatever the lang parameter says.
`dayMaster.chinese` required	string	The Day Master stem in hanzi.
`dayMaster.pinyin` required	string	Tone-marked pinyin for the Day Master stem.

Show all fieldsShow fewer fields

Field	Type	Description
`dayMaster.element` required	string	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.
`dayMaster.elementLocalized`	string	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.
`dayMaster.polarity` required	string	Polarity of the Day Master, yang or yin.
`dayMaster.nature` required	string	What this particular stem is like as a Day Master.
`verdict` required	string	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` required	number	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` required	string	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` required	string	The seasonal state in hanzi. Identical under every lang.
`seasonalStateMeaning` required	string	What this seasonal state means for the chart.
`rootCount` required	number	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` required	array of object	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.
`factors[].id` required	string	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, and the principal stems of the three branches outside the month, help or spend it. Always English, whatever the lang parameter says.
`factors[].name` required	string	Display name of the factor. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`factors[].chinese` required	string	The factor named in hanzi. Identical under every lang.
`factors[].pinyin` required	string	Tone-marked pinyin for the factor. Identical under every lang.
`factors[].contribution` required	number	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.
`factors[].detail` required	string	What the factor actually found in this chart, in one clause.
`favorableElements` required	array of string	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` required	array of string	Elements that burden this chart, the complement of favorableElements. Also empty when the verdict is balanced.
`fiveElements` required	array of object	Element headcount across the eight characters, the plain distribution behind the weighted verdict.
`fiveElements[].element` required	string	Five-phase element. Always English, whatever the lang parameter says.
`fiveElements[].elementLocalized`	string	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.
`fiveElements[].count` required	number	How many of the eight chart characters carry this element, four stems and four branch elements at one point each.
`fiveElements[].level` required	string	How represented the element is. deficient is absent, excess is three or more, balanced is one or two.
`fiveElements[].reading` required	string	What this level of representation means for the chart.
`summary` required	string	One-paragraph reading composed from the verdict, the seasonal state, and the rooting finding.

Example response

{
  "birthData": {
    "date": "1990-06-15",
    "time": "14:30:00",
    "timezone": 8,
    "latitude": 0,
    "longitude": 116.4
  },
  "conventions": {
    "dayBoundary": "split-zi",
    "yearBoundary": "li-chun",
    "hourClock": "clock"
  },
  "dayMaster": {
    "stem": "xin",
    "chinese": "辛",
    "pinyin": "xīn",
    "element": "Metal",
    "elementLocalized": "Metal",
    "polarity": "yin",
    "nature": "Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine."
  },
  "verdict": "weak",
  "score": -2.2,
  "seasonalState": "dead",
  "seasonalStateChinese": "死",
  "seasonalStateMeaning": "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.",
  "rootCount": 0,
  "factors": [
    {
      "id": "month-command",
      "name": "Month command",
      "chinese": "得令",
      "pinyin": "dé lìng",
      "contribution": -2,
      "detail": "Metal is dead in a Fire month"
    }
  ],
  "favorableElements": [
    "Metal",
    "Earth"
  ],
  "unfavorableElements": [
    "Water",
    "Wood"
  ],
  "fiveElements": [
    {
      "element": "Fire",
      "elementLocalized": "Fuego",
      "count": 2,
      "level": "balanced",
      "reading": "Fire is present in proportion. There is enough heat to be seen and to convince, without the chart burning through what it builds."
    }
  ],
  "summary": "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."
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

Calculate BaZi compatibility - Four Pillars matchmaking API

POST /api/v2/chinese-astrology/bazi/compatibility

Compare two BaZi charts pillar by pillar, the Chinese astrology reading of how two people match. 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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`personA` required	object	Birth moment of the first person. Each subject carries its own school switches, so two charts built under different conventions can still be compared.
`personA.date` required	string (date)	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.
`personA.time` required	string (time)	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.
`personA.timezone` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`personA.latitude`	number	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.
`personA.longitude`	number	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".
`personA.dayBoundary`	string enum	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.
`personA.yearBoundary`	string enum	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.
`personA.hourClock`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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.
`personB` required	object	Birth moment of the second person.
`personB.date` required	string (date)	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.
`personB.time` required	string (time)	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.
`personB.timezone` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`personB.latitude`	number	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.

Show all fieldsShow fewer fields

Field	Type	Description
`personB.longitude`	number	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".
`personB.dayBoundary`	string enum	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.
`personB.yearBoundary`	string enum	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.
`personB.hourClock`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/bazi/compatibility" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personA":{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York","latitude":0,"longitude":116.4,"dayBoundary":"split-zi","yearBoundary":"li-chun","hourClock":"clock"},"personB":{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York","latitude":0,"longitude":116.4,"dayBoundary":"split-zi","yearBoundary":"li-chun","hourClock":"clock"}}'

Response fields

Field	Type	Description
`personA` required	object	Resolved chart of the first person.
`personA.pillars` required	array of object	The four pillars of this person, year first.
`personA.pillars[].position` required	string	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.
`personA.pillars[].id` required	string	Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says.
`personA.pillars[].number` required	number	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.
`personA.pillars[].stem` required	object	The Heavenly Stem of this pillar.
`personA.pillars[].stem.id` required	string	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.
`personA.pillars[].stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`personA.pillars[].stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`personA.pillars[].stem.element` required	string	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.
`personA.pillars[].stem.elementLocalized`	string	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.
`personA.pillars[].stem.polarity` required	string	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.
`personA.pillars[].branch` required	object	The Earthly Branch of this pillar.
`personA.pillars[].branch.id` required	string	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.

Show all fieldsShow fewer fields

Field	Type	Description
`personA.pillars[].branch.chinese` required	string	The branch in hanzi. Identical under every lang.
`personA.pillars[].branch.pinyin` required	string	Tone-marked pinyin for the branch. Identical under every lang.
`personA.pillars[].branch.animal` required	string	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.
`personA.pillars[].branch.animalLocalized`	string	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.
`personA.pillars[].branch.element` required	string	Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`personA.pillars[].branch.elementLocalized`	string	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.
`personA.pillars[].branch.polarity` required	string	Polarity of the branch, yang or yin.
`personA.pillars[].tenGod` required	object	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.
`personA.pillars[].tenGod.id` required	string	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.
`personA.pillars[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`personA.pillars[].tenGod.nameLocalized`	string	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.
`personA.pillars[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`personA.pillars[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`personA.pillars[].tenGod.category` required	string	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.
`personA.pillars[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`personA.pillars[].hiddenStems` required	array of object	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.
`personA.pillars[].hiddenStems[].stem` required	object	The stem stored in the branch.
`personA.pillars[].hiddenStems[].role` required	string	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.
`personA.pillars[].hiddenStems[].tenGod` required	object	Relation this hidden stem holds to the Day Master.
`personA.pillars[].naYin` required	string	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.
`personA.pillars[].naYinChinese` required	string	The Na Yin name in hanzi. Identical under every lang.
`personA.pillars[].naYinElement` required	string	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. Always English, whatever the lang parameter says. Use naYinElementLocalized for anything a reader sees.
`personA.pillars[].naYinElementLocalized`	string	Na Yin 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.
`personA.dayMaster` required	object	The day stem of this person.
`personA.dayMaster.stem` required	string	Day stem identifier for this person.
`personA.dayMaster.chinese` required	string	The Day Master stem in hanzi.
`personA.dayMaster.pinyin` required	string	Tone-marked pinyin for the Day Master stem.
`personA.dayMaster.element` required	string	Five-phase element of this Day Master. Always English, whatever the lang parameter says.
`personA.dayMaster.elementLocalized`	string	Display copy of the element in the requested language. Absent for English, so an English response is unchanged.
`personA.dayMaster.polarity` required	string	Polarity, yang or yin.
`personA.dayMaster.nature` required	string	What this stem is like as a Day Master.
`personA.strength` required	string	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.
`personA.conventions` required	object	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.
`personA.conventions.dayBoundary` required	string enum	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.
`personA.conventions.yearBoundary` required	string enum	Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
`personA.conventions.hourClock` required	string enum	Hour clock actually applied. Echoes the request, or the default when omitted.
`personB` required	object	Resolved chart of the second person.
`personB.pillars` required	array of object	The four pillars of this person, year first.
`personB.pillars[].position` required	string	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.
`personB.pillars[].id` required	string	Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says.
`personB.pillars[].number` required	number	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.
`personB.pillars[].stem` required	object	The Heavenly Stem of this pillar.
`personB.pillars[].stem.id` required	string	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.
`personB.pillars[].stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`personB.pillars[].stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`personB.pillars[].stem.element` required	string	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.
`personB.pillars[].stem.elementLocalized`	string	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.
`personB.pillars[].stem.polarity` required	string	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.
`personB.pillars[].branch` required	object	The Earthly Branch of this pillar.
`personB.pillars[].branch.id` required	string	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.
`personB.pillars[].branch.chinese` required	string	The branch in hanzi. Identical under every lang.
`personB.pillars[].branch.pinyin` required	string	Tone-marked pinyin for the branch. Identical under every lang.
`personB.pillars[].branch.animal` required	string	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.
`personB.pillars[].branch.animalLocalized`	string	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.
`personB.pillars[].branch.element` required	string	Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`personB.pillars[].branch.elementLocalized`	string	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.
`personB.pillars[].branch.polarity` required	string	Polarity of the branch, yang or yin.
`personB.pillars[].tenGod` required	object	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.
`personB.pillars[].tenGod.id` required	string	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.
`personB.pillars[].tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`personB.pillars[].tenGod.nameLocalized`	string	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.
`personB.pillars[].tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`personB.pillars[].tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`personB.pillars[].tenGod.category` required	string	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.
`personB.pillars[].tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`personB.pillars[].hiddenStems` required	array of object	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.

Example response

{
  "personA": {
    "pillars": [
      {
        "position": "year",
        "id": "geng-wu",
        "number": 7,
        "stem": {
          "id": "geng",
          "chinese": "庚",
          "pinyin": "gēng",
          "element": "Metal",
          "elementLocalized": "Metal",
          "polarity": "yang"
        },
        "branch": {
          "id": "wu",
          "chinese": "午",
          "pinyin": "wǔ",
          "animal": "horse",
          "animalLocalized": "Caballo",
          "element": "Fire",
          "elementLocalized": "Fuego",
          "polarity": "yang"
        },
        "tenGod": {
          "id": "rob-wealth",
          "name": "Rob Wealth",
          "nameLocalized": "Roba Riqueza",
          "chinese": "劫財",
          "pinyin": "jié cái",
          "category": "peer",
          "keynote": "Drive, nerve, and competition for the same ground"
        },
        "hiddenStems": [
          {
            "stem": {},
            "role": "principal",
            "tenGod": {}
          }
        ],
        "naYin": "Earth by the Roadside",
        "naYinChinese": "路旁土",
        "naYinElement": "Earth",
        "naYinElementLocalized": "Earth"
      }
    ],
    "dayMaster": {
      "stem": "xin",
      "chinese": "辛",
      "pinyin": "xīn",
      "element": "Metal",
      "elementLocalized": "Metal",
      "polarity": "yin",
      "nature": "Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine."
    },
    "strength": "weak",
    "conventions": {
      "dayBoundary": "split-zi",
      "yearBoundary": "li-chun",
      "hourClock": "clock"
    }
  },
  "personB": {
    "pillars": [
      {
        "position": "year",
        "id": "geng-wu",
        "number": 7,
        "stem": {
          "id": "geng",
          "chinese": "庚",
          "pinyin": "gēng",
          "element": "Metal",
          "elementLocalized": "Metal",
          "polarity": "yang"
        },
        "branch": {
          "id": "wu",
          "chinese": "午",
          "pinyin": "wǔ",
          "animal": "horse",
          "animalLocalized": "Caballo",
          "element": "Fire",
          "elementLocalized": "Fuego",
          "polarity": "yang"
        },
        "tenGod": {
          "id": "rob-wealth",
          "name": "Rob Wealth",
          "nameLocalized": "Roba Riqueza",
          "chinese": "劫財",
          "pinyin": "jié cái",
          "category": "peer",
          "keynote": "Drive, nerve, and competition for the same ground"
        },
        "hiddenStems": [
          {
            "stem": {},
            "role": "principal",
            "tenGod": {}
          }
        ],
        "naYin": "Earth by the Roadside",
        "naYinChinese": "路旁土",
        "naYinElement": "Earth",
        "naYinElementLocalized": "Earth"
      }
    ],
    "dayMaster": {
      "stem": "xin",
      "chinese": "辛",
      "pinyin": "xīn",
      "element": "Metal",
      "elementLocalized": "Metal",
      "polarity": "yin",
      "nature": "Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which would only melt what took so long to refine."
    },
    "strength": "weak",
    "conventions": {
      "dayBoundary": "split-zi",
      "yearBoundary": "li-chun",
      "hourClock": "clock"
    }
  },
  "dayMasterRelation": "peer",
  "interactions": [
    {
      "type": "clash",
      "id": "wu-zi",
      "chinese": "子午沖",
      "pinyin": "zǐ wǔ chōng",
      "quality": "challenging",
      "positions": [
        "year",
        "month"
      ],
      "members": [
        "zi",
        "wu"
      ],
      "transformsTo": "Water",
      "variety": "ungrateful",
      "complete": false,
      "meaning": "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."
    }
  ],
  "score": 50,
  "harmoniousCount": 1,
  "challengingCount": 2,
  "summary": "The two charts form 1 binding interactions and 2 breaking ones across their pillars."
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

Calculate BaZi annual forecast - Liu Nian yearly pillar API

POST /api/v2/chinese-astrology/bazi/annual-forecast

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	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` required	string (time)	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` required	number or string	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 offset in force at the birth date and time, historical daylight-saving rules included, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state at that moment. On a transition day a time in the repeated hour is read as its first occurrence and a time in the skipped hour is moved forward past the gap. Invalid timezones return 400 with a validation error.
`latitude`	number	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`	number	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`	string enum	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`	string enum	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`	string enum	Which clock the day boundary and the hour branch are read from, so a correction that carries a birth across midnight moves the day pillar with the hour. "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` required	integer	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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/bazi/annual-forecast" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30:00","timezone":"America/New_York","year":2026}'

Response fields

Field	Type	Description
`birthData` required	object	Echo of the birth moment the chart was computed from.
`birthData.date` required	string (date)	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.
`birthData.time` required	string (time)	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.
`birthData.timezone` required	number	Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force at the birth, so this is the literal number applied and never the name. A local time that never happened (the skipped hour of a daylight-saving change) is moved forward past the gap, and date, time and timezone then echo the clock that was running, which the day and hour pillars are read from.
`birthData.latitude`	number	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.
`birthData.longitude`	number	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".
`conventions` required	object	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.
`conventions.dayBoundary` required	string enum	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.
`conventions.yearBoundary` required	string enum	Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
`conventions.hourClock` required	string enum	Hour clock actually applied. Echoes the request, or the default when omitted.
`year` required	number	Echo of the year requested, which the annual pillar below was resolved for.
`annualPillar` required	object	The sexagenary pillar of the year being read.
`annualPillar.id` required	string	Annual pillar identifier, the stem id and the branch id joined by a hyphen.
`annualPillar.number` required	number	Position of the annual pillar in the sexagenary cycle, 1 to 60.

Show all fieldsShow fewer fields

Field	Type	Description
`annualPillar.stem` required	object	Heavenly Stem of the year.
`annualPillar.stem.id` required	string	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.
`annualPillar.stem.chinese` required	string	The stem in hanzi. Data rather than display copy, so it is identical under every lang.
`annualPillar.stem.pinyin` required	string	Tone-marked pinyin for the stem. Identical under every lang.
`annualPillar.stem.element` required	string	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.
`annualPillar.stem.elementLocalized`	string	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.
`annualPillar.stem.polarity` required	string	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.
`annualPillar.branch` required	object	Earthly Branch of the year.
`annualPillar.branch.id` required	string	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.
`annualPillar.branch.chinese` required	string	The branch in hanzi. Identical under every lang.
`annualPillar.branch.pinyin` required	string	Tone-marked pinyin for the branch. Identical under every lang.
`annualPillar.branch.animal` required	string	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.
`annualPillar.branch.animalLocalized`	string	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.
`annualPillar.branch.element` required	string	Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
`annualPillar.branch.elementLocalized`	string	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.
`annualPillar.branch.polarity` required	string	Polarity of the branch, yang or yin.
`annualPillar.naYin` required	string	Na Yin sound element of the annual pillar.
`annualPillar.naYinChinese` required	string	The Na Yin name in hanzi. Identical under every lang.
`animal` required	string	Zodiac animal of the year branch. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees.
`animalLocalized`	string	Display copy of the animal name in the requested language. Absent for English, so an English response is unchanged.
`tenGod` required	object	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.
`tenGod.id` required	string	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.
`tenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`tenGod.nameLocalized`	string	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.
`tenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`tenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`tenGod.category` required	string	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.
`tenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`branchTenGod` required	object	Relation the principal hidden stem of the annual branch holds to the natal Day Master, the slower half of the same reading.
`branchTenGod.id` required	string	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.
`branchTenGod.name` required	string	Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
`branchTenGod.nameLocalized`	string	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.
`branchTenGod.chinese` required	string	The relation in traditional hanzi. Identical under every lang.
`branchTenGod.pinyin` required	string	Tone-marked pinyin for the relation. Identical under every lang.
`branchTenGod.category` required	string	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.
`branchTenGod.keynote` required	string	One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
`yearBranchRelation` required	string	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` required	boolean	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` required	string	What this relation between the annual branch and the natal year branch means.
`interactions` required	array of object	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.
`interactions[].type` required	string	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.
`interactions[].id` required	string	Identifier of the pairing itself, the member ids joined by hyphens in canonical order.
`interactions[].chinese` required	string	The interaction named in hanzi. Identical under every lang.
`interactions[].pinyin` required	string	Tone-marked pinyin for the interaction. Identical under every lang.
`interactions[].quality` required	string	Whether the interaction binds or breaks. harmonious for combinations and trines, challenging for clashes, harms and punishments. Always English, whatever the lang parameter says.
`interactions[].positions` required	array of string	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.
`interactions[].members` required	array of string	The stem or branch ids taking part, in the same order as positions.
`interactions[].transformsTo`	string	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.
`interactions[].variety`	string	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.
`interactions[].complete`	boolean	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.
`interactions[].meaning` required	string	What this kind of interaction does between the positions it joins.
`summary` required	string	One-paragraph reading of what the year asks of this chart.

Example response

{
  "birthData": {
    "date": "1990-06-15",
    "time": "14:30:00",
    "timezone": 8,
    "latitude": 0,
    "longitude": 116.4
  },
  "conventions": {
    "dayBoundary": "split-zi",
    "yearBoundary": "li-chun",
    "hourClock": "clock"
  },
  "year": 2026,
  "annualPillar": {
    "id": "bing-wu",
    "number": 43,
    "stem": {
      "id": "geng",
      "chinese": "庚",
      "pinyin": "gēng",
      "element": "Metal",
      "elementLocalized": "Metal",
      "polarity": "yang"
    },
    "branch": {
      "id": "wu",
      "chinese": "午",
      "pinyin": "wǔ",
      "animal": "horse",
      "animalLocalized": "Caballo",
      "element": "Fire",
      "elementLocalized": "Fuego",
      "polarity": "yang"
    },
    "naYin": "Water of the Sky River",
    "naYinChinese": "天河水"
  },
  "animal": "horse",
  "animalLocalized": "Caballo",
  "tenGod": {
    "id": "rob-wealth",
    "name": "Rob Wealth",
    "nameLocalized": "Roba Riqueza",
    "chinese": "劫財",
    "pinyin": "jié cái",
    "category": "peer",
    "keynote": "Drive, nerve, and competition for the same ground"
  },
  "branchTenGod": {
    "id": "rob-wealth",
    "name": "Rob Wealth",
    "nameLocalized": "Roba Riqueza",
    "chinese": "劫財",
    "pinyin": "jié cái",
    "category": "peer",
    "keynote": "Drive, nerve, and competition for the same ground"
  },
  "yearBranchRelation": "same",
  "benMingNian": true,
  "yearBranchRelationMeaning": "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.",
  "interactions": [
    {
      "type": "clash",
      "id": "wu-zi",
      "chinese": "子午沖",
      "pinyin": "zǐ wǔ chōng",
      "quality": "challenging",
      "positions": [
        "year",
        "month"
      ],
      "members": [
        "zi",
        "wu"
      ],
      "transformsTo": "Water",
      "variety": "ungrateful",
      "complete": false,
      "meaning": "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."
    }
  ],
  "summary": "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."
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

List the 12 Chinese zodiac animals - Sheng Xiao sign catalogue

GET /api/v2/chinese-astrology/zodiac/animals

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-12, default 12. Default `12`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/zodiac/animals" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total animals in the cycle. Always 12; the zodiac is a closed set.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`animals` required	array of object	Animals for the current page, in cycle order. Use /zodiac/animals/{id} for the full record with strengths, weaknesses, element variants and relationship partners.
`animals[].id` required	string	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.
`animals[].name` required	string	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.
`animals[].nameLocalized`	string	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.
`animals[].chinese` required	string	Traditional hanzi character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang.
`animals[].pinyin` required	string	Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang.
`animals[].branch` required	string	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.
`animals[].element` required	string	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.
`animals[].elementLocalized`	string	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.
`animals[].polarity` required	string	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.
`animals[].traits` required	array of string	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.

Example response

{
  "total": 12,
  "limit": 12,
  "offset": 0,
  "animals": [
    {
      "id": "rat",
      "name": "Rat",
      "nameLocalized": "Rata",
      "chinese": "鼠",
      "pinyin": "shǔ",
      "branch": "zi",
      "element": "Water",
      "elementLocalized": "Agua",
      "polarity": "yang",
      "traits": [
        "quick-witted",
        "resourceful"
      ]
    }
  ]
}

Get one Chinese zodiac animal - Full sign profile with compatibility partners

GET /api/v2/chinese-astrology/zodiac/animals/{id}

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.

Parameters

Parameter	Type	Description
`id` required path	string enum	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.
`lang` query	string enum	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. Default `en`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/zodiac/animals/rat" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`id` required	string	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` required	string	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`	string	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` required	string	Traditional hanzi character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang.
`pinyin` required	string	Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang.
`branch` required	string	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` required	string	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`	string	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` required	string	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` required	array of string	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` required	string	Character sketch of the sign, drawn from the season, the double-hour and the phase its branch occupies.
`strengths` required	array of string	What the sign does well, as full sentences rather than keywords.
`weaknesses` required	array of string	Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw.
`compatibilitySummary` required	string	How the sign behaves toward the other eleven in general. For a specific pair, call /zodiac/compatibility/{sign1}/{sign2}.

Show all fieldsShow fewer fields

Field	Type	Description
`hours` required	object	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.
`hours.start` required	number	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.
`hours.end` required	number	Hour the double-hour ends, exclusive, on a 24-hour local clock. Each branch governs exactly two hours.
`trine` required	object	The three-harmony group (San He) this animal belongs to. Every animal belongs to exactly one.
`trine.id` required	string	Machine id of the trine: first, second, third or fourth. Always English.
`trine.number` required	number	Position of the trine in the order the tradition lists them, 1 to 4. Not a ranking.
`trine.element` required	string	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.
`trine.elementLocalized`	string	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.
`trine.chinese` required	string	The three Earthly Branches of the trine in classical notation, in the order the texts give them.
`trine.pinyin` required	string	Tone-marked pinyin of the three branches.
`trine.members` required	array of string	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.
`trine.theme` required	string	What the alliance is traditionally said to produce. The three branches combine into the element above, which is not any one member own phase.
`secretFriend` required	object	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.
`secretFriend.id` required	string	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.
`secretFriend.name` required	string	Display name of the related animal in English. Always English; use nameLocalized for display.
`secretFriend.nameLocalized`	string	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.
`secretFriend.chinese` required	string	Traditional hanzi character for the related animal.
`secretFriend.pinyin` required	string	Tone-marked pinyin for the related animal.
`secretFriend.element` required	string	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.
`secretFriend.elementLocalized`	string	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.
`clashPartner` required	object	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.
`clashPartner.id` required	string	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.
`clashPartner.name` required	string	Display name of the related animal in English. Always English; use nameLocalized for display.
`clashPartner.nameLocalized`	string	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.
`clashPartner.chinese` required	string	Traditional hanzi character for the related animal.
`clashPartner.pinyin` required	string	Tone-marked pinyin for the related animal.
`harmPartner` required	object	The harming animal (Liu Hai). Treated as less violent than a clash and harder to spot, because it works through accumulation rather than confrontation.
`harmPartner.id` required	string	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.
`harmPartner.name` required	string	Display name of the related animal in English. Always English; use nameLocalized for display.
`harmPartner.nameLocalized`	string	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.
`harmPartner.chinese` required	string	Traditional hanzi character for the related animal.
`harmPartner.pinyin` required	string	Tone-marked pinyin for the related animal.
`elementVariants` required	array of object	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.
`elementVariants[].element` required	string	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.
`elementVariants[].elementLocalized`	string	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.
`elementVariants[].polarity` required	string	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.
`elementVariants[].stem` required	string	Heavenly Stem of the year, as its pinyin identifier. The ten stems are jia, yi, bing, ding, wu, ji, geng, xin, ren, gui.
`elementVariants[].pillar` required	string	Sexagenary pillar id for this variant, stem then branch. This pair returns once every sixty years.
`elementVariants[].years` required	array of number	Gregorian years in the published window that carry this variant. Two per variant, sixty years apart.

Example response

{
  "id": "rat",
  "name": "Rat",
  "nameLocalized": "Rata",
  "chinese": "鼠",
  "pinyin": "shǔ",
  "branch": "zi",
  "element": "Water",
  "elementLocalized": "Agua",
  "polarity": "yang",
  "traits": [
    "quick-witted",
    "resourceful"
  ],
  "summary": "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.",
  "strengths": [
    "Reads a room and a situation faster than almost anyone, and turns the reading into a plan"
  ],
  "weaknesses": [
    "Overthinks the entry point and lets a good opening close while the analysis runs"
  ],
  "compatibilitySummary": "The Rat is easiest with signs that give its speed somewhere to land.",
  "hours": {
    "start": 23,
    "end": 1
  },
  "trine": {
    "id": "first",
    "number": 1,
    "element": "Water",
    "elementLocalized": "Agua",
    "chinese": "申子辰",
    "pinyin": "shēn zǐ chén",
    "members": [
      "rat",
      "dragon"
    ],
    "theme": "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."
  },
  "secretFriend": {
    "id": "rat",
    "name": "Horse",
    "nameLocalized": "Caballo",
    "chinese": "馬",
    "pinyin": "mǎ",
    "element": "Water",
    "elementLocalized": "Tierra"
  },
  "clashPartner": {
    "id": "rat",
    "name": "Horse",
    "nameLocalized": "Caballo",
    "chinese": "馬",
    "pinyin": "mǎ"
  },
  "harmPartner": {
    "id": "rat",
    "name": "Horse",
    "nameLocalized": "Caballo",
    "chinese": "馬",
    "pinyin": "mǎ"
  },
  "elementVariants": [
    {
      "element": "Water",
      "elementLocalized": "Metal",
      "polarity": "yang",
      "stem": "geng",
      "pillar": "geng-zi",
      "years": [
        1960,
        2020
      ]
    }
  ]
}

Find the Chinese zodiac animal for a birth date - Sheng Xiao calculator

POST /api/v2/chinese-astrology/zodiac/sign

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	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`	string enum	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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/zodiac/sign" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15"}'

Response fields

Field	Type	Description
`date` required	string	Echo of the birth date the answer was resolved from.
`animal` required	object	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.
`animal.id` required	string	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.
`animal.name` required	string	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.
`animal.nameLocalized`	string	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.
`animal.chinese` required	string	Traditional hanzi character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang.
`animal.pinyin` required	string	Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang.
`animal.branch` required	string	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.
`animal.element` required	string	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.
`animal.elementLocalized`	string	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.
`animal.polarity` required	string	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.
`yearPillar` required	object	The sexagenary year the date falls in, under the resolved boundary. Stem and branch together repeat once every sixty years.
`yearPillar.id` required	string	Sexagenary year pillar id, Heavenly Stem then Earthly Branch. Always English pinyin.
`yearPillar.number` required	number	Position of this pillar in the sixty-year sexagenary cycle, 1 to 60, where jia-zi is 1.

Show all fieldsShow fewer fields

Field	Type	Description
`yearPillar.stem` required	string	Heavenly Stem of the year, as its pinyin identifier.
`yearPillar.branch` required	string	Earthly Branch of the year, as its pinyin identifier. This is the branch the animal names.
`element` required	string	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`	string	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` required	string	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` required	string	Composed reading of the sign under its year phase. The sign contributes the temperament and the phase contributes the register.
`conventions` required	object	The school parameters this answer was computed under, echoed so the result is self-describing.
`conventions.yearBoundary` required	string	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.

Example response

{
  "date": "1990-06-15",
  "animal": {
    "id": "rat",
    "name": "Rat",
    "nameLocalized": "Rata",
    "chinese": "鼠",
    "pinyin": "shǔ",
    "branch": "zi",
    "element": "Water",
    "elementLocalized": "Agua",
    "polarity": "yang"
  },
  "yearPillar": {
    "id": "geng-wu",
    "number": 7,
    "stem": "geng",
    "branch": "wu"
  },
  "element": "Metal",
  "elementLocalized": "Metall",
  "polarity": "yang",
  "interpretation": "Born under the Horse in a Metal year. The sign supplies the temperament and the year phase supplies the register it plays in.",
  "conventions": {
    "yearBoundary": "lunar-new-year"
  }
}

Chinese zodiac compatibility - Trine, six harmony, clash and harm analysis

GET /api/v2/chinese-astrology/zodiac/compatibility/{sign1}/{sign2}

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.

Parameters

Parameter	Type	Description
`sign1` required path	string enum	First animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig.
`sign2` required path	string enum	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.
`lang` query	string enum	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. Default `en`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/zodiac/compatibility/rat/dragon" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`signs` required	object	The two signs compared, in the order they were requested. Always one object, never an array.
`signs.first` required	object
`signs.first.id` required	string	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.
`signs.first.name` required	string	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.
`signs.first.nameLocalized`	string	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.
`signs.first.chinese` required	string	Traditional hanzi character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang.
`signs.first.pinyin` required	string	Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang.
`signs.first.branch` required	string	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.
`signs.first.element` required	string	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.
`signs.first.elementLocalized`	string	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.
`signs.first.polarity` required	string	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.
`signs.second` required	object
`signs.second.id` required	string	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.
`signs.second.name` required	string	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.

Show all fieldsShow fewer fields

Field	Type	Description
`signs.second.nameLocalized`	string	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.
`signs.second.chinese` required	string	Traditional hanzi character for the animal itself, not for its Earthly Branch. Data rather than a translation, so it is identical under every lang.
`signs.second.pinyin` required	string	Tone-marked Hanyu Pinyin for the animal name. Data rather than a translation, so it is identical under every lang.
`signs.second.branch` required	string	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.
`signs.second.element` required	string	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.
`signs.second.elementLocalized`	string	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.
`signs.second.polarity` required	string	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.
`relationship` required	string	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` required	string	Display name of the relation in English. Always English; use relationshipNameLocalized for anything a reader sees.
`relationshipNameLocalized`	string	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` required	string	Classical name of the relation in traditional hanzi. Identical under every lang.
`relationshipPinyin` required	string	Tone-marked pinyin of the classical relation name.
`score` required	number	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` required	string	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`	string	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`	string	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` required	string	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` required	array of string	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` required	array of string	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` required	string	The one thing worth doing differently, specific to this relation rather than generic relationship guidance.

Example response

{
  "signs": {
    "first": {
      "id": "rat",
      "name": "Rat",
      "nameLocalized": "Rata",
      "chinese": "鼠",
      "pinyin": "shǔ",
      "branch": "zi",
      "element": "Water",
      "elementLocalized": "Agua",
      "polarity": "yang"
    },
    "second": {
      "id": "rat",
      "name": "Rat",
      "nameLocalized": "Rata",
      "chinese": "鼠",
      "pinyin": "shǔ",
      "branch": "zi",
      "element": "Water",
      "elementLocalized": "Agua",
      "polarity": "yang"
    }
  },
  "relationship": "trine",
  "relationshipName": "Three Harmonies",
  "relationshipNameLocalized": "Tres Armonias",
  "relationshipChinese": "三合",
  "relationshipPinyin": "sān hé",
  "score": 85,
  "verdict": "strong",
  "sharedElement": "Water",
  "sharedElementLocalized": "Agua",
  "summary": "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.",
  "strengths": [
    "Reads a room and a situation faster than almost anyone, and turns the reading into a plan"
  ],
  "frictions": [
    "Overthinks the entry point and lets a good opening close while the analysis runs"
  ],
  "advice": "Do not mistake ease for effort already made. Trines coast, and the pairing rewards whichever side keeps putting work in."
}

Daily Chinese zodiac reading - Day pillar forecast by animal sign

GET /api/v2/chinese-astrology/zodiac/{id}/daily

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.

Parameters

Parameter	Type	Description
`id` required path	string enum	Animal id, case-insensitive. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig.
`lang` query	string enum	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. Default `en`.
`date` query	string (date)	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.
`timezone` query	string	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").

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/zodiac/rat/daily" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`animal` required	object	The sign this reading was requested for.
`animal.id` required	string	Machine identifier of the sign this reading is for. Always English and lowercase, so it stays safe to compare against in code.
`animal.name` required	string	Display name of the sign in English. Always English; use nameLocalized for anything a reader sees.
`animal.nameLocalized`	string	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.
`animal.chinese` required	string	Traditional hanzi character for the animal. Identical under every lang.
`animal.pinyin` required	string	Tone-marked pinyin for the animal name.
`animal.branch` required	string	Earthly Branch this animal names, as its pinyin identifier.
`animal.element` required	string	Fixed Five Element phase of the sign own branch. Always English so it stays safe to compare against.
`animal.elementLocalized`	string	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.
`animal.polarity` required	string	Yin or yang polarity of the branch.
`date` required	string	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` required	object	The sexagenary pillar of this calendar day, evaluated at the reference meridian for the Chinese calendar.
`dayPillar.id` required	string	Sexagenary day pillar id, Heavenly Stem then Earthly Branch. Always English pinyin.
`dayPillar.number` required	number	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.

Show all fieldsShow fewer fields

Field	Type	Description
`dayPillar.stem` required	string	Heavenly Stem of the day, as its pinyin identifier.
`dayPillar.branch` required	string	Earthly Branch of the day, as its pinyin identifier.
`dayPillar.animal` required	string	The animal the day branch carries, which the tradition calls the day animal. This is what the requested sign is being read against.
`dayPillar.element` required	string	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.
`relationship` required	string	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` required	number	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` required	string	What the day does to this sign, from the branch relation and the phase of the day stem.
`love` required	string	Relationship guidance for the day, specific to the branch relation.
`career` required	string	Work guidance for the day. Clash and harm days carry the traditional cautions about signings and launches.
`advice` required	string	The one thing worth doing differently today, drawn from the relation and from this sign own habitual weak point.
`year` required	object	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.
`year.pillar` required	string	Sexagenary year pillar in force on this date, resolved on the lunar new year rule.
`year.animal` required	string	Animal of the year in force. Always English so it stays safe to compare against.
`year.animalLocalized`	string	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.
`year.relationship` required	string	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.
`year.note` required	string	One line on the year relationship, or on the Ben Ming Nian year when the year animal matches the sign.
`benMingNian` required	boolean	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.

Example response

{
  "animal": {
    "id": "rat",
    "name": "Rat",
    "nameLocalized": "Rata",
    "chinese": "鼠",
    "pinyin": "shǔ",
    "branch": "zi",
    "element": "Water",
    "elementLocalized": "Agua",
    "polarity": "yang"
  },
  "date": "2026-04-03",
  "dayPillar": {
    "id": "jia-zi",
    "number": 1,
    "stem": "jia",
    "branch": "zi",
    "animal": "rat",
    "element": "Wood"
  },
  "relationship": "trine",
  "energyRating": 9,
  "overview": "The day sits in the Water trine with the Rat, one of the three-sign alliances the cycle divides into.",
  "love": "An easy day for closeness. The trine removes the translation step, so what you meant is roughly what lands.",
  "career": "Good for anything collaborative. Trine partners cooperate without negotiating first, so meetings run short.",
  "advice": "Ask for the thing. Trine days are when a request costs the other person least.",
  "year": {
    "pillar": "bing-wu",
    "animal": "horse",
    "animalLocalized": "Caballo",
    "relationship": "clash",
    "note": "The year branch clashes with the Rat, so the year asks for decisions the sign would rather defer."
  },
  "benMingNian": false
}

List the 24 solar terms - Jie Qi calendar API with exact instants

GET /api/v2/chinese-astrology/calendar/solar-terms/{year}

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.

Parameters

Parameter	Type	Description
`year` required path	integer	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.
`lang` query	string enum	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. Default `en`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/calendar/solar-terms/2026" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`year` required	number	Echo of the solar year requested.
`referenceOffset` required	number	Decimal UTC offset of the reference meridian the local fields are given at. Fixed at 8 for the Chinese calendar.
`total` required	number	Number of terms returned, which is always 24.
`terms` required	array of object
`terms[].id` required	string	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.
`terms[].name` required	string	Display name of the term. Several English renderings are in circulation, so treat this as a label and the id as the value.
`terms[].chinese` required	string	The term in Chinese. A data field, identical in every language.
`terms[].pinyin` required	string	Tone marked pinyin for the characters.
`terms[].longitude` required	number	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.
`terms[].type` required	string	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.
`terms[].instantUtc` required	string	The instant the sun reaches the longitude, in UTC.
`terms[].localDate` required	string	Calendar date of the instant at the reference meridian. This is the date printed in an almanac.
`terms[].localTime` required	string	Time of day of the instant at the reference meridian.

Example response

{
  "year": 2026,
  "referenceOffset": 8,
  "total": 24,
  "terms": [
    {
      "id": "li-chun",
      "name": "Beginning of Spring",
      "chinese": "立春",
      "pinyin": "lì chūn",
      "longitude": 315,
      "type": "minor",
      "instantUtc": "2026-02-03T20:01:54.000Z",
      "localDate": "2026-02-04",
      "localTime": "04:01:54"
    }
  ]
}

Convert lunar and Gregorian dates - Chinese lunisolar calendar API

POST /api/v2/chinese-astrology/calendar/lunar-date

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`date`	string (date)	Gregorian date to convert to the lunisolar calendar. Send this OR the lunar fields, never both. Converts from the first day of lunar year 1551 to the last day of lunar year 2648, a little inside the supported date span, because numbering a lunar month needs the winter solstice on each side of it and placing a leap month needs the year before; a date outside that answers 400 date_out_of_range.
`lunarYear`	integer	Lunisolar year to convert back to a Gregorian date. Requires lunarMonth and lunarDay.
`lunarMonth`	integer	Lunar month, 1 to 12. Requires lunarYear and lunarDay.
`lunarDay`	integer	Day of the lunar month, 1 to 30. Requires lunarYear and lunarMonth.
`isLeapMonth`	boolean	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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/calendar/lunar-date" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","lunarYear":1990,"lunarMonth":5,"lunarDay":23}'

Response fields

Field	Type	Description
`gregorianDate` required	string	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` required	object
`lunar.year` required	number	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.
`lunar.month` required	number	Lunar month, 1 to 12. A leap month repeats the number of the month it follows.
`lunar.day` required	number	Day of the lunar month, 1 to 30. A lunar month never has 31 days.
`lunar.isLeapMonth` required	boolean	True when this is the leap repetition of the month number rather than the first pass through it.
`lunar.monthLength` required	number	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.
`lunar.date` required	string	The Gregorian date this lunar day covers, evaluated at the reference meridian.
`leapMonthOfYear`	number	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` required	number	Decimal UTC offset the calendar was evaluated at. Fixed at 8, which is what makes a Chinese lunar date a world constant.

Example response

{
  "gregorianDate": "1990-06-15",
  "lunar": {
    "year": 1990,
    "month": 5,
    "day": 23,
    "isLeapMonth": false,
    "monthLength": 30,
    "date": "1990-06-15"
  },
  "leapMonthOfYear": 5,
  "referenceOffset": 8
}

Get the almanac for a day - Tong Shu API with day officers and mansions

GET /api/v2/chinese-astrology/calendar/day/{date}

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.

Parameters

Parameter	Type	Description
`date` required path	string (date)	Gregorian date in YYYY-MM-DD format, evaluated at the reference meridian. Years 1900 to 2100.
`lang` query	string enum	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. Default `en`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/calendar/day/1990-06-15" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`date` required	string	The Gregorian date of the day, at the reference meridian.
`lunar` required	object
`lunar.year` required	number	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.
`lunar.month` required	number	Lunar month, 1 to 12. A leap month repeats the number of the month it follows.
`lunar.day` required	number	Day of the lunar month, 1 to 30. A lunar month never has 31 days.
`lunar.isLeapMonth` required	boolean	True when this is the leap repetition of the month number rather than the first pass through it.
`lunar.monthLength` required	number	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.
`lunar.date` required	string	The Gregorian date this lunar day covers, evaluated at the reference meridian.
`yearPillar` required	object	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.
`yearPillar.id` required	string	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.
`yearPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`yearPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`yearPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`yearPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.

Show all fieldsShow fewer fields

Field	Type	Description
`yearPillar.naYin` required	string	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.
`yearPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`monthPillar` required	object	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.
`monthPillar.id` required	string	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.
`monthPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`monthPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`monthPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`monthPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`monthPillar.naYin` required	string	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.
`monthPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`dayPillar` required	object
`dayPillar.id` required	string	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.
`dayPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`dayPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`dayPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`dayPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`dayPillar.naYin` required	string	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.
`dayPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`dayOfficer` required	object
`dayOfficer.id` required	string	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.
`dayOfficer.nameLocalized`	string	Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged.
`dayOfficer.name` required	string	English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
`dayOfficer.chinese` required	string	The officer in Chinese. A data field, identical in every language.
`dayOfficer.pinyin` required	string	Tone marked pinyin for the character.
`dayOfficer.quality` required	string	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.
`dayOfficer.meaning` required	string	What the officer means, in the terms a date choice uses it in.
`mansion` required	object
`mansion.number` required	number	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.
`mansion.name` required	string	English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
`mansion.nameLocalized`	string	Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
`mansion.chinese` required	string	The mansion in Chinese. A data field, identical in every language.
`mansion.pinyin` required	string	Tone marked pinyin for the character.
`mansion.palace` required	string	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.
`mansion.planet` required	string	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.
`mansion.animal` required	string	Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
`mansion.animalLocalized`	string	Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
`clashAnimal` required	string	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`	string	Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged.
`favours` required	array of string	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` required	array of string	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.

Example response

{
  "date": "1990-06-15",
  "lunar": {
    "year": 1990,
    "month": 5,
    "day": 23,
    "isLeapMonth": false,
    "monthLength": 30,
    "date": "1990-06-15"
  },
  "yearPillar": {
    "id": "geng-wu",
    "number": 7,
    "stem": "geng",
    "branch": "wu",
    "chinese": "辛亥",
    "naYin": "Metal of Hairpin and Bracelet",
    "naYinElement": "Metal"
  },
  "monthPillar": {
    "id": "ren-wu",
    "number": 19,
    "stem": "ren",
    "branch": "wu",
    "chinese": "辛亥",
    "naYin": "Metal of Hairpin and Bracelet",
    "naYinElement": "Metal"
  },
  "dayPillar": {
    "id": "xin-hai",
    "number": 48,
    "stem": "xin",
    "branch": "hai",
    "chinese": "辛亥",
    "naYin": "Metal of Hairpin and Bracelet",
    "naYinElement": "Metal"
  },
  "dayOfficer": {
    "id": "zhi",
    "nameLocalized": "Halten",
    "name": "Hold",
    "chinese": "執",
    "pinyin": "zhí",
    "quality": "inauspicious",
    "meaning": "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."
  },
  "mansion": {
    "number": 2,
    "name": "Neck",
    "nameLocalized": "星宿",
    "chinese": "亢",
    "pinyin": "Kàng",
    "palace": "azure-dragon",
    "planet": "Metal",
    "animal": "Dragon",
    "animalLocalized": "龍"
  },
  "clashAnimal": "snake",
  "clashAnimalLocalized": "Schlange",
  "favours": [
    "moving-house",
    "travel"
  ],
  "avoids": [
    "moving-house",
    "travel"
  ]
}

Get a month of almanac days - Chinese calendar month view API

GET /api/v2/chinese-astrology/calendar/monthly

Return every day of one Gregorian month of the Chinese almanac 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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.
`year` query	integer	Gregorian year, 1900 to 2100. Defaults to the current UTC year when omitted, together with month.
`month` query	integer	Gregorian month, 1 to 12. Defaults to the current UTC month when omitted, together with year.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/calendar/monthly" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`year` required	number	Year of the month returned. Echoes the year requested, or the current UTC year when it was omitted.
`month` required	number	Month returned, 1 to 12. Echoes the month requested, or the current UTC month when it was omitted.
`total` required	number	Number of days in the month.
`solarTerms` required	array of object
`solarTerms[].id` required	string	Solar term identifier in kebab case pinyin.
`solarTerms[].name` required	string	Display name of the term.
`solarTerms[].type` required	string	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.
`solarTerms[].date` required	string	Date the term falls on at the reference meridian.
`solarTerms[].instantUtc` required	string	The exact instant of the term, in UTC.
`days` required	array of object	Every day of the month, in order.
`days[].date` required	string	The Gregorian date of the day, at the reference meridian.
`days[].lunar` required	object
`days[].lunar.year` required	number	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.
`days[].lunar.month` required	number	Lunar month, 1 to 12. A leap month repeats the number of the month it follows.

Show all fieldsShow fewer fields

Field	Type	Description
`days[].lunar.day` required	number	Day of the lunar month, 1 to 30. A lunar month never has 31 days.
`days[].lunar.isLeapMonth` required	boolean	True when this is the leap repetition of the month number rather than the first pass through it.
`days[].lunar.monthLength` required	number	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.
`days[].lunar.date` required	string	The Gregorian date this lunar day covers, evaluated at the reference meridian.
`days[].yearPillar` required	object	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.
`days[].yearPillar.id` required	string	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.
`days[].yearPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].yearPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].yearPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].yearPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].yearPillar.naYin` required	string	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.
`days[].yearPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].monthPillar` required	object	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.
`days[].monthPillar.id` required	string	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.
`days[].monthPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].monthPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].monthPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].monthPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].monthPillar.naYin` required	string	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.
`days[].monthPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].dayPillar` required	object
`days[].dayPillar.id` required	string	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.
`days[].dayPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].dayPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].dayPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].dayPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].dayPillar.naYin` required	string	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.
`days[].dayPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].dayOfficer` required	object
`days[].dayOfficer.id` required	string	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.
`days[].dayOfficer.nameLocalized`	string	Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged.
`days[].dayOfficer.name` required	string	English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
`days[].dayOfficer.chinese` required	string	The officer in Chinese. A data field, identical in every language.
`days[].dayOfficer.pinyin` required	string	Tone marked pinyin for the character.
`days[].dayOfficer.quality` required	string	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.
`days[].dayOfficer.meaning` required	string	What the officer means, in the terms a date choice uses it in.
`days[].mansion` required	object
`days[].mansion.number` required	number	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.
`days[].mansion.name` required	string	English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
`days[].mansion.nameLocalized`	string	Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
`days[].mansion.chinese` required	string	The mansion in Chinese. A data field, identical in every language.
`days[].mansion.pinyin` required	string	Tone marked pinyin for the character.
`days[].mansion.palace` required	string	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.
`days[].mansion.planet` required	string	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.
`days[].mansion.animal` required	string	Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
`days[].mansion.animalLocalized`	string	Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
`days[].clashAnimal` required	string	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.
`days[].clashAnimalLocalized`	string	Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged.
`days[].favours` required	array of string	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.
`days[].avoids` required	array of string	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.

Example response

{
  "year": 1990,
  "month": 6,
  "total": 30,
  "solarTerms": [
    {
      "id": "mang-zhong",
      "name": "Grain in Ear",
      "type": "minor",
      "date": "1990-06-06",
      "instantUtc": "1990-06-05T22:31:00.000Z"
    }
  ],
  "days": [
    {
      "date": "1990-06-15",
      "lunar": {
        "year": 1990,
        "month": 5,
        "day": 23,
        "isLeapMonth": false,
        "monthLength": 30,
        "date": "1990-06-15"
      },
      "yearPillar": {
        "id": "geng-wu",
        "number": 7,
        "stem": "geng",
        "branch": "wu",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "monthPillar": {
        "id": "ren-wu",
        "number": 19,
        "stem": "ren",
        "branch": "wu",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "dayPillar": {
        "id": "xin-hai",
        "number": 48,
        "stem": "xin",
        "branch": "hai",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "dayOfficer": {
        "id": "zhi",
        "nameLocalized": "Halten",
        "name": "Hold",
        "chinese": "執",
        "pinyin": "zhí",
        "quality": "inauspicious",
        "meaning": "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."
      },
      "mansion": {
        "number": 2,
        "name": "Neck",
        "nameLocalized": "星宿",
        "chinese": "亢",
        "pinyin": "Kàng",
        "palace": "azure-dragon",
        "planet": "Metal",
        "animal": "Dragon",
        "animalLocalized": "龍"
      },
      "clashAnimal": "snake",
      "clashAnimalLocalized": "Schlange",
      "favours": [
        "moving-house",
        "travel"
      ],
      "avoids": [
        "moving-house",
        "travel"
      ]
    }
  ]
}

Find auspicious days - Chinese date selection API for weddings and openings

POST /api/v2/chinese-astrology/calendar/auspicious-days

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.

Request body

Field	Type	Description
`activity` required	string enum	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` required	string (date)	First date of the range to search, inclusive.
`endDate` required	string (date)	Last date of the range to search, inclusive. The range may not exceed 93 days.
`avoidAnimal`	string enum	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.

curl

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/calendar/auspicious-days" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity":"wedding","startDate":"2026-03-01","endDate":"2026-04-30"}'

Response fields

Field	Type	Description
`activity` required	string	Echo of the activity searched for, folded to its canonical identifier.
`activityLabel` required	string	Display label for the activity in the requested language.
`startDate` required	string	Echo of the first date of the range.
`endDate` required	string	Echo of the last date of the range.
`daysSearched` required	number	Number of days in the range, counting both ends.
`avoidAnimal`	string	Echo of the animal protected. Absent when none was sent, rather than null.
`avoidAnimalLocalized`	string	Display name of the protected animal in the requested language, beside the avoidAnimal identifier. Absent when no animal was sent and absent when lang is en, so an English response is unchanged.
`total` required	number	Number of favoured days found. This is the count after the clash filter, not the number of days searched.
`days` required	array of object	The favoured days, in date order.
`days[].date` required	string	The Gregorian date of the day, at the reference meridian.
`days[].lunar` required	object
`days[].lunar.year` required	number	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.
`days[].lunar.month` required	number	Lunar month, 1 to 12. A leap month repeats the number of the month it follows.
`days[].lunar.day` required	number	Day of the lunar month, 1 to 30. A lunar month never has 31 days.

Show all fieldsShow fewer fields

Field	Type	Description
`days[].lunar.isLeapMonth` required	boolean	True when this is the leap repetition of the month number rather than the first pass through it.
`days[].lunar.monthLength` required	number	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.
`days[].lunar.date` required	string	The Gregorian date this lunar day covers, evaluated at the reference meridian.
`days[].yearPillar` required	object	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.
`days[].yearPillar.id` required	string	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.
`days[].yearPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].yearPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].yearPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].yearPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].yearPillar.naYin` required	string	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.
`days[].yearPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].monthPillar` required	object	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.
`days[].monthPillar.id` required	string	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.
`days[].monthPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].monthPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].monthPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].monthPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].monthPillar.naYin` required	string	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.
`days[].monthPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].dayPillar` required	object
`days[].dayPillar.id` required	string	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.
`days[].dayPillar.number` required	number	Position in the sixty year cycle, 1 to 60. jia-zi is 1 and gui-hai is 60.
`days[].dayPillar.stem` required	string	Heavenly Stem of the pillar, one of jia yi bing ding wu ji geng xin ren gui.
`days[].dayPillar.branch` required	string	Earthly Branch of the pillar, one of zi chou yin mao chen si wu wei shen you xu hai.
`days[].dayPillar.chinese` required	string	The pillar in Chinese characters. A data field, identical in every language.
`days[].dayPillar.naYin` required	string	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.
`days[].dayPillar.naYinElement` required	string	Five phase the Na Yin resolves to. Always English, so it stays safe to compare against in code.
`days[].dayOfficer` required	object
`days[].dayOfficer.id` required	string	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.
`days[].dayOfficer.nameLocalized`	string	Display name of the officer in the requested language. Absent when lang is en, so an English response is unchanged.
`days[].dayOfficer.name` required	string	English display name of the officer. Canonical, identical in every language, so it stays safe to compare against in code. The translation is in nameLocalized.
`days[].dayOfficer.chinese` required	string	The officer in Chinese. A data field, identical in every language.
`days[].dayOfficer.pinyin` required	string	Tone marked pinyin for the character.
`days[].dayOfficer.quality` required	string	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.
`days[].dayOfficer.meaning` required	string	What the officer means, in the terms a date choice uses it in.
`days[].mansion` required	object
`days[].mansion.number` required	number	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.
`days[].mansion.name` required	string	English display name of the mansion. Canonical, identical in every language. The translation is in nameLocalized. Note the mansion has no string id: number is the stable 1 to 28 key, because five of the 28 share a pinyin spelling.
`days[].mansion.nameLocalized`	string	Display name of the mansion in the requested language. Absent when lang is en, and absent when a language has no entry for this mansion, so a caller falls back to name rather than rendering a blank.
`days[].mansion.chinese` required	string	The mansion in Chinese. A data field, identical in every language.
`days[].mansion.pinyin` required	string	Tone marked pinyin for the character.
`days[].mansion.palace` required	string	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.
`days[].mansion.planet` required	string	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.
`days[].mansion.animal` required	string	Animal emblem of the mansion, the third character of its full Chinese name. English and canonical, identical in every language, matching how clashAnimal behaves on the same response. The translation is in animalLocalized.
`days[].mansion.animalLocalized`	string	Animal emblem in the requested language. Absent when lang is en, and absent when a language has no entry, so a caller falls back to animal.
`days[].clashAnimal` required	string	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.
`days[].clashAnimalLocalized`	string	Display name of the clashing animal in the requested language. Absent when lang is en, so an English response is unchanged.
`days[].favours` required	array of string	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.
`days[].avoids` required	array of string	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.

Example response

{
  "activity": "wedding",
  "activityLabel": "Wedding",
  "startDate": "2026-03-01",
  "endDate": "2026-04-30",
  "daysSearched": 61,
  "avoidAnimal": "rat",
  "avoidAnimalLocalized": "Ratte",
  "total": 8,
  "days": [
    {
      "date": "1990-06-15",
      "lunar": {
        "year": 1990,
        "month": 5,
        "day": 23,
        "isLeapMonth": false,
        "monthLength": 30,
        "date": "1990-06-15"
      },
      "yearPillar": {
        "id": "geng-wu",
        "number": 7,
        "stem": "geng",
        "branch": "wu",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "monthPillar": {
        "id": "ren-wu",
        "number": 19,
        "stem": "ren",
        "branch": "wu",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "dayPillar": {
        "id": "xin-hai",
        "number": 48,
        "stem": "xin",
        "branch": "hai",
        "chinese": "辛亥",
        "naYin": "Metal of Hairpin and Bracelet",
        "naYinElement": "Metal"
      },
      "dayOfficer": {
        "id": "zhi",
        "nameLocalized": "Halten",
        "name": "Hold",
        "chinese": "執",
        "pinyin": "zhí",
        "quality": "inauspicious",
        "meaning": "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."
      },
      "mansion": {
        "number": 2,
        "name": "Neck",
        "nameLocalized": "星宿",
        "chinese": "亢",
        "pinyin": "Kàng",
        "palace": "azure-dragon",
        "planet": "Metal",
        "animal": "Dragon",
        "animalLocalized": "龍"
      },
      "clashAnimal": "snake",
      "clashAnimalLocalized": "Schlange",
      "favours": [
        "moving-house",
        "travel"
      ],
      "avoids": [
        "moving-house",
        "travel"
      ]
    }
  ]
}

List the five elements - Wu Xing API with generating and controlling cycles

GET /api/v2/chinese-astrology/elements

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.

Parameters

Parameter	Type	Description
`lang` query	string enum	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. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-5, default 5. Default `5`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/chinese-astrology/elements" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total number of phases, which is always five.
`limit` required	number	Maximum phases returned in this page.
`offset` required	number	Number of phases skipped before this page.
`generatingCycle` required	array of string	The producing ring in order. Each phase generates the next and the last generates the first, so the list wraps.
`controllingCycle` required	array of string	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` required	array of object	The phases for this page, in generating cycle order.
`elements[].id` required	string	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.
`elements[].nameLocalized`	string	Display name of the phase in the requested language. Absent when lang is en, so an English response is unchanged.
`elements[].chinese` required	string	Chinese character for the phase. A data field, identical in every language.
`elements[].pinyin` required	string	Tone marked pinyin for the character. A data field, identical in every language.
`elements[].season` required	string	Season the phase governs. Earth governs the transitions rather than a season of its own, and is reported as Late Summer.
`elements[].direction` required	string	Compass direction of the phase. Earth returns Center, because it sits at the middle of the arrangement rather than on the ring.
`elements[].generates` required	string	The phase this one produces in the generating cycle. Wood feeds Fire, Fire makes Earth, Earth bears Metal, Metal condenses Water, Water grows Wood.
`elements[].generatedBy` required	string	The phase that produces this one. The inverse of the generates field.

Show all fieldsShow fewer fields

Field	Type	Description
`elements[].controls` required	string	The phase this one restrains in the controlling cycle. Wood breaks Earth, Earth dams Water, Water quenches Fire, Fire melts Metal, Metal cuts Wood.
`elements[].controlledBy` required	string	The phase that restrains this one. The inverse of the controls field.
`elements[].stems` required	array of string	The two Heavenly Stems that carry this phase, yang first. Every phase has exactly two, which is why ten stems cover five phases.
`elements[].branches` required	array of string	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.
`elements[].meaning` required	string	What the phase is and how it behaves, in the terms a reading uses it in. Translated in place.

Example response

{
  "total": 5,
  "limit": 5,
  "offset": 0,
  "generatingCycle": [
    "Wood",
    "Fire"
  ],
  "controllingCycle": [
    "Wood",
    "Earth"
  ],
  "elements": [
    {
      "id": "Wood",
      "nameLocalized": "Holz",
      "chinese": "木",
      "pinyin": "mù",
      "season": "Spring",
      "direction": "East",
      "generates": "Fire",
      "generatedBy": "Water",
      "controls": "Earth",
      "controlledBy": "Metal",
      "stems": [
        "jia",
        "yi"
      ],
      "branches": [
        "yin",
        "mao"
      ],
      "meaning": "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."
    }
  ]
}