Feng Shui API
Flying star charts that are actually checkable.
Flying StarKua NumberEight MansionsAnnual AfflictionsBagua Map …and so much more
Start building in seconds.
Want to try without writing code? Try this domain live in API playground →
npm install @roxyapi/sdkimport { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.fengShui.get(/* ... */)pip install roxy-sdkfrom roxy_sdk import create_roxy
roxy = create_roxy("your-api-key")
result = roxy.feng_shui.get(...) # async: await roxy.feng_shui.get_async(...)composer require roxyapi/sdkuse function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->fengShui->get(/* ... */);dotnet add package RoxyApi.Sdkusing RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
// await roxy.FengShui.<resource>.GetAsync() or .PostAsync(new() { ... })go get github.com/RoxyAPI/sdk-goimport roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
// resp, err := roxy.FengShui.<Method>(context.Background(), nil)curl -H "X-API-Key: YOUR_KEY" \
https://roxyapi.com/api/v2/feng-shui/claude mcp add --transport http \
roxy-feng-shui https://roxyapi.com/mcp/feng-shui \
--header "X-API-Key: YOUR_KEY"AI agents auto-discover all endpoints as callable tools. Zero configuration. Responses can come back token-optimized and lossless, cutting the tokens your agent spends per call by roughly 40 to 52 percent.
Want to ship faster? Clone a free template and go from zero to production in 30 minutes.
Building with Cursor, Claude Code, or Bolt? Use our AI prompts to generate a complete app in minutes.
Building on WordPress? Install the RoxyAPI plugin and drop a shortcode, no code required.
{
"period": 9,
"facing": {
"id": "wu",
"chinese": "午",
"pinyin": "Wǔ",
"label": "S2",
"direction": "South",
"yuan": "heaven",
"polarity": "yin",
"startDegree": 172.5,
"endDegree": 187.5
},
"sitting": {
"id": "zi",
"chinese": "子",
"pinyin": "Zǐ",
"label": "N2",
"direction": "North",
"yuan": "heaven",
"polarity": "yin",
"startDegree": 352.5,
"endDegree": 7.5
},
"straddling": false,
"mountainCenterStar": 5,
"waterCenterStar": 4,
"mountainFlight": "reverse",
"waterFlight": "forward",
"structure": {
"id": "double-sitting",
"name": "Double Star at Sitting",
"chinese": "雙星到坐",
"meaning": "Both prosperous stars gather at the back of the building. Good for health, for family and for anyone who works from home, weaker for income arriving from outside. The standard correction is water or open movement at the back, which gives the water star somewhere to work."
},
"palaces": [
{
"palace": "Center",
"base": 5,
"period": 9,
"mountain": 5,
"water": 4,
"reading": "The Five Yellow mountain star sits with the Four Green water star in this palace. The water star controls the mountain star here, Wood acting on Earth, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "Northwest",
"base": 6,
"period": 1,
"mountain": 4,
"water": 5,
"reading": "The Four Green mountain star sits with the Five Yellow water star in this palace. The mountain star controls the water star here, Wood acting on Earth, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "West",
"base": 7,
"period": 2,
"mountain": 3,
"water": 6,
"reading": "The Three Jade mountain star sits with the Six White water star in this palace. The water star controls the mountain star here, Metal acting on Wood, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "Northeast",
"base": 8,
"period": 3,
"mountain": 2,
"water": 7,
"reading": "The Two Black mountain star sits with the Seven Red water star in this palace. The mountain star produces the water star here, Earth feeding Metal, so the people side of the palace pours into the money side and the sector rewards effort spent on the household before effort spent on income. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "South",
"base": 9,
"period": 4,
"mountain": 1,
"water": 8,
"reading": "The One White mountain star sits with the Eight White water star in this palace. The water star controls the mountain star here, Earth acting on Water, so the money side dominates and gains in this sector tend to come at the expense of health or of the people in it. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "North",
"base": 1,
"period": 5,
"mountain": 9,
"water": 9,
"reading": "The Nine Purple mountain star sits with the Nine Purple water star in this palace. Both stars carry the Fire phase, so they reinforce each other instead of moderating each other, and whatever this palace does it does emphatically. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "Southwest",
"base": 2,
"period": 6,
"mountain": 8,
"water": 1,
"reading": "The Eight White mountain star sits with the One White water star in this palace. The mountain star controls the water star here, Earth acting on Water, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "East",
"base": 3,
"period": 7,
"mountain": 7,
"water": 2,
"reading": "The Seven Red mountain star sits with the Two Black water star in this palace. The water star produces the mountain star here, Earth feeding Metal, so money and opportunity support health and relationships, and the sector is usually easier to live in than to profit from. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
},
{
"palace": "Southeast",
"base": 4,
"period": 8,
"mountain": 6,
"water": 3,
"reading": "The Six White mountain star sits with the Three Jade water star in this palace. The mountain star controls the water star here, Metal acting on Wood, so the people side dominates: relationships hold, and income through this sector is held back rather than released. Read the mountain star for health, for the people in the room and for the relationships between them, and the water star for money, opportunity and whatever arrives from outside."
}
]
}Structured JSON with documented fields. Not hallucinated text. See all endpoints
Works with your stack
Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mountains, Kua numbers and the full Eight Mansions map of favourable and unfavourable directions, annual and monthly star plates, the four annual afflictions with exact degree spans, the compass Bagua map and the 1864 to 2043 period table. Chinese years resolve at Li Chun, computed astronomically, so the boundary is right rather than assumed. One key, Remote MCP, typed SDKs.
Every Feng Shui calculation is covered by 8,896 automated tests per deploy, 1,983 of them gold-standard tests locked to named external references such as NASA JPL Horizons, with a public MIT benchmark repo anyone can clone and re-run. See how we test.
Multi-language API responses
Key Features
Everything you need from our Feng Shui API, built for production:
Xuan Kong flying star natal charts cast from a construction period and a facing direction, returning all nine palaces with the period star, the mountain star and the water star, the flight direction of each plate, and the classical structure verdict
Facing accepted as one of the 24 mountains or as a raw compass bearing, with the response saying when a bearing fell in the outer band where the substitute gua construction applies instead
A named formation and a composed reading for every palace of a chart, built from the classical two star combinations and the five phase relation between the pair
Kua numbers for both formula variants, before and from the year 2000, with the raw result published beside the reassignment so a 5 is never silently changed
The full Eight Mansions map: all eight sectors classified into Sheng Chi, Tian Yi, Yan Nian and Fu Wei, and Huo Hai, Wu Gui, Liu Sha and Jue Ming, ordered best to worst with a rank that says which affliction to accept when no favourable sector is reachable
Annual and monthly star plates on the SOLAR calendar, where the year turns at Li Chun and each month at a major solar term, not on 1 January and not at Lunar New Year
The four annual afflictions with degree spans rather than sector names: Tai Sui on a single 15 degree mountain, Sui Po opposite it, the Three Killings across its 75 degree span split into its three named parts, and the Five Yellow read off the annual plate
The compass Bagua map with both the Later Heaven and Earlier Heaven arrangements per sector, aligned to true directions rather than to the front door
The nine periods from 1864 to 2043 with the exact Li Chun date each one opened, so a building finished in early February lands in the right period
Trigram vocabulary served from the same source as the I-Ching endpoints, so a trigram read from a Bagua sector and one read from the I-Ching catalogue agree field for field
All 11 Endpoints
Every one is live in the public OpenAPI spec and callable as an MCP tool. Click any endpoint to view detailed documentation, parameters, and response examples.
What You Can Build with Feng Shui API
Real-world applications and use cases for integrating Feng Shui API into your projects:
Property and interior design tools: natal charts and Bagua overlays laid onto a floor plan, sector by sector
Personal feng shui apps: Kua numbers, favourable directions and bed or desk placement guidance per household member
Yearly and monthly guidance features: annual star plates, afflictions and the renovation dates to avoid
AI assistants and chatbots: chart data over Remote MCP so an agent can answer a placement question with real numbers
Practitioner and consultation software: the full nine palace chart with flight directions and structure, in the form a professional already reads
Content and editorial platforms: star, Bagua and period reference lookups for explainer pages and structured libraries
What developers are saying
Dhani M.
Indie App Developer
Shipped an astrology app over a long weekend. Birth charts, nakshatras, KP cusps, significators. I verified the Lahiri ayanamsha values independently and they line up with my reference. One API key for all of it.
Tom H.
Senior Developer
The OpenAPI spec is the most complete I have seen in this space. Generated a type-safe TypeScript client from it in seconds. Every field has descriptions and examples. Production-grade documentation.
Chris W.
Backend Engineer
Response times consistently under 50ms for numerology and tarot endpoints. The API returns structured JSON with every field documented. Integrated it into our platform in an afternoon.
Do not take our word for it. Ask the agents.
The receipts are public: the testing methodology, the open MIT benchmark, the transparency report, and the live API playground. Let ChatGPT, Perplexity, or Claude search the web and tell you what they find about RoxyAPI accuracy, MCP, SDKs, and pricing.
Opens a live web search in a new tab.
Getting started with Feng Shui API.
From zero to production in 3 steps. No signup required for testing.
3 Steps to Ship
| 1Install the SDK | npm i @roxyapi/sdk |
| 2Get your API key | View Plans |
| 3Make your first call | View Docs |
Agent-Ready Infrastructure
MCPRemote MCP, llms.txt, and AGENTS.md. The full agent-readiness stack for 14+ domains under one key.
- Remote MCP server — every endpoint auto-discovered as a tool by Claude, ChatGPT, Cursor over Streamable HTTP. No Docker.
- Token-optimized responses — opt-in compact mode returns the same data with each field name sent once, cutting the tokens your agent reads per call by roughly 40 to 52 percent. Lossless, and one call still counts as one request.
- llms.txt — AI-native discovery surface for ChatGPT, Perplexity, and Gemini citation
- AGENTS.md — 2026 execution playbook for Cursor, Codex, Windsurf, Aider, Claude Code, Gemini CLI. Bundled in the SDK.
From your AI agent to a verified Feng Shui answer.
Your agent grounds every answer in verified calculations and replies in your own voice, so it never hallucinates a chart, date, or reading. No local setup, no AGPL, no hosted-AI markup.
Audit it yourself: every Feng Shui endpoint runs live in the API playground
Feng Shui API FAQ
How do I add a flying star chart to my app?
Send the construction period of the building and the direction it faces, either as one of the 24 mountains or as a compass bearing, and the API returns all nine palaces with the period star, the mountain star, the water star, the named formation for each pair and the classical verdict on the chart. Omit the period and it defaults to the one in force. Drop in the typed SDKs or point a client at our Remote MCP server, and one key also covers every other RoxyAPI domain.
Which feng shui school do these calculations follow?
Flying star charts follow the down gua construction of the Xuan Kong school, the one every modern text teaches, with the period plate flown forward and the mountain and water plates flown by the San Yuan polarity of the mountain each answers to. Eight Mansions follows the classical Da You Nian classification, which the API derives from the trigram line rule rather than reading off a stored matrix, so a transposed cell cannot survive. Where a genuine school split exists it is stated rather than hidden.
When does the feng shui year actually change?
At Li Chun, the astronomical start of spring in early February, and not at Lunar New Year, which is usually two to four weeks later. Every route in this domain uses that boundary: periods, annual stars, monthly stars and all four afflictions. The exact date is computed for each year rather than assumed to be 4 February, which it is not in roughly one year in four, and it is returned on the response so a caller can apply a new chart on the right day.
What is a Kua number and why does it need my birth date and sex?
The Kua number, also called the Ming Gua, places a person on one of the eight trigrams and decides which four compass sectors are favourable for them and which four are not. It is a function of the Chinese year of birth and of sex, because the two formula variants are different arithmetic on the same year. Birth time and place are not used, so no location lookup is needed. A raw result of 5 has no direction of its own and is reassigned, and the API publishes the untouched result beside the reassigned one.
Do the mountain star and the water star mean different things?
Yes, and reading them the same way is the usual mistake. The mountain star, also called the sitting star, governs health, the people in a room and the relationships between them. The water star, also called the facing star, governs money, career and whatever arrives from outside. A palace is then judged by the PAIR rather than by either star alone, which is why every palace in a chart comes back with the combination for its pair and a reading composed from both.
How precise are the affliction positions?
Precise to the mountain, which is 15 degrees, rather than to the 45 degree sector most guides quote. Tai Sui occupies exactly one mountain, so the two neighbouring mountains of the same sector are unaffected, and the difference decides whether a wall can be drilled. The Three Killings span is returned as both its exact 75 degree branch range and the cardinal sector it sits in, because both readings are in circulation and a caller should be able to see which one they are applying.
Start using Feng Shui API today.
Flying star charts that are actually checkable.
All 14 domains included with every plan. Every endpoint, MCP server, SDK, and starters.
Plans from $39/mo, starting at $2.32 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key