Feng Shui API Evaluation: 10 Checks Before You Build

Feng shui looks like content until you try to compute it. Then it becomes a small, unforgiving calculation with several places to be quietly wrong, and none of them raise an error. A feng shui API can return a well formed object, nine sectors, nine numbers and sensible prose, and still be describing a building that does not exist.

The failure is rarely arithmetic. It is usually a missing input. A chart cast without a period is not a chart. A grid with one number per sector has merged three layers into one and discarded the two a practitioner actually reads. A Kua number taken from the calendar year is wrong for everyone born in January.

This is a checklist you can run against any provider, including this one. Every check is answerable from one request, and the answer sits in the response body rather than in the marketing copy.

What a flying star natal chart has to contain before it is usable

A flying star natal chart is determined by two facts about a building: the twenty year period it was completed in, and the exact direction its front faces, resolved to one of twenty four compass mountains of fifteen degrees each. Those two inputs produce a nine palace grid, and each palace carries several numbers rather than one.

The number most readers see quoted, the annual star, is a separate layer that changes every February, and it is the cheapest to compute. The two that carry the analysis are the mountain star, read for health, occupants and relationships, and the water star, read for money and anything arriving from outside. They are separate plates, seeded from different palaces, and they often fly in opposite directions.

Ready to build this? The Feng Shui API returns all three plates plus the structure verdict in one call. See pricing.

Ten checks to run against any feng shui API

Ordered so the cheapest come first. A provider that fails the first two cannot pass the rest, whatever the docs say.

1. Does the chart come from a period and a facing, or only from a year? The period is the twenty year cycle the building was completed in, and it is fixed for the life of the building. If the request takes a year, an address, or a room name and no period, whatever comes back is not a natal chart.
2. Are the plates separate per palace, and does each plate hold all nine stars exactly once? One number per sector means the layers were merged. The nine stars appearing exactly once on each plate is the structural property that makes a chart checkable, and it is one jq line.
3. Is the flight direction of each plate published? Each plate enters the centre and then flies forward or in reverse across the palaces, and the direction is decided by the yin or yang nature of the mountain the centre star answers to. That one bit turns the same pair of centre numbers into two different grids. Lineages differ on the seeding rules, so a chart that does not say which way it flew cannot be reconciled against the one a practitioner drew.
4. Does the response carry the structure verdict? The classical read of a chart is which of four arrangements it landed in: both prosperous stars where they belong, both reversed, both at the front, or both at the back. That verdict is what a consultation is built on, and it is not recoverable from a grid image.
5. Does the verdict obey the law of its period? Not every period can produce every structure. Cast all twenty four facings for one period and count the results. If the counts are impossible for that period, the engine is generating grids rather than computing them.
6. Does a bearing near a mountain boundary get flagged? The mountains are fifteen degrees wide. A bearing within roughly three degrees of a boundary is where part of the tradition switches to a different construction entirely, and where a two degree compass error changes the whole chart. Silence here is the most expensive silence in the domain.
7. Can you cast a chart for any of the nine periods, not just the one in force? Most existing buildings are not from the current period. An API that knows only the current one cannot analyse the housing stock its users live in.
8. Does the annual chart state the date it changes over? The feng shui year starts neither on 1 January nor at Chinese New Year. Without a changeover date in the response, you cannot tell which year a caller is in during the first weeks of February.
9. Is the raw Kua published before the gender reassignment? One Kua value has no trigram of its own and is reassigned by gender, so two users born in the same year get different directions. If only the final number comes back, you cannot explain the result to a user who checked it against a book.
10. Does the response come back in the language your users read, and does the machine-readable half stay stable? Translated prose is table stakes for a consumer app. What matters more to your code is that identifiers, sector names and verdict keys do not translate with it, so logic written against the English response keeps working under every locale.

How to read all three plates from one request

One POST returns the whole chart. POST /feng-shui/flying-stars/natal takes a period from 1 to 9 and a facing, given as one of the twenty four mountain ids or as a compass label such as S2. Send facingDegrees instead when you have a real bearing. No coordinates, no birth data, no account state.

curl -s -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 { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.fengShui.generateFlyingStarChart({
  body: { period: 9, facing: 'wu' },
});
console.log(data.structure.id, data.mountainFlight, data.waterFlight);

from roxy_sdk import create_roxy

roxy = create_roxy("your-api-key")

chart = roxy.feng_shui.generate_flying_star_chart(period=9, facing="wu")
print(chart["structure"]["id"], chart["mountainFlight"], chart["waterFlight"])

Trimmed to the fields this section is about, the response looks like this:

{
  "period": 9,
  "facing": { "id": "wu", "label": "S2", "direction": "South", "polarity": "yin", "startDegree": 172.5, "endDegree": 187.5 },
  "sitting": { "id": "zi", "label": "N2", "direction": "North", "polarity": "yin" },
  "straddling": false,
  "mountainCenterStar": 5,
  "waterCenterStar": 4,
  "mountainFlight": "reverse",
  "waterFlight": "forward",
  "structure": { "id": "double-sitting", "name": "Double Star at Sitting", "chinese": "雙星到坐" },
  "palaces": [
    { "palace": "Center", "base": 5, "period": 9, "mountain": 5, "water": 4 },
    { "palace": "North",  "base": 1, "period": 5, "mountain": 9, "water": 9 },
    { "palace": "South",  "base": 9, "period": 4, "mountain": 1, "water": 8 }
  ]
}

The plates fly in opposite directions here, reverse for the mountain and forward for the water, from centre numbers that differ by one. Check 2 is a single line against the same call:

... | jq '[.palaces[].mountain] | sort'
# [1,2,3,4,5,6,7,8,9]

Swap .mountain for .water and you get the same nine. Add ?lang=es or ?lang=zh-Hant to the URL and structure.id stays double-sitting, palace stays North, and facing.direction stays South, while the reading and the formation names arrive in the requested language.

Why the same building gets a different chart in Period 9

Period is not a detail. Here is the same facing, S2, cast in the two most common periods for existing buildings, with the palaces trimmed to the front and the back of the house:

The prosperous pair moves from the front of the building to the back, and the whole recommendation inverts with it. Period 8 ran from February 2004 to February 2024 and Period 9 runs from 4 February 2024 to 2043, so a building finished in January 2024 is still a Period 8 building and one finished in March 2024 is not.

GET /feng-shui/periods returns the full nine period table with cycleStartYear 1864, cycleEndYear 2043 and currentPeriod, which dates every chart you cast:

{
  "cycleStartYear": 1864,
  "cycleEndYear": 2043,
  "currentPeriod": 9,
  "periods": [
    {
      "number": 9,
      "startYear": 2024,
      "endYear": 2043,
      "startDate": "2024-02-04",
      "rulingStar": 9,
      "rulingStarName": "Nine Purple",
      "element": "Fire",
      "palace": "South"
    }
  ]
}

What the period tells you a chart cannot be

Check 5 is the fastest way to tell a real chart engine from a plausible one. The four structures are not equally available in every period. In some the twenty four facings split evenly into all four. In others, two of the four cannot occur at all, and a response claiming one of them is not a near miss but an impossibility.

for m in N1 N2 N3 NE1 NE2 NE3 E1 E2 E3 SE1 SE2 SE3 \
         S1 S2 S3 SW1 SW2 SW3 W1 W2 W3 NW1 NW2 NW3; do
  curl -s -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\": \"$m\"}" | jq -r '.structure.id'
done | sort | uniq -c
#   12 double-facing
#   12 double-sitting

Run the same loop with "period": 8 and the twenty four split six, six, six and six across all four structures. Twenty four requests settle in one minute a question no feature table answers.

What the year boundary does to a Kua number

The Kua number is the entry point to the personal half of feng shui, and the arithmetic looks trivial enough that the boundary is where implementations go wrong. The solar year it uses begins at the start of spring in early February, not on 1 January and not at Chinese New Year, so every birthday in January and early February belongs to the previous year.

POST /feng-shui/kua takes a date and a gender, and accepts an optional yearBoundary of li-chun or lunar-new-year. The same birth date under the two conventions:

{ "kua": 2, "rawKua": 2, "reassigned": false, "group": "west",
  "solarYear": 1989, "boundaryDate": "1990-02-04",
  "conventions": { "yearBoundary": "li-chun" } }

{ "kua": 1, "rawKua": 1, "reassigned": false, "group": "east",
  "solarYear": 1990, "boundaryDate": "1990-01-27",
  "conventions": { "yearBoundary": "lunar-new-year" } }

One birth date, 30 January 1990, two groups, and every favourable direction in the app flips with it. The response names the convention it used and the boundary date it compared against, so the disagreement is visible instead of silent. The gender reassignment is published the same way: a male born in 1995 returns rawKua 5 with kua 2, a female born in 1990 returns rawKua 5 with kua 8, and reassigned is true on both.

GET /feng-shui/flying-stars/annual/{year} and GET /feng-shui/afflictions/{year} carry the same boundary discipline, returning a changeoverDate of 2027-02-04 for 2027 beside the annual centre star and the four afflictions with their exact fifteen degree mountains.

When a bearing near a boundary needs a specialist, not an API

Each mountain spans fifteen degrees. A bearing in the central nine is unambiguous. A bearing in the outer three degrees on either side sits at a boundary where a small compass error moves the chart, and where part of the tradition switches to a different construction rather than the standard one. That is not a rounding problem, it is a different chart.

This is an honest limit of the domain rather than a gap to be patched. Naming a mountain instead of a bearing always returns straddling: false, because naming a mountain expresses no bearing at all. If your users type compass readings from a phone, that flag is the difference between an app that knows what it does not know and one that guesses.

FAQ

What is a flying star natal chart?

A flying star natal chart is the permanent chart of a building, fixed by the twenty year period it was completed in and the exact compass direction its front faces. It divides the building into nine palaces, each carrying a mountain star read for health and relationships and a water star read for wealth. RoxyAPI returns all nine palaces, both plates and the classical structure verdict from one request to POST /feng-shui/flying-stars/natal.

How do I calculate a flying star chart with an API?

Send a period from 1 to 9 and a facing, either as one of the twenty four mountain ids or as a compass bearing in degrees. The RoxyAPI endpoint answers with the nine palaces, the centre stars of both plates, the direction each plate flew, a boundary flag on the bearing and a reading per palace. No coordinates, no birth data and no stored state are involved.

Does Period 9 change my flying star chart?

The natal chart of an existing building does not change when the period turns over, but the meaning of every star in it does, because the ruling star moved from 8 to 9 on 4 February 2024. Buildings completed after that date are cast in Period 9 and get a different grid from the same facing. RoxyAPI casts any of the nine periods, and GET /feng-shui/periods returns the full 1864 to 2043 table with the current period.

When do the annual flying stars change each year?

The feng shui year turns over at the start of spring in early February rather than on 1 January or at Chinese New Year, so the annual chart and the annual afflictions change on a date near 4 February. RoxyAPI publishes it as changeoverDate on both the annual flying stars endpoint and the annual afflictions endpoint, so your application never has to assume it.

Is there a feng shui API with Kua numbers and flying stars together?

Yes. RoxyAPI covers the flying star natal chart, the annual and monthly overlays, the annual afflictions, Kua numbers, the full Eight Mansions map, the compass bagua and the nine period table on one key, answering in 10+ languages including Simplified and Traditional Chinese. It sits alongside 209+ endpoints across 14 domains in the same subscription, with typed SDKs and a Remote MCP server.

Conclusion

Feng shui is small enough to verify and specific enough that a wrong answer stays invisible until a practitioner sees it, so run the checks rather than read the feature table. The Feng Shui API answers all ten in the open, and the 8 trigrams of the bagua are a good place to start if the vocabulary is new.