Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Roxy Chinese Astrology API
version: 2.0.0
description: '# RoxyAPI: AI-Native Insight Infrastructure
> **Base URL:** `https://roxyapi.com/api/v2`
> All endpoint paths below are relative to this base URL.'
contact:
name: RoxyAPI Support
url: https://roxyapi.com/contact
license:
name: Proprietary
url: https://roxyapi.com/policy/terms
servers:
- url: /api/v2
description: Production API v2
security:
- apiKey: []
tags:
- name: Chinese Astrology
description: 'Calculate BaZi Four Pillars charts, Chinese zodiac signs, and the Chinese lunisolar calendar from any birth moment: year, month, day and hour pillars with hidden stems, Na Yin and Ten God relations, luck pillars, day master strength, and animal compatibility.'
paths:
/chinese-astrology/bazi/chart:
post:
operationId: generateBaziChart
tags:
- Chinese Astrology
summary: Generate BaZi chart - Four Pillars of Destiny calculator API
description: Calculate a complete BaZi chart, the Four Pillars of Destiny, from a birth moment. Returns the year, month, day and hour pillars with every Heavenly Stem and Earthly Branch, the stems hidden inside each branch, the Ten God relation each one holds to the Day Master, the Na Yin sound element of each pair, the five-element balance across the chart, and the combinations and clashes running between the pillars. The day boundary, year boundary and hour clock are all selectable and the applied conventions come back on every response, so a chart is self-describing. Built for astrology apps, matchmaking services, and agents that need a Four Pillars reading they can reproduce.
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
requestBody:
content:
application/json:
schema:
type: object
properties:
date:
type: string
format: date
example: '1990-06-15'
description: Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary.
time:
type: string
format: time
example: '14:30:00'
description: Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere.
timezone:
anyOf:
- type: number
minimum: -14
maximum: 14
- type: string
description: 'IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.'
example: America/New_York
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
example: 116.4
description: Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is "local-mean" or "solar", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is "clock".
dayBoundary:
type: string
enum:
- split-zi
- midnight
- early-zi
default: split-zi
example: split-zi
description: 'Which instant starts the sexagenary DAY, which only matters for a birth between 23:00 and 23:59. "midnight" is the classical position of the Ming compendium San Ming Tong Hui: the day turns at 00:00 and 23:00 to 23:59 is the late zi hour of the day that is ending, so the hour stem is taken from that day. "early-zi" turns the whole day at 23:00, the practice in Hong Kong, Taiwan and much of South East Asia. "split-zi" is the compromise most software implements and the default here: the day still turns at 00:00, but the hour stem is taken from the next day. The three give three different answers for a late-evening birth and identical answers for every other birth.'
yearBoundary:
type: string
enum:
- li-chun
- lunar-new-year
default: li-chun
example: li-chun
description: 'Which instant starts the sexagenary YEAR. "li-chun" is Beginning of Spring, around 4 February, and is the classical rule every BaZi text uses, so it is the default on this endpoint. "lunar-new-year" is the folk rule people mean when they say which animal they are, and it falls between late January and late February. The two disagree for any birth in the weeks between them: 14 February 2026 is a Wood Snake year under lunar-new-year and a Fire Horse year under li-chun.'
hourClock:
type: string
enum:
- clock
- local-mean
- solar
default: clock
example: clock
description: Which clock the HOUR branch is read from. "clock" is civil time exactly as a birth certificate records it, which is what most calculators use and the default here. "local-mean" shifts to the mean sun over the birth longitude, a correction of up to 59 minutes at the edge of a wide time zone. "solar" adds the equation of time on top of that, up to a further 16 minutes. Both non-civil options need "longitude" in the request and return 400 without it.
required:
- date
- time
- timezone
responses:
'200':
description: Four pillars, Day Master, element balance, interactions, and the conventions
content:
application/json:
schema:
type: object
properties:
birthData:
type: object
properties:
date:
type: string
format: date
example: '1990-06-15'
description: Birth date in YYYY-MM-DD format. Sets the year, month and day pillars. The year pillar turns at Beginning of Spring rather than on 1 January, and the month pillar turns at each of the twelve minor solar terms rather than at a calendar month boundary.
time:
type: string
format: time
example: '14:30:00'
description: Birth time in 24-hour HH:MM:SS format. Sets the hour pillar, which is one of the four and carries the whole picture of later life and offspring. Each Earthly Branch covers two hours, so a birth within a few minutes of an odd hour can land in either. All four pillars are read in the local clock of the birth, and the day boundary is applied in that same clock; only the lunisolar calendar date itself is a world constant, fixed at UTC plus 8 so one instant has one Chinese date everywhere.
timezone:
type: number
example: 8
description: Decimal UTC offset the chart was computed with, resolved from whatever the request sent. An IANA name is resolved to the offset in force on the birth date, so this is the literal number applied and never the name.
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Accepted for consistency with the other birth-data endpoints and does not affect any part of a BaZi chart. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
example: 116.4
description: Birth longitude in decimal degrees. Positive is East, negative is West. Required when hourClock is "local-mean" or "solar", which shift the hour branch to the sun over the birth place; omitting it in either case returns 400. Ignored when hourClock is "clock".
required:
- date
- time
- timezone
description: Echo of the birth moment the chart was computed from.
conventions:
type: object
properties:
dayBoundary:
type: string
enum:
- split-zi
- midnight
- early-zi
example: split-zi
description: Day-boundary school actually applied. Echoes the request, or the default when it was omitted. Always English, whatever the lang parameter says, so it stays safe to compare against in code.
yearBoundary:
type: string
enum:
- li-chun
- lunar-new-year
example: li-chun
description: Year-boundary school actually applied. Echoes the request, or the default when it was omitted.
hourClock:
type: string
enum:
- clock
- local-mean
- solar
example: clock
description: Hour clock actually applied. Echoes the request, or the default when omitted.
required:
- dayBoundary
- yearBoundary
- hourClock
description: 'The three school conventions this result was computed under. Returned on every BaZi response so a chart is self-describing: two calculators can produce different pillars for one birth and both be correct, and this object says which reading you are holding.'
pillars:
type: array
items:
type: object
properties:
position:
type: string
example: year
description: Which of the four pillars this is. One of year, month, day, hour. The year pillar reads ancestry and early life, the month career and parents, the day the self and the partner, the hour later life and children.
id:
type: string
example: geng-wu
description: Pillar identifier, the stem id and the branch id joined by a hyphen. Always English pinyin, whatever the lang parameter says.
number:
type: number
example: 7
description: Position of this pillar in the sexagenary cycle, 1 to 60, where jia-zi is 1. The cycle runs stems and branches together, which is why only 60 of the 120 possible pairings occur.
stem:
type: object
properties:
id:
type: string
example: geng
description: Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on.
chinese:
type: string
example: 庚
description: The stem in hanzi. Data rather than display copy, so it is identical under every lang.
pinyin:
type: string
example: gēng
description: Tone-marked pinyin for the stem. Identical under every lang.
element:
type: string
example: Metal
description: Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
elementLocalized:
type: string
example: Metal
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
polarity:
type: string
example: yang
description: Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart.
required:
- id
- chinese
- pinyin
- element
- polarity
description: The Heavenly Stem of this pillar.
branch:
type: object
properties:
id:
type: string
example: wu
description: 'Earthly Branch identifier. One of zi, chou, yin, mao, chen, si, wu, wei, shen, you, xu, hai. Always English pinyin, whatever the lang parameter says. Note that "wu" is also a stem identifier: they never share a field, so a branch id is only ever read out of a branch position.'
chinese:
type: string
example: 午
description: The branch in hanzi. Identical under every lang.
pinyin:
type: string
example: wǔ
description: Tone-marked pinyin for the branch. Identical under every lang.
animal:
type: string
example: horse
description: Zodiac animal of the branch. One of rat, ox, tiger, rabbit, dragon, snake, horse, goat, monkey, rooster, dog, pig. Always English, whatever the lang parameter says. Use animalLocalized for anything a reader sees.
animalLocalized:
type: string
example: Caballo
description: Zodiac animal name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
element:
type: string
example: Fire
description: Five-phase element of the branch. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
elementLocalized:
type: string
example: Fuego
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
polarity:
type: string
example: yang
description: Polarity of the branch, yang or yin.
required:
- id
- chinese
- pinyin
- animal
- element
- polarity
description: The Earthly Branch of this pillar.
tenGod:
type: object
properties:
id:
type: string
example: rob-wealth
description: Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says.
name:
type: string
example: Rob Wealth
description: Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
nameLocalized:
type: string
example: Roba Riqueza
description: Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
chinese:
type: string
example: 劫財
description: The relation in traditional hanzi. Identical under every lang.
pinyin:
type: string
example: jié cái
description: Tone-marked pinyin for the relation. Identical under every lang.
category:
type: string
example: peer
description: Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says.
keynote:
type: string
example: Drive, nerve, and competition for the same ground
description: One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
required:
- id
- name
- chinese
- pinyin
- category
- keynote
description: Relation the pillar STEM holds to the Day Master. The day pillar carries day-master instead, because the day stem is the reference point every other position is measured from rather than a relation to itself.
hiddenStems:
type: array
items:
type: object
properties:
stem:
type: object
properties:
id:
type: string
example: geng
description: Heavenly Stem identifier. One of jia, yi, bing, ding, wu, ji, geng, xin, ren, gui. Always English pinyin, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on.
chinese:
type: string
example: 庚
description: The stem in hanzi. Data rather than display copy, so it is identical under every lang.
pinyin:
type: string
example: gēng
description: Tone-marked pinyin for the stem. Identical under every lang.
element:
type: string
example: Metal
description: Five-phase element of the stem. One of Wood, Fire, Earth, Metal, Water. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
elementLocalized:
type: string
example: Metal
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
polarity:
type: string
example: yang
description: Polarity of the stem, yang or yin. The five odd stems are yang and the five even ones are yin, and this is half of what decides every Ten God relation in the chart.
required:
- id
- chinese
- pinyin
- element
- polarity
description: The stem stored in the branch.
role:
type: string
example: principal
description: 'Rank of this stem inside the branch, by the classical day-count that divides a thirty-day month 18, 9 and 3 days between the stems a branch holds. principal is the first-ranked stem and always matches the branch element; middle is the second-ranked; residual is the third. A branch holds one to three, always returned in rank order. What each rank CONTAINS depends on the branch family: on a storage branch the second-ranked stem is the seasonal carryover from the month before and the third is the stem that branch stores as the close of its trine, while on a growth branch the second-ranked stem is the one beginning its long-life phase there and the third is the carryover. Some schools name the same three positions by that function rather than by rank, which swaps the second and third labels on the four storage branches, so compare on rank rather than assuming a name.'
tenGod:
type: object
properties:
id:
type: string
example: rob-wealth
description: Ten God identifier. One of friend, rob-wealth, eating-god, hurting-officer, indirect-wealth, direct-wealth, seven-killings, direct-officer, indirect-resource, direct-resource, plus day-master in the day-stem position. Always English, whatever the lang parameter says.
name:
type: string
example: Rob Wealth
description: Display name of the relation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees.
nameLocalized:
type: string
example: Roba Riqueza
description: Ten God name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
chinese:
type: string
example: 劫財
description: The relation in traditional hanzi. Identical under every lang.
pinyin:
type: string
example: jié cái
description: Tone-marked pinyin for the relation. Identical under every lang.
category:
type: string
example: peer
description: Which of the five cycle relations this belongs to. peer is the same element as the Day Master, output is what the Day Master generates, wealth is what it controls, influence is what controls it, resource is what generates it, and self marks the Day Master itself. Always English, whatever the lang parameter says.
keynote:
type: string
example: Drive, nerve, and competition for the same ground
description: One-line summary of what this relation contributes, for a compact rendering that has no room for the full meaning.
required:
- id
- name
- chinese
- pinyin
- category
- keynote
description: Relation this hidden stem holds to the Day Master.
required:
- stem
- role
- tenGod
description: Stems stored inside the branch, principal first. These carry the qi a branch holds without showing it, and they are where a Day Master finds a root.
naYin:
type: string
example: Earth by the Roadside
description: Na Yin sound element of the pillar, an older elemental reading assigned to each of the 30 stem-and-branch pairs. The hanzi name sits beside it in naYinChinese.
naYinChinese:
type: string
example: 路旁土
description: The Na Yin name in hanzi. Identical under every lang.
naYinElement:
type: string
example: Earth
description: Element the Na Yin resolves to. Independent of the stem element and often different from it, which is why it is reported separately rather than folded in.
required:
- position
- id
- number
- stem
- branch
- tenGod
- hiddenStems
- naYin
- naYinChinese
- naYinElement
description: The four pillars, year first. Each carries its stem, its branch, the hidden stems stored in the branch, the Ten God relation to the Day Master, and the Na Yin sound element of the pair.
dayMaster:
type: object
properties:
stem:
type: string
example: xin
description: Day stem identifier, which IS the Day Master. Always English pinyin, whatever the lang parameter says.
chinese:
type: string
example: 辛
description: The Day Master stem in hanzi. Identical under every lang.
pinyin:
type: string
example: xīn
description: Tone-marked pinyin for the Day Master stem.
element:
type: string
example: Metal
description: Five-phase element of the Day Master. Every Ten God in the chart is measured from this element and this polarity. Always English, whatever the lang parameter says. Use elementLocalized for anything a reader sees.
elementLocalized:
type: string
example: Metal
description: Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it.
polarity:
type: string
example: yin
description: Polarity of the Day Master, yang or yin.
nature:
type: string
example: 'Jewel, coin and finished blade rather than raw ore: cool, smooth and already refined. Heaped earth buries it, which is the one thing it truly fears, while moving water rinses it until it shows what it is. Under summer heat it wants damp earth for cover. In deep winter it wants the small contained fire and never the open blaze, which w
# --- truncated at 32 KB (420 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-chinese-astrology-api-openapi.yml