# Feng Shui API > 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. Flying star charts that are actually checkable. - Product page: https://roxyapi.com/products/feng-shui-api - OpenAPI spec: https://roxyapi.com/api/v2/feng-shui/openapi.json - Remote MCP server: https://roxyapi.com/mcp/feng-shui - Authentication: `X-API-Key` header on every request - Pricing: https://roxyapi.com/pricing (all domains included in every plan) ## Stats - uptime: 99.95%+ ## Features - Xuan Kong flying star natal charts cast from a construction period and a facing direction, returning all nine palaces with the period star, the mountain star and the water star, the flight direction of each plate, and the classical structure verdict - Facing accepted as one of the 24 mountains or as a raw compass bearing, with the response saying when a bearing fell in the outer band where the substitute gua construction applies instead - A named formation and a composed reading for every palace of a chart, built from the classical two star combinations and the five phase relation between the pair - Kua numbers for both formula variants, before and from the year 2000, with the raw result published beside the reassignment so a 5 is never silently changed - The full Eight Mansions map: all eight sectors classified into Sheng Chi, Tian Yi, Yan Nian and Fu Wei, and Huo Hai, Wu Gui, Liu Sha and Jue Ming, ordered best to worst with a rank that says which affliction to accept when no favourable sector is reachable - Annual and monthly star plates on the SOLAR calendar, where the year turns at Li Chun and each month at a major solar term, not on 1 January and not at Lunar New Year - The four annual afflictions with degree spans rather than sector names: Tai Sui on a single 15 degree mountain, Sui Po opposite it, the Three Killings across its 75 degree span split into its three named parts, and the Five Yellow read off the annual plate - The compass Bagua map with both the Later Heaven and Earlier Heaven arrangements per sector, aligned to true directions rather than to the front door - The nine periods from 1864 to 2043 with the exact Li Chun date each one opened, so a building finished in early February lands in the right period - Trigram vocabulary served from the same source as the I-Ching endpoints, so a trigram read from a Bagua sector and one read from the I-Ching catalogue agree field for field ## Includes The Feng Shui API bundles these sub-APIs under one key: - Flying Star API - Kua Number API - Eight Mansions API - Annual Afflictions API - Bagua Map API ## Use Cases - Property and interior design tools: natal charts and Bagua overlays laid onto a floor plan, sector by sector - Personal feng shui apps: Kua numbers, favourable directions and bed or desk placement guidance per household member - Yearly and monthly guidance features: annual star plates, afflictions and the renovation dates to avoid - AI assistants and chatbots: chart data over Remote MCP so an agent can answer a placement question with real numbers - Practitioner and consultation software: the full nine palace chart with flight directions and structure, in the form a professional already reads - Content and editorial platforms: star, Bagua and period reference lookups for explainer pages and structured libraries ## FAQ ### How do I add a flying star chart to my app? Send the construction period of the building and the direction it faces, either as one of the 24 mountains or as a compass bearing, and the API returns all nine palaces with the period star, the mountain star, the water star, the named formation for each pair and the classical verdict on the chart. Omit the period and it defaults to the one in force. Drop in the typed SDKs or point a client at our Remote MCP server, and one key also covers every other RoxyAPI domain. ### Which feng shui school do these calculations follow? Flying star charts follow the down gua construction of the Xuan Kong school, the one every modern text teaches, with the period plate flown forward and the mountain and water plates flown by the San Yuan polarity of the mountain each answers to. Eight Mansions follows the classical Da You Nian classification, which the API derives from the trigram line rule rather than reading off a stored matrix, so a transposed cell cannot survive. Where a genuine school split exists it is stated rather than hidden. ### When does the feng shui year actually change? At Li Chun, the astronomical start of spring in early February, and not at Lunar New Year, which is usually two to four weeks later. Every route in this domain uses that boundary: periods, annual stars, monthly stars and all four afflictions. The exact date is computed for each year rather than assumed to be 4 February, which it is not in roughly one year in four, and it is returned on the response so a caller can apply a new chart on the right day. ### What is a Kua number and why does it need my birth date and sex? The Kua number, also called the Ming Gua, places a person on one of the eight trigrams and decides which four compass sectors are favourable for them and which four are not. It is a function of the Chinese year of birth and of sex, because the two formula variants are different arithmetic on the same year. Birth time and place are not used, so no location lookup is needed. A raw result of 5 has no direction of its own and is reassigned, and the API publishes the untouched result beside the reassigned one. ### Do the mountain star and the water star mean different things? Yes, and reading them the same way is the usual mistake. The mountain star, also called the sitting star, governs health, the people in a room and the relationships between them. The water star, also called the facing star, governs money, career and whatever arrives from outside. A palace is then judged by the PAIR rather than by either star alone, which is why every palace in a chart comes back with the combination for its pair and a reading composed from both. ### How precise are the affliction positions? Precise to the mountain, which is 15 degrees, rather than to the 45 degree sector most guides quote. Tai Sui occupies exactly one mountain, so the two neighbouring mountains of the same sector are unaffected, and the difference decides whether a wall can be drilled. The Three Killings span is returned as both its exact 75 degree branch range and the cardinal sector it sits in, because both readings are in circulation and a caller should be able to see which one they are applying. ## Endpoints - `POST /api/v2/feng-shui/kua` Calculate Kua number - Feng shui personal direction calculator API - `GET /api/v2/feng-shui/kua/{number}` Look up a Kua number - Eight Mansions reference API - `POST /api/v2/feng-shui/eight-mansions` Generate Eight Mansions map - Ba Zhai lucky direction API - `POST /api/v2/feng-shui/flying-stars/natal` Generate flying star natal chart - Xuan Kong Fei Xing API - `GET /api/v2/feng-shui/flying-stars/annual/{year}` Annual flying stars - Yearly feng shui star chart API - `GET /api/v2/feng-shui/flying-stars/monthly` Monthly flying stars - Month by month feng shui overlay API - `GET /api/v2/feng-shui/flying-stars/stars` List the nine flying stars - Xuan Kong star reference API - `GET /api/v2/feng-shui/afflictions/{year}` Annual afflictions - Tai Sui, San Sha and Five Yellow API - `GET /api/v2/feng-shui/bagua` List Bagua sectors - Feng shui bagua map API - `GET /api/v2/feng-shui/bagua/{id}` Look up a Bagua sector - Life area reference API - `GET /api/v2/feng-shui/periods` List the nine periods - San Yuan period table API ## Example Response ``` POST /api/v2/feng-shui/flying-stars/natal ``` ```json { "period": 9, "facing": { "id": "wu", "chinese": "午", "pinyin": "Wǔ", "label": "S2", "direction": "South", "yuan": "heaven", "polarity": "yin", "startDegree": 172.5, "endDegree": 187.5 }, "sitting": { "id": "zi", "chinese": "子", "pinyin": "Zǐ", "label": "N2", "direction": "North", "yuan": "heaven", "polarity": "yin", "startDegree": 352.5, "endDegree": 7.5 }, "straddling": false, "mountainCenterStar": 5, "waterCenterStar": 4, "mountainFlight": "reverse", "waterFlight": "forward", "structure": { "id": "double-sitting", "name": "Double Star at Sitting", "chinese": "雙星到坐", "meaning": "Both prosperous stars gather at the back of the building. Good for health, for family and for anyone who works from home, weaker for income arriving from outside. The standard correction is water or open movement at the back, which gives the water star somewhere to work." }, "palaces": [ { "palace": "Center", "base": 5, "period": 9, "mountain": 5, "water": 4, "reading": "The Five Yellow mountain star sits with the Four Green water star in this palace. The water star controls the mountain star here, Wood acting on Earth, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "Northwest", "base": 6, "period": 1, "mountain": 4, "water": 5, "reading": "The Four Green mountain star sits with the Five Yellow water star in this palace. The mountain star controls the water star here, Wood acting on Earth, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "West", "base": 7, "period": 2, "mountain": 3, "water": 6, "reading": "The Three Jade mountain star sits with the Six White water star in this palace. The water star controls the mountain star here, Metal acting on Wood, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "Northeast", "base": 8, "period": 3, "mountain": 2, "water": 7, "reading": "The Two Black mountain star sits with the Seven Red water star in this palace. The mountain star produces the water star here, Earth feeding Metal, so the people side of the palace pours into the money side and the sector rewards effort spent on the household before effort spent on income. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "South", "base": 9, "period": 4, "mountain": 1, "water": 8, "reading": "The One White mountain star sits with the Eight White water star in this palace. The water star controls the mountain star here, Earth acting on Water, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "North", "base": 1, "period": 5, "mountain": 9, "water": 9, "reading": "The Nine Purple mountain star sits with the Nine Purple water star in this palace. Both stars carry the Fire phase, so they reinforce each other instead of moderating each other, and whatever this palace does it does emphatically. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "Southwest", "base": 2, "period": 6, "mountain": 8, "water": 1, "reading": "The Eight White mountain star sits with the One White water star in this palace. The mountain star controls the water star here, Earth acting on Water, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "East", "base": 3, "period": 7, "mountain": 7, "water": 2, "reading": "The Seven Red mountain star sits with the Two Black water star in this palace. The water star produces the mountain star here, Earth feeding Metal, so money and opportunity support health and relationships, and the sector is usually easier to live in than to profit from. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." }, { "palace": "Southeast", "base": 4, "period": 8, "mountain": 6, "water": 3, "reading": "The Six White mountain star sits with the Three Jade water star in this palace. The mountain star controls the water star here, Metal acting on Wood, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside." } ] } ``` ## MCP Tool Naming Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/feng-shui`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`: ``` POST /feng-shui/kua -> post_feng_shui_kua GET /feng-shui/kua/{number} -> get_feng_shui_kua_number POST /feng-shui/eight-mansions -> post_feng_shui_eight_mansions ``` `tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call). ## Multi-language Support Append `?lang=` to translated endpoints. Supported on this domain: `de, en, es, fr, hi, pt, ru, zh-Hans, zh-Hant, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text. ## Error Contract Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable): - `validation_error` (400, returns `issues[]` with all field errors at once) - `api_key_required` (401), `invalid_api_key` (401) - `subscription_inactive` (403), `subscription_not_found` (404) - `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field) - `rate_limit_exceeded` (429) - `internal_error` (500) Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff. ## Full Reference For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/feng-shui/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.