# 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 |

<Aside type="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.
</Aside>

## Example

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    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 }'
    ```
  </TabItem>
  <TabItem label="Node">
    ```js
    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);
    ```
  </TabItem>
</Tabs>

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.

<Aside type="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`.
</Aside>

## 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).