# Feng Shui API, what to build and how to call it > Ship a Kua number calculator, an Eight Mansions direction finder, a flying star chart, or an annual afflictions page in under 30 minutes. No consultant training required. Feng shui is a full domain in the RoxyAPI catalog. 11 endpoints covering the Kua number, the Eight Mansions (Ba Zhai) map, flying star charts by period and facing, the annual and monthly star overlays, the four annual afflictions, the Later Heaven bagua, the nine flying stars, and the nine-period cycle. Everything is classical compass-school method, computed rather than looked up, and available in 10+ languages on one key. Whether you need a Kua number calculator, a flying star chart, a bagua map overlay or an annual afflictions page, it is one key and one domain. ## What you can build - Kua number calculators (personal number, east or west group, the trigram, the four good and four bad directions) - Bed, desk, and door placement tools (Eight Mansions map, ranked best to worst) - Flying star chart generators (nine palaces with base, mountain, and water stars, plus the chart structure) - Annual feng shui pages (the star that rules the year, and where the four afflictions sit) - Monthly overlay widgets for publishers on a monthly cadence - Bagua map overlays for floor plans (nine life areas, colours, elements, trigrams) - Period 9 explainers and renovation timing tools (the nine-period cycle to 2043) - Room-by-room reports, combining a personal Kua with a building flying star chart ## Prerequisites 1. A RoxyAPI key from [/account](/account). 2. For anything personal: a birth `date` (YYYY-MM-DD) and a `gender` of `male` or `female`, which selects the Kua formula variant. No birth time and no birth place needed. 3. For a flying star chart: the building `period` (1 to 9) and which way it faces. Facing is either `facingDegrees` (a compass bearing 0 to 360, taken looking out from inside) or `facing` (one of the 24 mountains, by id such as `wu` or by label such as `S2`). 4. Nothing else. There is no location lookup in this domain, so [`GET /location/search`](/api-reference#tag/location-and-timezone/GET/location/search) is optional. ## Install ### npm ```bash npm install @roxyapi/sdk ``` ### Python ```bash pip install roxy-sdk ``` ### PHP ```bash composer require roxyapi/sdk ``` ### .NET CLI ```bash dotnet add package RoxyApi.Sdk ``` ### Go ```bash go get github.com/RoxyAPI/sdk-go ``` ## Call the endpoint The #1 feng shui call is the Kua number. One POST turns a birth date into the personal number that every other reading in the domain is built on, plus all eight compass sectors ranked and classified. Verified operationId: `calculateKuaNumber`. ### curl ```bash curl -X POST https://roxyapi.com/api/v2/feng-shui/kua \ -H "X-API-Key: $ROXY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "date": "1990-07-15", "gender": "female" }' ``` ### TypeScript SDK ```typescript import { createRoxy } from '@roxyapi/sdk'; const roxy = createRoxy(process.env.ROXY_API_KEY!); const { data: kua } = await roxy.fengShui.calculateKuaNumber({ body: { date: '1990-07-15', gender: 'female' }, }); console.log(kua.kua); // 8 console.log(kua.rawKua); // 5 <- before the reassignment rule console.log(kua.reassigned); // true console.log(kua.group); // "west" console.log(kua.solarYear); // 1990 console.log(kua.boundaryDate); // "1990-02-04" console.log(kua.trigram.english); // "Mountain" console.log(kua.sectors.length); // 8 console.log(kua.sectors[5]); // { direction: "Southwest", star: "sheng-chi", nature: "auspicious", rank: 1, ... } ``` ### Python SDK ```python import os from roxy_sdk import create_roxy roxy = create_roxy(os.environ['ROXY_API_KEY']) kua = roxy.feng_shui.calculate_kua_number(date='1990-07-15', gender='female') print(kua['kua'], kua['group'], kua['trigram']['english']) print([s['direction'] for s in kua['sectors'] if s['nature'] == 'auspicious']) ``` ### PHP SDK ```php fengShui->calculateKuaNumber( date: '1990-07-15', gender: 'female', ); echo $kua['kua'], ' ', $kua['group']; ``` ### C# SDK ```csharp using RoxyApi; using Microsoft.Kiota.Abstractions; // for the Date type using RoxyApi.FengShui.Kua; var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!); var kua = await roxy.FengShui.Kua.PostAsync(new() { Date = new Date(1990, 7, 15), Gender = KuaPostRequestBody_gender.Female, }); Console.WriteLine(kua!.Kua); // 8 Console.WriteLine(kua.Group); // "west" Console.WriteLine(kua.Trigram!.English); // "Mountain" Console.WriteLine(kua.Sectors!.Count); // 8 ``` ### Go SDK ```go import ( "context" "time" roxyapi "github.com/RoxyAPI/sdk-go" ) roxy, _ := roxyapi.NewRoxy("YOUR_API_KEY") kua, _ := roxy.FengShui.CalculateKuaNumber(context.Background(), nil, roxyapi.CalculateKuaNumberJSONRequestBody{ Date: roxyapi.Date(1990, time.July, 15), Gender: roxyapi.CalculateKuaNumberJSONBodyGenderFemale, }) ``` ### MCP ```bash claude mcp add-json --scope user roxy-feng-shui '{"type":"http","url":"https://roxyapi.com/mcp/feng-shui","headers":{"X-API-Key":"YOUR_KEY"}}' ``` Then in any MCP client: "what is the Kua number for a woman born 15 July 1990, and which direction should her desk face?" The agent calls the Kua number tool and reads the top-ranked auspicious sector. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp). ## Read the response `sectors` is the payload that matters. All eight compass directions come back at once, each classified and ranked, so you never have to hold a lookup table of your own. | Field | What it is | |---|---| | `kua` | The number used for every reading, 1 to 9 with 5 never appearing | | `rawKua` | The arithmetic result before the reassignment rule. `5` here means the number moved | | `reassigned` | `true` when `rawKua` was 5 and got moved. Use it to explain the result to a user | | `group` | `east` or `west`. Decides which four directions are the good ones | | `trigram` | The personal trigram: `chinese`, `english`, `pinyin`, `symbol`, `element`, `direction`, `familyMember` | | `sectors[]` | Eight objects: `direction`, `star`, `starName`, `nature`, `rank`, `domain` | | `solarYear` and `boundaryDate` | The solar year actually used, and the Li Chun date that decided it | | `conventions` | The `yearBoundary` this result was computed with | `nature` is `auspicious` or `inauspicious`, and `rank` is 1 to 4 **within** that group. So a sector with `nature: "auspicious"` and `rank: 1` is the single best direction, while `nature: "inauspicious"` and `rank: 1` is the mildest of the four bad ones, which is the compromise to take when no good sector is reachable. Rank is never a score across all eight, and reading it as one is the most common mistake in this domain. ```typescript const best = kua.sectors.find((s) => s.nature === 'auspicious' && s.rank === 1); const fallback = kua.sectors.find((s) => s.nature === 'inauspicious' && s.rank === 1); ``` ## The year starts at Li Chun, not on 1 January This is the rule most people get wrong when they work a Kua number out by hand, and the one your support inbox will ask about. The feng shui year turns at Li Chun, the solar term in early February, so a birthday in January belongs to the **previous** solar year. The response tells you which year it used and the exact boundary it applied: ```bash curl -X POST https://roxyapi.com/api/v2/feng-shui/kua \ -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \ -d '{"date":"2000-01-20","gender":"male"}' # => kua 1, group "east", solarYear 1999, boundaryDate "2000-02-04" ``` A birth on 20 January 2000 is a 1999 birth for this purpose. Pass `yearBoundary: "lunar-new-year"` if you need to match a tool that uses the folk convention instead, and the `conventions` object echoes whichever you chose. **Tip: Surface `solarYear` in your UI** When a user says your number disagrees with another site, `solarYear` and `boundaryDate` answer it in one line without you having to recompute anything. The other rule worth knowing: a raw Kua of 5 has no trigram of its own, so it gets reassigned, and the two formula variants do not send it to the same place. A raw 5 becomes **2** under the `male` formula and **8** under the `female` one. That is exactly what `rawKua` and `reassigned` are for: the first call in this guide returns `kua: 8` from `rawKua: 5`, so your copy can show the user the step instead of asserting a number they cannot check. ## Ship the rest ### The Eight Mansions map, ranked [`POST /feng-shui/eight-mansions`](/api-reference#tag/feng-shui/POST/feng-shui/eight-mansions) (`generateEightMansions`) is the full Ba Zhai map. It accepts either a `kua` you already have, or a `date` plus `gender` to derive one, so you never need two round trips. It adds what the Kua endpoint does not carry: a composed `reading` per sector, the trigram on each sector, and `bestSector` and `worstSector` at the top level. ```bash curl -X POST https://roxyapi.com/api/v2/feng-shui/eight-mansions \ -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \ -d '{"kua":7,"facing":"South"}' # => bestSector "Northwest", worstSector "East", # facingSector { direction: "South", star: "wu-gui", nature: "inauspicious" } ``` Optional `facing` here is one of the eight compass sectors (`North` through `Northwest`, capitalised), and it makes the response name the star sitting on the door you care about. That is a different parameter from the `facing` on the flying star endpoint below, which takes one of the 24 mountains. ### Flying star natal chart, the deepest call in the domain [`POST /feng-shui/flying-stars/natal`](/api-reference#tag/feng-shui/POST/feng-shui/flying-stars/natal) (`generateFlyingStarChart`) builds the nine-palace chart for a building. Send `period` (defaults to the period in force now) plus a direction: ```bash 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":"S2"}' ``` The response carries `facing` and `sitting` as full mountain objects (id, Chinese character, label, degree span), `mountainCenterStar` and `waterCenterStar`, the flight direction of each (`forward` or `reverse`), a `structure` naming the classical chart type, and nine `palaces` each with `base`, `period`, `mountain`, `water` and a composed `reading`. `straddling` flags a bearing sitting on a mountain boundary, which is the case a practitioner would re-measure rather than trust. **Read the two star layers differently.** The mountain star governs health, the people in a room and the relationships between them. The water star governs money, opportunity and what arrives from outside. Most of the interpretation in this method is what those two do to each other in one palace. ### Annual and monthly overlays - [`GET /feng-shui/flying-stars/annual/{year}`](/api-reference#tag/feng-shui/GET/feng-shui/flying-stars/annual/{year}) (`getAnnualFlyingStars`) returns `centerStar`, the `changeoverDate`, and the nine palaces with the star, element, nature, enhancer and remedy for each. This is the annual refresh every feng shui site publishes. - [`GET /feng-shui/flying-stars/monthly`](/api-reference#tag/feng-shui/GET/feng-shui/flying-stars/monthly) (`getMonthlyFlyingStars`) is the same shape for a `year` and `month`. ### The four annual afflictions [`GET /feng-shui/afflictions/{year}`](/api-reference#tag/feng-shui/GET/feng-shui/afflictions/{year}) (`getAnnualAfflictions`) returns Tai Sui, Sui Po, San Sha and the Five Yellow: the four that every annual feng shui article is built around, and the four a renovation-timing feature has to check. ```bash curl https://roxyapi.com/api/v2/feng-shui/afflictions/2026 \ -H "X-API-Key: $ROXY_API_KEY" ``` Each affliction carries its own directional rule, and they are not the same rule. Tai Sui asks you to sit with your back to it and never face it. San Sha is the reverse: facing it is safe, sitting with your back to it is not. San Sha also comes back as a 75 degree span with three named `parts`, rather than a single direction, so a UI that draws one arrow for it is drawing the wrong shape. ### The catalogs - [`GET /feng-shui/kua/{number}`](/api-reference#tag/feng-shui/GET/feng-shui/kua/{number}) (`getKuaNumber`) returns one Kua in full with no birth data, which is what backs the nine static Kua pages. - [`GET /feng-shui/bagua`](/api-reference#tag/feng-shui/GET/feng-shui/bagua) (`listBaguaSectors`) and [`GET /feng-shui/bagua/{id}`](/api-reference#tag/feng-shui/GET/feng-shui/bagua/{id}) (`getBaguaSector`) return the Later Heaven bagua: `career`, `knowledge`, `family`, `wealth`, `fame`, `love`, `children`, `helpful-people` and `health`, each with its palace, element, colours, trigram and focus. - [`GET /feng-shui/flying-stars/stars`](/api-reference#tag/feng-shui/GET/feng-shui/flying-stars/stars) (`listFlyingStars`) is the nine-star reference the charts link to. - [`GET /feng-shui/periods`](/api-reference#tag/feng-shui/GET/feng-shui/periods) (`listNinePeriods`) returns the full 1864 to 2043 cycle plus `currentPeriod`, so a UI can date a building without shipping the table itself. See the full domain at the [API Reference](/api-reference#tag/feng-shui). ## We are in Period 9 `GET /feng-shui/periods` returns `currentPeriod: 9`, running `2024-02-04` to 2043, ruling star Nine Purple, element Fire, palace South, inside the 1864 to 2043 cycle. A great deal of feng shui content on the web still assumes Period 8, which ended in early 2024, so a chart cast from a Period 8 assumption is now wrong for any building completed since. Read the period from the endpoint rather than hardcoding it, and your app stays correct through the next changeover without a deploy: ```typescript const { data: periods } = await roxy.fengShui.listNinePeriods(); const { data: chart } = await roxy.fengShui.generateFlyingStarChart({ body: { period: periods.currentPeriod, facingDegrees: 180 }, }); ``` Note what `period` means: the twenty-year cycle the building was **completed** in, or last renovated heavily enough to reset. It is fixed for the life of the building, so a house finished in January 2024 is a Period 8 house even though we are in Period 9 now. ## Render the result Both of the main shapes are simple grids, and the response maps onto them directly. The Eight Mansions map is an eight-cell compass ring keyed by `direction`: ```html
${s.direction} ${s.starName} ${s.domain}
``` The flying star chart is a 3 by 3 grid of `palaces`, each cell showing three numbers: mountain on the left, base in the centre, water on the right. ```html
${p.mountain} ${p.base} ${p.water}
``` `nature`, `direction` and `palace` are canonical English in every language, so they are safe as CSS class names and data attributes. For ready-made chart rendering, see the component catalog in [`@roxyapi/ui`](/docs/ui). ## Reply in the user language Every endpoint here accepts `?lang=`, in 10+ languages including both Chinese scripts, `zh-Hant` and `zh-Hans`. ```bash curl -X POST "https://roxyapi.com/api/v2/feng-shui/kua?lang=zh-Hans" \ -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \ -d '{"date":"1990-07-15","gender":"female"}' ``` Machine-readable identifiers never translate: `star` stays `"wu-gui"`, `nature` stays `"inauspicious"`, `group` stays `"west"`, `direction` stays `"Northwest"`. Translated display text arrives in a sibling field named `*Localized`, present only when you pass `lang`: ```typescript const label = sector.starNameLocalized ?? sector.starName; // "五鬼" with lang=zh-Hans, else "Wu Gui" if (sector.nature === 'auspicious') { /* always safe, in every language */ } ``` Branch on the canonical field, render the localized one. ## Gotchas - **`rank` is within `nature`, not across all eight.** Rank 1 auspicious is the best direction; rank 1 inauspicious is the least bad one. Filter on `nature` first, then sort. - **Two endpoints, two different `facing` parameters.** Eight Mansions takes a capitalised compass sector (`"South"`). Flying stars takes one of the 24 mountains (`"wu"` or `"S2"`). Sending the wrong vocabulary returns 400 with the accepted values listed. - **A flying star chart needs a direction.** Send `facing` or `facingDegrees`. Sending neither returns 400, on purpose: a chart cannot be cast without one, and defaulting would silently produce a chart for a building that is not yours. - **Measure facing looking out from inside.** The facing side is the open, active, public side of a building, which is not always the side with the front door. - **`straddling: true` means the bearing sits on a mountain boundary.** Show it. It is the case where a real consultant would re-measure rather than trust a reading. - **Kua 5 never appears in `kua`.** It appears in `rawKua`, and `reassigned` tells you it moved. Do not write a nine-way switch that includes a 5 branch. - **`gender` selects a formula variant, not an identity.** It picks the arithmetic and the reassignment rule. Label the input in your UI however suits your users, and pass `male` or `female` to the API. - **The Center has no direction and no trigram.** `GET /feng-shui/bagua` returns 9 sectors, not 8: the eight compass sectors plus `health` at the Center. On that one, `direction` and `trigram` are ABSENT rather than null, so they read as `undefined`: a truthiness check catches it, `=== null` does not. A loop that assumes every sector has a compass direction will drop it or crash on it. - **Everything in this domain is cache-forever except the overlays.** A Kua number, an Eight Mansions map and a natal flying star chart never change. The annual and monthly stars and the afflictions change on a schedule you already know: the annual ones at Li Chun, in early February. - **Every call bills at a flat 1 request.** REST and Remote MCP are identical, with no per-domain fees. ## Frequently asked questions ### What is a Kua number and how is it calculated? A Kua number, also called a Ming Gua, is a number from 1 to 9 (never 5) derived from a birth year, that assigns a person to the east or west group and fixes their four favourable and four unfavourable compass directions. `POST /feng-shui/kua` returns it from a birth date plus a formula selector, along with all eight sectors ranked and the personal trigram. ### Why does my Kua number differ from another calculator? Two reasons, and the response answers both. The feng shui year starts at Li Chun in early February, so a January birthday belongs to the previous solar year, and `solarYear` plus `boundaryDate` show which year was used. Separately, a raw result of 5 has no trigram and is reassigned, and the two formula variants send it to different numbers: a raw 5 becomes 2 under the male formula and 8 under the female one. `rawKua` and `reassigned` show whether that happened to a given result. ### Can I generate a flying star chart from a compass reading? Yes. `POST /feng-shui/flying-stars/natal` takes `facingDegrees` as a bearing from 0 to 360 measured looking out from inside, resolves it to one of the 24 mountains, and returns the nine palaces with base, mountain and water stars plus the chart structure. Send `facing` instead if you already know the mountain by id or label. ### What feng shui period are we in now? Period 9, which began on 4 February 2024 and runs to 2043. Its ruling star is Nine Purple, element Fire, in the South palace. `GET /feng-shui/periods` returns the current period and the full 1864 to 2043 cycle, so read it from the API rather than hardcoding it. ### Which directions should I avoid this year? That is the annual afflictions call: `GET /feng-shui/afflictions/{year}` returns Tai Sui, Sui Po, San Sha and the Five Yellow with their positions and their individual rules. They are not one rule: Tai Sui should be at your back and never faced, while San Sha is the opposite, and San Sha occupies a 75 degree span rather than a single direction. ### Do I need a birth time or birth place for feng shui? No. The personal calls need a birth date and a formula selector only, and the building calls need a period and a facing direction. That makes this the lightest domain in the catalog to collect input for, and the easiest to add to an existing signup flow. ## Ready-made starter There is no feng-shui-only template yet. The flagship [astrology-ai-chatbot](https://github.com/RoxyAPI/astrology-ai-chatbot) template connects this domain by default over Remote MCP, so cloning it gives you a working Kua and flying star chatbot with no wiring; browse the catalog at [/starters](/starters). For a custom build, the [Next.js integration guide](/docs/integrations/nextjs) is the fastest path. ## What to build next - The [Chinese astrology guide](/docs/guides/chinese-astrology) covers the other half of Chinese metaphysics: BaZi Four Pillars, the zodiac, the lunisolar calendar and the Tong Shu almanac. The two domains share the same Li Chun year boundary and the same five elements. - The [complete birth profile tutorial](/docs/tutorials/complete-birth-profile) shows the Kua number joining the natal chart, kundli, bodygraph, BaZi and numerology in one cached payload. - The [caching guide](/docs/guides/caching) covers the cache-forever versus refresh-annually split this domain has. - The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows tool registration so users can ask "which way should my desk face" in natural language.