Flying star chart calculator for Xuan Kong feng shui. Send a construction period and the direction a building faces and get all nine palaces with the period star, the mountain star and the water star, a named formation and a composed reading per palace, and the classical verdict on the chart as a whole. Facing is one of the 24 mountains or a compass bearing. One key covers 18+ spiritual domains. MCP-first.
Flying star feng shui, Xuan Kong Fei Xing, reads a building as a grid of nine palaces and asks which of the nine stars flew into each one. Two inputs decide the whole chart: the twenty year period the building was completed in, and the mountain it faces. This repo ships working TypeScript, JavaScript, and Python samples against the RoxyAPI flying star natal endpoint, the deepest call in the feng shui API family. One call returns all nine palaces with the base star, the period star, the mountain star that governs health and the people in the room, and the water star that governs money and whatever arrives from outside, plus the named classical formation where the tradition names one, a composed reading for every palace, and the verdict on how the two prosperous stars landed. One subscription unlocks 18+ spiritual domains: Western astrology, Vedic astrology, Forecast, Human Design, Chinese astrology, Feng Shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, and location.
Four properties decide whether a flying star chart calculator is usable in software. A fifth decides whether it is worth taking as a dependency.
The period is dated, not assumed. Periods turn over at Li Chun in early February, not on 1 January and not at Lunar New Year. Period 9 opened on 4 February 2024 and runs to 2043, so a building finished in January 2024 is a Period 8 building and keeps that plate for its whole life. Hardcode the period and the chart is wrong for the next seventeen years, and it is the kind of wrong that surfaces only when a customer checks. GET /feng-shui/periods returns the 1864 to 2043 table with the exact Li Chun date each period opened, plus currentPeriod resolved for any date you pass, so the period is looked up rather than guessed.
Facing is one of the 24 mountains, not a compass word. The 360 degree circle is cut into 24 sectors of 15 degrees, and two buildings in the same compass sector can hold different charts because they sit on different mountains inside it. Send facing as a pinyin id (ren zi gui chou gen yin jia mao yi chen xun si bing wu ding wei kun shen geng you xin xu qian hai) or as a compass label (N1 N2 N3 NE1 NE2 NE3 E1 E2 E3 SE1 SE2 SE3 S1 S2 S3 SW1 SW2 SW3 W1 W2 W3 NW1 NW2 NW3). Both spellings resolve to the same mountain, so wu and S2 return the same chart. Sending "south" returns a 400 with the valid options listed. If you only have a bearing off a compass, send facingDegrees instead and the server resolves the mountain for you.
Mountain flight and water flight are returned separately. Each plate flies forward or in reverse independently, decided by the San Yuan polarity of the mountain its centre star answers to, and that polarity differs from the natural polarity of the stem or branch on eight of the 24 mountains. mountainFlight and waterFlight are published as their own fields precisely because this is the step that separates two charts that otherwise look alike, and it is the one thing a picture of a finished chart cannot tell you.
A straddling facing is named, not silently resolved. A bearing that lands in the outer 3 degrees of its mountain rather than the central 9 calls for a different construction of the chart. The response sets straddling to true and returns the standard chart anyway, so a caller knows the case needs a specialist instead of receiving a confident answer that quietly papers over the boundary.
Breadth on one key. The same key reaches the annual and monthly star plates, the Eight Mansions map, the Kua number, the bagua life areas, BaZi four pillars, the Tong Shu almanac day view, and every other domain in the catalog, so this feng shui API is never a single purpose dependency you have to justify on its own.
GET /feng-shui/periods is the table every flying star chart is dated against. It returns all nine twenty year periods of the 180 year San Yuan cycle from 1864 to 2043, each with its ruling star, five phase, palace, era, and the exact Li Chun date it opened, plus which period is in force on a date you name.
curl https://roxyapi.com/api/v2/feng-shui/periods \
-H "X-API-Key: $ROXY_API_KEY"{
"total": 9,
"cycleStartYear": 1864,
"cycleEndYear": 2043,
"date": "2026-08-26",
"currentPeriod": 9,
"periods": [
{
"number": 9,
"startYear": 2024,
"endYear": 2043,
"startDate": "2024-02-04",
"era": "lower",
"eraName": "Lower Era",
"rulingStar": 9,
"rulingStarName": "Nine Purple",
"element": "Fire",
"palace": "South",
"trigram": { "number": 6, "english": "Fire", "chinese": "離" },
"base": 9
}
]
}Pass ?date=2024-01-20 and currentPeriod comes back as 8, because that date sits before Li Chun. That is the lookup a property tool needs at the moment a user types a completion date, and it is why the period belongs in a request rather than in a constant.
The period is not a cosmetic label either. Sweep all 24 mountains in Period 9 and every chart returns a structure of double-facing or double-sitting. Sweep the same 24 mountains in Period 8 and six come back prosperous-mountain-prosperous-water and six come back reversed. Same building, same facing, different period, opposite verdict.
| Property | Value |
|---|---|
| Coverage | 18+ spiritual domains in one subscription |
| Facing | 24 mountains by pinyin id or compass label, or a raw bearing in degrees |
| Period | 1 to 9, defaulting to the period in force now, dated at Li Chun |
| Published separately | mountainFlight and waterFlight, mountainCenterStar and waterCenterStar, straddling |
| Readings | A named classical formation where one exists, and a composed reading for all nine palaces |
| Languages | Nine locales alongside English, including Simplified and Traditional Chinese |
| MCP server | https://roxyapi.com/mcp/feng-shui (Streamable HTTP, no local setup) |
| SDKs | TypeScript on npm @roxyapi/sdk, Python on PyPI roxy-sdk, PHP on Packagist roxyapi/sdk, C# on NuGet RoxyApi.Sdk, Go github.com/RoxyAPI/sdk-go, WordPress plugin roxyapi |
| Pricing | One key, flat per call, from $39/mo |
| Licensing | Personal and commercial use, including closed source apps. No AGPL or GPL entanglement. Full terms |
| Last verified | 2026-Q3 |
- Get a key at roxyapi.com/pricing
- Pick a language below
- Copy the snippet, run, ship
A flying star natal chart takes no birth data and no coordinates. It describes a building, not a person, so there is no location lookup step: send the period and the facing and you have a chart.
curl -X POST https://roxyapi.com/api/v2/feng-shui/flying-stars/natal \
-H "X-API-Key: $ROXY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"period": 9,
"facing": "wu"
}'import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ["ROXY_API_KEY"])
# A Period 9 building facing the wu mountain, which is S2, the middle of South
chart = roxy.feng_shui.generate_flying_star_chart(period=9, facing="wu")
print("Period", chart["period"], "facing", chart["facing"]["label"], "sitting", chart["sitting"]["label"])
print("Structure:", chart["structure"]["name"])
print("Mountain plate flies", chart["mountainFlight"], "water plate flies", chart["waterFlight"])
for p in chart["palaces"]:
print(f" {p['palace']:<10} period {p['period']} mountain {p['mountain']} water {p['water']}")import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY);
// A Period 9 building facing the wu mountain, which is S2, the middle of South
const { data, error } = await roxy.fengShui.generateFlyingStarChart({
body: { period: 9, facing: 'wu' },
});
if (error) throw new Error(error.error);
console.log('Period', data.period, 'facing', data.facing.label, 'sitting', data.sitting.label);
console.log('Structure:', data.structure.name);
console.log('Mountain plate flies', data.mountainFlight, 'water plate flies', data.waterFlight);
data.palaces.forEach(p =>
console.log(` ${p.palace} period ${p.period} mountain ${p.mountain} water ${p.water}`)
);import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
// A Period 9 building facing the wu mountain, which is S2, the middle of South
const { data, error } = await roxy.fengShui.generateFlyingStarChart({
body: { period: 9, facing: 'wu' },
});
if (error) throw new Error(error.error);
console.log(`Period ${data.period}, facing ${data.facing.label}, sitting ${data.sitting.label}`);
console.log(`Structure: ${data.structure.name} (${data.structure.id})`);
console.log(`Mountain plate ${data.mountainFlight}, water plate ${data.waterFlight}`);
for (const p of data.palaces) {
const formation = p.combination ? ` ${p.combination.name}` : '';
console.log(` ${p.palace.padEnd(10)} m${p.mountain} w${p.water}${formation}`);
}All three body fields are optional, with one rule: send facing or facingDegrees. Sending neither returns a 400, because a chart cannot be cast without a direction.
| Field | Type | Required | Description |
|---|---|---|---|
period |
integer | no | Construction period of the building, 1 to 9. The twenty year cycle the building was completed in, or last renovated heavily enough to reset, fixed for the life of the building. Periods change at Li Chun in early February, so a building finished in January 2024 is a Period 8 building. Defaults to the period in force now |
facing |
string | conditional | The mountain the front of the building faces, by pinyin id such as wu or by compass label such as S2. The facing side is the open, active, public side, which is not always the side with the front door. Send this or facingDegrees |
facingDegrees |
number | conditional | The compass bearing the front of the building faces, 0 to 360 degrees, measured looking out from inside. Resolved to one of the 24 mountains. Send this or facing |
lang |
query string | no | Response language. Nine locales alongside English, including Simplified and Traditional Chinese. Machine values stay English in every language |
The 24 valid facing ids, in compass order from North: ren zi gui chou gen yin jia mao yi chen xun si bing wu ding wei kun shen geng you xin xu qian hai. The 24 equivalent labels: N1 N2 N3 NE1 NE2 NE3 E1 E2 E3 SE1 SE2 SE3 S1 S2 S3 SW1 SW2 SW3 W1 W2 W3 NW1 NW2 NW3.
A Period 9 building facing wu, which is S2. Four of the nine palaces shown.
{
"period": 9,
"facing": {
"id": "wu",
"label": "S2",
"chinese": "午",
"pinyin": "Wǔ",
"direction": "South",
"yuan": "heaven",
"polarity": "yin",
"startDegree": 172.5,
"endDegree": 187.5
},
"sitting": {
"id": "zi",
"label": "N2",
"chinese": "子",
"pinyin": "Zǐ",
"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."
},
{
"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."
},
{
"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."
},
{
"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."
}
]
}| Field | Type | Description |
|---|---|---|
period |
number | The period this chart was built for. Echoes the period requested, or the period in force now when it was omitted |
facing |
object | The resolved facing mountain: id, label, chinese, pinyin, direction, yuan, polarity, startDegree, endDegree |
sitting |
object | The mountain directly opposite the facing, same shape. The back of the building |
facingDegrees |
number | Echo of the bearing sent, when one was sent. Absent when the facing was named as a mountain instead, since naming a mountain expresses no bearing |
straddling |
boolean | Whether the bearing fell in the outer 3 degrees of its mountain rather than the central 9. A true value means the case calls for a different construction and needs a specialist. Always false when the facing was named as a mountain |
mountainCenterStar |
number | The star that entered the centre of the mountain plate, 1 to 9 |
waterCenterStar |
number | The star that entered the centre of the water plate, 1 to 9 |
mountainFlight |
string | forward or reverse, decided by the polarity of the mountain the centre star answers to |
waterFlight |
string | forward or reverse, decided the same way against the facing mountain |
structure.id |
string | The verdict on the chart: prosperous-mountain-prosperous-water, reversed, double-facing, or double-sitting. Always English, safe to switch on |
structure.name |
string | Display name of the structure, translated in place under ?lang=. Switch on structure.id, never on this |
structure.chinese |
string | Chinese name of the structure. Data, identical in every language |
structure.meaning |
string | What the structure means and what the classical correction for it is |
palaces |
array | All nine palaces, centre first and then along the Lo Shu flight path |
palaces[].palace |
string | Center, North, Northeast, East, Southeast, South, Southwest, West, or Northwest. Always English, safe to key a grid cell on |
palaces[].base |
number | The Lo Shu base number of the palace, 1 to 9 |
palaces[].period |
number | The period star in this palace, 1 to 9 |
palaces[].mountain |
number | The mountain star, read for health, for the people in the room, and for the relationships between them |
palaces[].water |
number | The water star, read for money, opportunity, and whatever arrives from outside |
palaces[].combination |
object | The named classical formation for this mountain and water pair: id such as 2-5, name, nameLocalized under ?lang=, chinese, and nature. Absent for the pairs the tradition does not name, where the composed reading carries the meaning instead |
palaces[].reading |
string | What this palace means, composed from the two stars and the phase relation between them. Translated in place under ?lang= |
Each of the nine stars appears exactly once on each plate, which is the property that makes a chart checkable.
The same building facing the same wu mountain, but completed before Li Chun 2024 and therefore Period 8, returns a different structure and surfaces the named formations:
{
"period": 8,
"structure": { "id": "double-facing", "name": "Double Star at Facing", "chinese": "雙星到向" },
"palaces": [
{ "palace": "Northwest", "mountain": 5, "water": 2,
"combination": { "id": "2-5", "name": "Compounded Earth", "chinese": "二五交加", "nature": "inauspicious" } },
{ "palace": "West", "mountain": 6, "water": 1,
"combination": { "id": "1-6", "name": "Heaven and Water", "chinese": "一六共宗", "nature": "auspicious" } },
{ "palace": "Northeast", "mountain": 7, "water": 9,
"combination": { "id": "7-9", "name": "Fire and Metal", "chinese": "七九合轍", "nature": "inauspicious" } }
]
}combination.id is canonical with the lower number first, so a palace holding mountain 9 and water 7 resolves to the same 7-9 entry as one holding mountain 7 and water 9. Branch on id and nature, and display name or nameLocalized.
| Use case | Endpoint flow |
|---|---|
| Flying star chart calculator | POST to /feng-shui/flying-stars/natal with period and facing, render palaces[] as a three by three grid keyed on palace |
| Floor plan overlay | Map each palaces[].palace to a compass sector of the plan, label the cell with mountain over water and the period star |
| Property listing analysis | Read structure.id for a one line verdict, then palaces[].combination.nature to flag the sectors that need attention |
| Facing capture from a compass | Send facingDegrees straight from the device reading, check straddling before showing the result as settled |
| Completion date to period lookup | GET /feng-shui/periods?date= with the completion date, feed currentPeriod into the natal call |
| Annual and monthly overlay | Layer GET /feng-shui/flying-stars/annual/{year} and GET /feng-shui/flying-stars/monthly on top of the natal grid for timing |
| Star reference pages | GET /feng-shui/flying-stars/stars once for the nine star catalogue and link every chart cell to it |
GET /feng-shui/periods(listNinePeriods) - the nine twenty year periods from 1864 to 2043 with the exact Li Chun date each opened, pluscurrentPeriodfor any date. The lookup that dates every natal chartGET /feng-shui/flying-stars/stars(listFlyingStars) - the nine star catalogue the charts link to: name, Chinese characters, five phase, home palace, trigram, the period each rules, and which element strengthens or drains itGET /feng-shui/flying-stars/annual/{year}(getAnnualFlyingStars) - the annual plate for a solar year, universal to every building, withchangeoverDatereturned because the changeover is Li Chun and not Lunar New YearGET /feng-shui/flying-stars/monthly(getMonthlyFlyingStars) - the faster monthly overlay on solar months, where month 1 begins at Li Chun and no month lines up with a calendar monthGET /feng-shui/bagua(listBaguaSectors) - the bagua life areas, eight compass sectors plus the centre, each with its element, colors, trigram, and focusPOST /feng-shui/eight-mansions(generateEightMansions) - the Eight Mansions map ranked best to worst for a person rather than a building, withbestSector,worstSector, and the sector the building faces
Connect Claude, GPT, Gemini, or Cursor to RoxyAPI through the remote MCP server. No Docker. No self hosting. The full MCP tool catalog for this domain is at https://roxyapi.com/mcp/feng-shui.
{
"mcpServers": {
"feng-shui": {
"url": "https://roxyapi.com/mcp/feng-shui",
"headers": { "X-API-Key": "$ROXY_API_KEY" }
}
}
}The tool for this endpoint is post_feng_shui_flying_stars_natal, the period table is get_feng_shui_periods, and the star catalogue is get_feng_shui_flying_stars.
See docs/mcp for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code setup.
This repo ships an AGENTS.md execution playbook. Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, and Gemini CLI will pick it up automatically. Top level overview lives at roxyapi.com/AGENTS.md.
- Methodology and gold standard tests
- Full API reference interactive Scalar UI
- TypeScript SDK on npm
- Python SDK on PyPI
- PHP SDK on Packagist
- C# SDK on NuGet
- Go SDK on pkg.go.dev
- WordPress plugin
- llms.txt full LLM citation index
- Top level AGENTS.md
MIT for this sample repo. See LICENSE.
Catalog licensing: Personal and commercial use, including closed source proprietary apps. No AGPL or GPL entanglement. RoxyAPI APIs and SDKs are safe to embed in commercial products. Full terms at roxyapi.com/policy/license.
- Site: roxyapi.com
- Status: roxyapi.com/api-reference