Flying stars (玄空飛星)

Xuan Kong Fei Xing (玄空飛星) is the school of feng shui that casts a chart for a building rather than for a person. Two things are enough, and both are required: the period the building was occupied in, and the direction it faces. From those come three numbers for each of nine sectors.

Three stars in every palace

Star	中文	What it is read for
Mountain	山星	People, health, relationships
Period	運星	The era the building belongs to
Facing	向星	Money, opportunity, movement

The numbers and their flight are exact arithmetic. What a pair of numbers means in a particular room is an interpretive tradition with more than one school. The response keeps those two halves apart, and notes says where the calculation ends.

Endpoints

Endpoint	Credits	What it returns
POST /v1/chinese/feng-shui/flying-star	10	The building’s natal chart: nine palaces, the chart type, the special patterns
POST /v1/chinese/feng-shui/annual-stars	10	The annual stars and the year’s afflictions, optionally the monthly layer

Caution

The period has no default. Without period or occupiedDate the request comes back 400. A building occupied in 1998 belongs to period 7, and a confident period-9 chart for it would simply be the wrong answer wearing the right shape.

Example

cURL

curl -X POST https://api.astroway.info/v1/chinese/feng-shui/flying-star \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "period": 8, "facing": 180, "year": 2026 }'

Node

const res = await fetch('https://api.astroway.info/v1/chinese/feng-shui/flying-star', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.ASTROWAY_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ occupiedDate: '2011-06-01', facingMountain: 'S2' }),
});
const { data } = await res.json();
console.log(data.chartType.id, data.palaces.find((p) => p.palace === 'S').pair);

Give the direction either as degrees clockwise from true north (facing: 180) or as one of the 24 mountains by code (S2), pinyin (Wu) or character (午). The period works the same way: a number (period: 8) or the date of occupation (occupiedDate), in which case the year is taken from the exact Li Chun instant rather than a fixed 4 February.

Chart type

Four canonical arrangements, and the answer names the one that came out:

id	中文	Reading
wang-shan-wang-shui	旺山旺水	The most favoured: people behind, money in front
shang-shan-xia-shui	上山下水	The reverse, and the case where a practitioner asks about the landform outside
double-facing	雙星到向	Both stars in front: good for money, wants support behind
double-sitting	雙星到坐	Both behind: good for people, wants water in front

What was verified, and against what

The flight rule is stated wrongly more often than rightly. A star is not sent forward or backward by the polarity of the mountain the building faces, but by the polarity of the mountain at the same ordinal position inside the sector belonging to the flying star’s own trigram.

The naive reading reproduces 6 of the 24 published period-8 charts and fails 18. One or two spot checks would have blessed it, so the whole published set sits in the tests: 24 charts, 9 palaces, 3 stars, 648 numbers, all matching.

Star 5 has no trigram of its own and borrows the period star’s polarity. The other common version, “the polarity of the palace it came from”, is the same version: 5 always lands in the palace whose Lo Shu number is 10 − period, and that always shares the period’s parity. Proved for all nine periods rather than left as a caveat.

Note

替卦, the replacement stars, are deliberately absent. Some schools apply them when a reading falls near a mountain boundary. It changes the chart, and the schools disagree on when it applies. Rather than choose quietly, the answer warns you: a reading within 1.5° of a boundary comes back with the distance and the neighbouring mountain in warnings.

Annual stars and afflictions

POST /v1/chinese/feng-shui/annual-stars returns the nine annual stars and four or five afflictions. The difference between them matters to anyone about to act:

• Tai Sui (太歲) and Sui Po (歲破) are one 15° mountain each.
• San Sha (三煞) is a whole 45° sector.
• Five Yellow (五黃) and Two Black (二黑) are sectors of the annual chart.

For 2026 the answer puts the five yellow in the south, Tai Sui at S2 (午), Sui Po at N2 and San Sha in the north, which is what the published almanacs say; those four are pinned by a test.

The year here is solar and turns at Li Chun. A January date belongs to the previous year, which is exactly why nothing is defaulted: without year or date you get a 400.

What sits next to it

The rest of the feng shui surface was already in the API and is unchanged: POST /v1/chinese/feng-shui/kua (the Kua number), /lucky-directions (the eight personal directions) and /bagua (the map of nine life areas).