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.
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 is optional.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

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 -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"
  }'

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, ... }

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

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$kua = $roxy->fengShui->calculateKuaNumber(
    date: '1990-07-15',
    gender: 'female',
);
echo $kua['kua'], ' ', $kua['group'];

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

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,
    })

claude mcp add-json --scope user roxy-feng-shui '{"type":"http","url":"https://roxyapi.com/mcp/feng-shui","headers":{"X-API-Key":"YOUR_KEY"}}'

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.

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.

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:

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.

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 (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.

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 (generateFlyingStarChart) builds the nine-palace chart for a building. Send period (defaults to the period in force now) plus a direction:

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} (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 (getMonthlyFlyingStars) is the same shape for a year and month.

The four annual afflictions

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.

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} (getKuaNumber) returns one Kua in full with no birth data, which is what backs the nine static Kua pages.
• GET /feng-shui/bagua (listBaguaSectors) and 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 (listFlyingStars) is the nine-star reference the charts link to.
• 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.

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:

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:

<div class="bagua-ring">
  <!-- one cell per sector, in the order the API returns them -->
  <div class="sector ${s.nature}" data-dir="${s.direction}">
    <b>${s.direction}</b>
    <span>${s.starName}</span>
    <small>${s.domain}</small>
  </div>
</div>

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.

<div class="flying-star">
  <div class="palace" data-palace="${p.palace}">
    <span class="mountain">${p.mountain}</span>
    <span class="base">${p.base}</span>
    <span class="water">${p.water}</span>
  </div>
</div>

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.

Reply in the user language

Every endpoint here accepts ?lang=, in 10+ languages including both Chinese scripts, zh-Hant and zh-Hans.

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:

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

Ready-made starter

There is no feng-shui-only template yet. The flagship 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. For a custom build, the Next.js integration guide is the fastest path.

What to build next

• The Chinese astrology guide 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 shows the Kua number joining the natal chart, kundli, bodygraph, BaZi and numerology in one cached payload.
• The caching guide covers the cache-forever versus refresh-annually split this domain has.
• The AI chatbot tutorial shows tool registration so users can ask "which way should my desk face" in natural language.