Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Roxy Feng Shui 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: Feng Shui
description: 'Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mountains, Kua numbers and the full Eight Mansions map of favourable and unfavourable directions, annual and monthly star plates, the four annual afflictions with exact degree spans, the compass Bagua map and the 1864 to 2043 period table. Chinese years resolve at Li Chun, computed astronomically, so the boundary is right rather than assumed. One key, Remote MCP, typed SDKs.'
paths:
/feng-shui/kua:
post:
operationId: calculateKuaNumber
tags:
- Feng Shui
summary: Calculate Kua number - Feng shui personal direction calculator API
description: Calculate the Kua number, also called the Ming Gua or life gua, from a birth date and sex. Returns the number, the east or west life group, the personal trigram, and all eight compass sectors classified from best to worst. The Chinese year is resolved at Li Chun by default, so an early February birthday is placed in the correct year rather than the calendar one, and the boundary that decided it is echoed back. Built for room and desk placement features, personalised feng shui reports, and any product that needs a favourable direction per person.
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: '1985-07-15'
description: 'Birth date in YYYY-MM-DD format. Only the Chinese YEAR this date falls in enters the formula, so no birth time, latitude or longitude is needed. A January or early February birthday is the case that matters: it usually belongs to the PREVIOUS Chinese year and produces a different Kua. A date is read at the start of its day, and the boundary falls part-way through its own day, so a birth date landing exactly on the boundary day is placed in the outgoing year.'
gender:
type: string
enum:
- male
- female
example: male
description: Selects the Kua formula variant. The two formulas are different arithmetic on the same year, and they also differ in where a raw result of 5 is reassigned.
yearBoundary:
type: string
enum:
- li-chun
- lunar-new-year
default: li-chun
example: li-chun
description: Which boundary starts the Chinese year. Defaults to li-chun, the astronomical start of spring in early February, which is the classical position and the one feng shui uses for periods, annual stars and afflictions alike. Send lunar-new-year to match popular zodiac tables, which start the year two to four weeks later. The two disagree for anyone born between the two dates.
required:
- date
- gender
responses:
'200':
description: Kua number, life group, personal trigram and all eight classified sectors
content:
application/json:
schema:
type: object
properties:
kua:
type: number
example: 6
description: Kua number, 1 to 9 excluding 5. This is the value every other feng shui calculation about a person keys on.
rawKua:
type: number
example: 6
description: The formula output before any reassignment. Equal to kua except when the formula produced 5, which has no trigram and no direction and must be moved.
reassigned:
type: boolean
example: false
description: Whether the raw result was 5 and had to be moved onto a trigram, to 2 for a man and to 8 for a woman.
gender:
type: string
example: male
description: Echo of the sex sent, which selected the formula variant.
group:
type: string
example: west
description: Life group, east or west. East group Kuas are 1, 3, 4 and 9 and share North, East, Southeast and South as their favourable sectors; west group Kuas are 2, 6, 7 and 8 and share Northeast, Southwest, West and Northwest. Always English, safe to compare against.
solarYear:
type: number
example: 1985
description: The Chinese year the birth date fell in under the boundary applied. This is the year the formula actually used, which is the previous calendar year for an early-in-the-year birthday.
boundaryDate:
type: string
example: '1985-02-04'
description: Calendar date of the boundary that decided the year, computed astronomically rather than assumed. Li Chun is commonly quoted as 4 February and lands on the 3rd or the 5th in roughly one year in four.
trigram:
type: object
properties:
number:
type: number
example: 4
description: Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking.
chinese:
type: string
example: 巽
description: Chinese character for the trigram. Data, identical in every language.
english:
type: string
example: Wind
description: English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number.
pinyin:
type: string
example: Xùn
description: Tone-marked pinyin for the trigram. Data, identical in every language.
symbol:
type: string
example: ☴
description: Unicode trigram symbol, for rendering a Bagua diagram without an icon set.
binary:
type: string
example: '011'
description: Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram.
element:
type: string
example: Wood
description: 'Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint.'
direction:
type: string
example: Southeast
description: Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints.
familyMember:
type: string
example: Eldest Daughter
description: Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at.
required:
- number
- chinese
- english
- pinyin
- symbol
- binary
- element
- direction
- familyMember
sectors:
type: array
items:
type: object
properties:
direction:
type: string
example: Southeast
description: Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints.
star:
type: string
example: sheng-chi
description: Eight Mansions star for this sector, one of sheng-chi, tian-yi, yan-nian, fu-wei, huo-hai, wu-gui, liu-sha, jue-ming. Always English, safe to compare against and to key styling on.
starName:
type: string
example: Sheng Chi
description: Display name of the star. Always English, whatever the lang parameter says. Use starNameLocalized for anything a reader sees.
starNameLocalized:
type: string
example: Aliento generador
description: Star 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 starName exactly. Never compare against this value.
nature:
type: string
example: auspicious
description: 'Whether the sector helps or harms: auspicious or inauspicious.'
rank:
type: number
example: 1
description: Order within its nature, 1 to 4. Among auspicious sectors 1 is the strongest; among inauspicious sectors 1 is the mildest and 4 the most serious, which is what tells you which affliction to accept when no favourable sector is reachable.
domain:
type: string
example: Growth and income
description: The life domain this sector governs, in a few words.
required:
- direction
- star
- starName
- nature
- rank
- domain
description: All eight sectors classified for this Kua, in compass order from North. Exactly four are auspicious and four are inauspicious, and the two sets partition the compass. Call the eight mansions endpoint for the same map with full readings and ranked placement guidance.
conventions:
type: object
properties:
yearBoundary:
type: string
example: li-chun
description: Which boundary decided the Chinese year for this calculation. li-chun starts the year at the astronomical start of spring, in early February, and is the classical position that feng shui uses throughout. lunar-new-year starts it at the first day of the lunar year, which is usually two to four weeks later and is what most popular zodiac tables use. Echoes the resolved value, whether it was sent or defaulted.
required:
- yearBoundary
required:
- kua
- rawKua
- reassigned
- gender
- group
- solarYear
- boundaryDate
- trigram
- sectors
- conventions
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/feng-shui/kua/{number}:
get:
operationId: getKuaNumber
tags:
- Feng Shui
summary: Look up a Kua number - Eight Mansions reference API
description: 'Look up the reference chart for one Kua number: its trigram, its east or west life group, and how it classifies all eight compass sectors. A pure reference endpoint with no birth data required, for building a lookup table or a picker. Number 5 is served for completeness and is never a computed result, because it belongs to the centre and has no direction of its own: a man whose formula gives 5 reads Kua 2 and a woman reads Kua 8, and the chart returned for 5 is therefore the Kua 2 chart.'
security:
- apiKey: []
parameters:
- schema:
type: number
minimum: 1
maximum: 9
example: 8
description: Kua number, 1 to 9.
required: true
description: Kua number, 1 to 9.
name: number
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
responses:
'200':
description: Kua reference chart with trigram, life group and eight classified sectors
content:
application/json:
schema:
type: object
properties:
number:
type: number
example: 8
description: Kua number, 1 to 9.
group:
type: string
example: west
description: Life group, east or west. Always English, safe to compare against and to key styling on.
trigram:
type: object
properties:
number:
type: number
example: 4
description: Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking.
chinese:
type: string
example: 巽
description: Chinese character for the trigram. Data, identical in every language.
english:
type: string
example: Wind
description: English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number.
pinyin:
type: string
example: Xùn
description: Tone-marked pinyin for the trigram. Data, identical in every language.
symbol:
type: string
example: ☴
description: Unicode trigram symbol, for rendering a Bagua diagram without an icon set.
binary:
type: string
example: '011'
description: Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram.
element:
type: string
example: Wood
description: 'Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint.'
direction:
type: string
example: Southeast
description: Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints.
familyMember:
type: string
example: Eldest Daughter
description: Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at.
required:
- number
- chinese
- english
- pinyin
- symbol
- binary
- element
- direction
- familyMember
sectors:
type: array
items:
type: object
properties:
direction:
type: string
example: Southeast
description: Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints.
star:
type: string
example: sheng-chi
description: Eight Mansions star for this sector, one of sheng-chi, tian-yi, yan-nian, fu-wei, huo-hai, wu-gui, liu-sha, jue-ming. Always English, safe to compare against and to key styling on.
starName:
type: string
example: Sheng Chi
description: Display name of the star. Always English, whatever the lang parameter says. Use starNameLocalized for anything a reader sees.
starNameLocalized:
type: string
example: Aliento generador
description: Star 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 starName exactly. Never compare against this value.
nature:
type: string
example: auspicious
description: 'Whether the sector helps or harms: auspicious or inauspicious.'
rank:
type: number
example: 1
description: Order within its nature, 1 to 4. Among auspicious sectors 1 is the strongest; among inauspicious sectors 1 is the mildest and 4 the most serious, which is what tells you which affliction to accept when no favourable sector is reachable.
domain:
type: string
example: Growth and income
description: The life domain this sector governs, in a few words.
required:
- direction
- star
- starName
- nature
- rank
- domain
description: All eight sectors classified for this Kua, in compass order from North.
required:
- number
- group
- trigram
- sectors
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'404':
description: No Kua chart for that number
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Resource not found
description: Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead.
code:
type: string
example: not_found
description: Machine-readable error code. Stable identifier for programmatic error handling.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/feng-shui/eight-mansions:
post:
operationId: generateEightMansions
tags:
- Feng Shui
summary: Generate Eight Mansions map - Ba Zhai lucky direction API
description: 'Build the full Eight Mansions (Ba Zhai) map for a person: all eight compass sectors classified into the four favourable stars, Sheng Chi, Tian Yi, Yan Nian and Fu Wei, and the four unfavourable ones, Huo Hai, Wu Gui, Liu Sha and Jue Ming. Sectors come back ordered best to worst with a composed reading each, plus the ranking that decides which
# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-feng-shui-api-openapi.yml