{"openapi":"3.1.0","info":{"title":"Feng Shui API","version":"2.0.0","description":"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.\n\n# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 14 domains (Astrology, Vedic Astrology, Forecast, Human Design, Chinese Astrology, Feng Shui, Numerology, Tarot Reading, Biorhythm, I-Ching Oracle, Crystals and Healing Stones, Dream Interpretation, Angel Numbers, Location and Timezone), 209+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (Remote MCP)\n\nRoxyAPI ships a Remote MCP server per product over Streamable HTTP, with no local setup and no Docker. Your AI agent auto-discovers all 209+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable and stable, so it is the one safe to switch on programmatically.\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset` (Unix timestamp, seconds). Quotas reset on the 1st of every calendar month at 12:00 AM UTC, not on your renewal date.\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 per month for 50K requests, up to 3M requests, with custom volume above that.\n\nSee [roxyapi.com/pricing](https://roxyapi.com/pricing)\n\n## Resources\n\n- [Quickstart guide](https://roxyapi.com/docs/quickstart) - first API call in 60 seconds\n- [Documentation](https://roxyapi.com/docs) - guides, tutorials, domain reference\n- [MCP setup](https://roxyapi.com/docs/mcp) - connect AI agents\n- [Starter apps](https://roxyapi.com/starters) - clone and deploy in 30 minutes\n- [FAQ](https://roxyapi.com/faq) - common questions\n- [Contact](https://roxyapi.com/contact) - support and API key recovery\n","contact":{"name":"RoxyAPI Support","url":"https://roxyapi.com/contact"},"license":{"name":"Proprietary","url":"https://roxyapi.com/policy/terms"}},"externalDocs":{"description":"Complete API Documentation with Examples","url":"https://roxyapi.com/docs"},"servers":[{"url":"/api/v2","description":"Production API v2"}],"security":[{"apiKey":[]}],"tags":[{"name":"Feng Shui","description":"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."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key for accessing RoxyAPI. Alternatively, you can pass the API key as a query parameter \"api_key\"."}},"schemas":{},"parameters":{}},"paths":{"/kua":{"post":{"operationId":"calculateKuaNumber","tags":["Feng Shui"],"summary":"Calculate Kua number - Feng shui personal direction calculator API","description":"Calculate the Kua number, also called the Ming Gua or life gua, from a birth date and sex. Returns the number, the east or west life group, the personal trigram, and all eight compass sectors classified from best to worst. The Chinese year is resolved at Li Chun by default, so an early February birthday is placed in the correct year rather than the calendar one, and the boundary that decided it is echoed back. Built for room and desk placement features, personalised feng shui reports, and any product that needs a favourable direction per person.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1985-07-15","description":"Birth date in YYYY-MM-DD format. Only the Chinese YEAR this date falls in enters the formula, so no birth time, latitude or longitude is needed. A January or early February birthday is the case that matters: it usually belongs to the PREVIOUS Chinese year and produces a different Kua. A date is read at the start of its day, and the boundary falls part-way through its own day, so a birth date landing exactly on the boundary day is placed in the outgoing year."},"gender":{"type":"string","enum":["male","female"],"example":"male","description":"Selects the Kua formula variant. The two formulas are different arithmetic on the same year, and they also differ in where a raw result of 5 is reassigned."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which boundary starts the Chinese year. Defaults to li-chun, the astronomical start of spring in early February, which is the classical position and the one feng shui uses for periods, annual stars and afflictions alike. Send lunar-new-year to match popular zodiac tables, which start the year two to four weeks later. The two disagree for anyone born between the two dates."}},"required":["date","gender"]}}}},"responses":{"200":{"description":"Kua number, life group, personal trigram and all eight classified sectors","content":{"application/json":{"schema":{"type":"object","properties":{"kua":{"type":"number","example":6,"description":"Kua number, 1 to 9 excluding 5. This is the value every other feng shui calculation about a person keys on."},"rawKua":{"type":"number","example":6,"description":"The formula output before any reassignment. Equal to kua except when the formula produced 5, which has no trigram and no direction and must be moved."},"reassigned":{"type":"boolean","example":false,"description":"Whether the raw result was 5 and had to be moved onto a trigram, to 2 for a man and to 8 for a woman."},"gender":{"type":"string","example":"male","description":"Echo of the sex sent, which selected the formula variant."},"group":{"type":"string","example":"west","description":"Life group, east or west. East group Kuas are 1, 3, 4 and 9 and share North, East, Southeast and South as their favourable sectors; west group Kuas are 2, 6, 7 and 8 and share Northeast, Southwest, West and Northwest. Always English, safe to compare against."},"solarYear":{"type":"number","example":1985,"description":"The Chinese year the birth date fell in under the boundary applied. This is the year the formula actually used, which is the previous calendar year for an early-in-the-year birthday."},"boundaryDate":{"type":"string","example":"1985-02-04","description":"Calendar date of the boundary that decided the year, computed astronomically rather than assumed. Li Chun is commonly quoted as 4 February and lands on the 3rd or the 5th in roughly one year in four."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"]},"sectors":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"star":{"type":"string","example":"sheng-chi","description":"Eight Mansions star for this sector, one of sheng-chi, tian-yi, yan-nian, fu-wei, huo-hai, wu-gui, liu-sha, jue-ming. Always English, safe to compare against and to key styling on."},"starName":{"type":"string","example":"Sheng Chi","description":"Display name of the star. Always English, whatever the lang parameter says. Use starNameLocalized for anything a reader sees."},"starNameLocalized":{"type":"string","example":"Aliento generador","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat starName exactly. Never compare against this value."},"nature":{"type":"string","example":"auspicious","description":"Whether the sector helps or harms: auspicious or inauspicious."},"rank":{"type":"number","example":1,"description":"Order within its nature, 1 to 4. Among auspicious sectors 1 is the strongest; among inauspicious sectors 1 is the mildest and 4 the most serious, which is what tells you which affliction to accept when no favourable sector is reachable."},"domain":{"type":"string","example":"Growth and income","description":"The life domain this sector governs, in a few words."}},"required":["direction","star","starName","nature","rank","domain"]},"description":"All eight sectors classified for this Kua, in compass order from North. Exactly four are auspicious and four are inauspicious, and the two sets partition the compass. Call the eight mansions endpoint for the same map with full readings and ranked placement guidance."},"conventions":{"type":"object","properties":{"yearBoundary":{"type":"string","example":"li-chun","description":"Which boundary decided the Chinese year for this calculation. li-chun starts the year at the astronomical start of spring, in early February, and is the classical position that feng shui uses throughout. lunar-new-year starts it at the first day of the lunar year, which is usually two to four weeks later and is what most popular zodiac tables use. Echoes the resolved value, whether it was sent or defaulted."}},"required":["yearBoundary"]}},"required":["kua","rawKua","reassigned","gender","group","solarYear","boundaryDate","trigram","sectors","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/kua/{number}":{"get":{"operationId":"getKuaNumber","tags":["Feng Shui"],"summary":"Look up a Kua number - Eight Mansions reference API","description":"Look up the reference chart for one Kua number: its trigram, its east or west life group, and how it classifies all eight compass sectors. A pure reference endpoint with no birth data required, for building a lookup table or a picker. Number 5 is served for completeness and is never a computed result, because it belongs to the centre and has no direction of its own: a man whose formula gives 5 reads Kua 2 and a woman reads Kua 8, and the chart returned for 5 is therefore the Kua 2 chart.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":9,"example":8,"description":"Kua number, 1 to 9."},"required":true,"description":"Kua number, 1 to 9.","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Kua reference chart with trigram, life group and eight classified sectors","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":8,"description":"Kua number, 1 to 9."},"group":{"type":"string","example":"west","description":"Life group, east or west. Always English, safe to compare against and to key styling on."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"]},"sectors":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"star":{"type":"string","example":"sheng-chi","description":"Eight Mansions star for this sector, one of sheng-chi, tian-yi, yan-nian, fu-wei, huo-hai, wu-gui, liu-sha, jue-ming. Always English, safe to compare against and to key styling on."},"starName":{"type":"string","example":"Sheng Chi","description":"Display name of the star. Always English, whatever the lang parameter says. Use starNameLocalized for anything a reader sees."},"starNameLocalized":{"type":"string","example":"Aliento generador","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat starName exactly. Never compare against this value."},"nature":{"type":"string","example":"auspicious","description":"Whether the sector helps or harms: auspicious or inauspicious."},"rank":{"type":"number","example":1,"description":"Order within its nature, 1 to 4. Among auspicious sectors 1 is the strongest; among inauspicious sectors 1 is the mildest and 4 the most serious, which is what tells you which affliction to accept when no favourable sector is reachable."},"domain":{"type":"string","example":"Growth and income","description":"The life domain this sector governs, in a few words."}},"required":["direction","star","starName","nature","rank","domain"]},"description":"All eight sectors classified for this Kua, in compass order from North."}},"required":["number","group","trigram","sectors"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No Kua chart for that number","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/eight-mansions":{"post":{"operationId":"generateEightMansions","tags":["Feng Shui"],"summary":"Generate Eight Mansions map - Ba Zhai lucky direction API","description":"Build the full Eight Mansions (Ba Zhai) map for a person: all eight compass sectors classified into the four favourable stars, Sheng Chi, Tian Yi, Yan Nian and Fu Wei, and the four unfavourable ones, Huo Hai, Wu Gui, Liu Sha and Jue Ming. Sectors come back ordered best to worst with a composed reading each, plus the ranking that decides which affliction to accept when no favourable sector is reachable. Accepts a Kua number directly or derives one from a birth date and sex. Built for bed and desk placement tools, room-by-room reports and floor plan overlays.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kua":{"type":"number","minimum":1,"maximum":9,"example":6,"description":"Kua number to build the map for, if you already have one. Send this OR date and gender, not neither. A Kua of 5 is read as the Kua 2 chart, since 5 has no direction of its own."},"date":{"type":"string","format":"date","example":"1985-07-15","description":"Birth date in YYYY-MM-DD format, used to derive the Kua when no kua is sent. Requires gender alongside it. A date is read at the start of its day, so a birth date landing exactly on the year boundary is placed in the outgoing year."},"gender":{"type":"string","enum":["male","female"],"example":"male","description":"Selects the Kua formula variant. Required when the Kua is being derived from a birth date."},"yearBoundary":{"type":"string","enum":["li-chun","lunar-new-year"],"default":"li-chun","example":"li-chun","description":"Which boundary starts the Chinese year when the Kua is derived from a birth date. Defaults to li-chun, the classical position. Ignored when a kua is sent directly, and echoed back either way."},"facing":{"type":"string","enum":["North","Northeast","East","Southeast","South","Southwest","West","Northwest"],"example":"Southeast","description":"Optional compass sector the main door faces, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. When sent, the response names the star sitting on that sector so a caller can judge an entrance without scanning the whole map."}},"description":"Send either a kua number, or a date and gender to derive one. Sending neither is a 400."}}}},"responses":{"200":{"description":"Eight classified sectors ordered best to worst, with readings","content":{"application/json":{"schema":{"type":"object","properties":{"kua":{"type":"number","example":6,"description":"The Kua number this map was built for."},"group":{"type":"string","example":"west","description":"Life group, east or west. Always English, safe to compare against and to key styling on."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"]},"sectors":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"star":{"type":"string","example":"sheng-chi","description":"Eight Mansions star for this sector. Always English, safe to compare against and to key styling on."},"starName":{"type":"string","example":"Sheng Chi","description":"Display name of the star. Always English, whatever the lang parameter says. Use starNameLocalized for anything a reader sees."},"starNameLocalized":{"type":"string","example":"Aliento generador","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat starName exactly. Never compare against this value."},"chinese":{"type":"string","example":"生氣","description":"Chinese characters for the star. Data, identical in every language."},"pinyin":{"type":"string","example":"Shēng Qì","description":"Tone-marked pinyin for the star. Data, identical in every language."},"nature":{"type":"string","example":"auspicious","description":"Whether the sector helps or harms: auspicious or inauspicious."},"rank":{"type":"number","example":1,"description":"Order within its nature, 1 to 4. Among auspicious sectors 1 is the strongest; among inauspicious sectors 1 is the mildest and 4 the most serious."},"domain":{"type":"string","example":"Growth and income","description":"The life domain this sector governs, in a few words."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"]},"reading":{"type":"string","example":"The West sector reads Sheng Chi for Kua 6. This is one of the four favourable sectors for Kua 6, ranked 1 of four. The generating breath, and the strongest of the four favourable sectors. It is the direction to face while working, to seat a main door in, and to put a desk against, because it reads as advancement, new business and the kind of momentum that compounds. Where a household has to choose one sector to get right, this is the one.","description":"Composed reading for this sector: which star it holds, where that star ranks for this Kua, and what the star means in practice."}},"required":["direction","star","starName","chinese","pinyin","nature","rank","domain","trigram","reading"]},"description":"All eight sectors, ordered best to worst rather than by compass, because the question this map answers is which sector to use next. Read down the list until you reach one the building actually has."},"bestSector":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"worstSector":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"facingSector":{"type":"object","properties":{"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"star":{"type":"string","example":"sheng-chi","description":"Eight Mansions star sitting on the facing sector."},"nature":{"type":"string","example":"auspicious","description":"Whether the facing sector helps or harms for this Kua."}},"required":["direction","star","nature"],"description":"The classification of the sector sent as facing. Absent when no facing was sent."},"conventions":{"type":"object","properties":{"yearBoundary":{"type":"string","example":"li-chun","description":"Which boundary decided the Chinese year for this calculation. li-chun starts the year at the astronomical start of spring, in early February, and is the classical position that feng shui uses throughout. lunar-new-year starts it at the first day of the lunar year, which is usually two to four weeks later and is what most popular zodiac tables use. Echoes the resolved value, whether it was sent or defaulted."}},"required":["yearBoundary"]}},"required":["kua","group","trigram","sectors","bestSector","worstSector","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/flying-stars/natal":{"post":{"operationId":"generateFlyingStarChart","tags":["Feng Shui"],"summary":"Generate flying star natal chart - Xuan Kong Fei Xing API","description":"Cast the Xuan Kong flying star natal chart for a building from its construction period and the direction it faces. Returns all nine palaces with the period star, the mountain star that governs health and relationships and the water star that governs wealth, plus the named formation and a composed reading for every palace, and the classical verdict on how the two prosperous stars landed. Facing is accepted as one of the 24 mountains or as a compass bearing. Built for property analysis tools, floor plan overlays and consultation software.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"integer","minimum":1,"maximum":9,"example":9,"description":"Construction period of the building, 1 to 9. This is the twenty year cycle the building was completed in, or last renovated heavily enough to reset, and it is fixed for the life of the building. Periods change at Li Chun in early February, so a building finished in January 2024 is a Period 8 building. Defaults to the period in force now."},"facing":{"type":"string","enum":["ren","zi","gui","chou","gen","yin","jia","mao","yi","chen","xun","si","bing","wu","ding","wei","kun","shen","geng","you","xin","xu","qian","hai","N1","N2","N3","NE1","NE2","NE3","E1","E2","E3","SE1","SE2","SE3","S1","S2","S3","SW1","SW2","SW3","W1","W2","W3","NW1","NW2","NW3"],"example":"wu","description":"The mountain the front of the building faces, by id or by compass label such as S2. Send this or facingDegrees, not neither. The facing side is the open, active, public side, which is not always the side with the front door."},"facingDegrees":{"type":["number","null"],"minimum":0,"maximum":360,"example":180,"description":"The compass bearing the front of the building faces, 0 to 360 degrees, measured looking out from inside. Resolved to one of the 24 mountains. Send this or facing, not neither."}}}}}},"responses":{"200":{"description":"Nine palaces with period, mountain and water stars, readings and structure","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"number","example":9,"description":"The period this chart was built for. Echoes the period requested, or the period in force now when it was omitted."},"facing":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Mountain id, the pinyin of the stem, branch or trigram that names it. Always English pinyin, safe to compare against."},"label":{"type":"string","example":"S2","description":"Compass label of the mountain, sector plus position 1 to 3 clockwise. The form a facing is usually quoted in."},"chinese":{"type":"string","example":"午","description":"Chinese character for the mountain. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ","description":"Tone-marked pinyin for the mountain. Data, identical in every language."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"yuan":{"type":"string","example":"heaven","description":"Which of the three dragons the mountain holds inside its sector: earth for the first mountain clockwise, heaven for the middle, human for the last. The heaven and human dragons share a polarity, which is why they share a chart."},"polarity":{"type":"string","example":"yin","description":"San Yuan polarity of the mountain, yang or yin, which decides whether a plate entering the centre flies forward or in reverse. This is NOT the natural polarity of the stem or branch and the two differ on eight of the 24 mountains."},"startDegree":{"type":"number","example":172.5,"description":"Start of the 15 degree span, in compass degrees. Wraps past 360 for the two northernmost mountains."},"endDegree":{"type":"number","example":187.5,"description":"End of the 15 degree span, in compass degrees."}},"required":["id","label","chinese","pinyin","direction","yuan","polarity","startDegree","endDegree"]},"sitting":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Mountain id, the pinyin of the stem, branch or trigram that names it. Always English pinyin, safe to compare against."},"label":{"type":"string","example":"S2","description":"Compass label of the mountain, sector plus position 1 to 3 clockwise. The form a facing is usually quoted in."},"chinese":{"type":"string","example":"午","description":"Chinese character for the mountain. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ","description":"Tone-marked pinyin for the mountain. Data, identical in every language."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"yuan":{"type":"string","example":"heaven","description":"Which of the three dragons the mountain holds inside its sector: earth for the first mountain clockwise, heaven for the middle, human for the last. The heaven and human dragons share a polarity, which is why they share a chart."},"polarity":{"type":"string","example":"yin","description":"San Yuan polarity of the mountain, yang or yin, which decides whether a plate entering the centre flies forward or in reverse. This is NOT the natural polarity of the stem or branch and the two differ on eight of the 24 mountains."},"startDegree":{"type":"number","example":172.5,"description":"Start of the 15 degree span, in compass degrees. Wraps past 360 for the two northernmost mountains."},"endDegree":{"type":"number","example":187.5,"description":"End of the 15 degree span, in compass degrees."}},"required":["id","label","chinese","pinyin","direction","yuan","polarity","startDegree","endDegree"]},"facingDegrees":{"type":"number","example":180,"description":"Echo of the bearing sent, when one was sent. Absent when the facing was named as a mountain instead."},"straddling":{"type":"boolean","example":false,"description":"Whether the bearing fell in the outer 3 degrees of its mountain rather than the central 9. A bearing there calls for the substitute gua construction, which is a different chart; this chart is always the down gua one, so a true value means the result needs a specialist rather than this endpoint. Always false when the facing was named as a mountain, since naming a mountain expresses no bearing."},"mountainCenterStar":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"waterCenterStar":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"mountainFlight":{"type":"string","example":"reverse","description":"Whether the mountain plate flew forward or in reverse, decided by the polarity of the mountain the centre star answers to. Published because it is the step that separates two charts that otherwise look alike."},"waterFlight":{"type":"string","example":"forward","description":"Whether the water plate flew forward or in reverse, decided the same way against the facing mountain."},"structure":{"type":"object","properties":{"id":{"type":"string","example":"double-sitting","description":"The classical verdict on the chart: prosperous-mountain-prosperous-water, reversed, double-facing or double-sitting. Always English, safe to switch on."},"name":{"type":"string","example":"Double Star at Sitting","description":"Display name of the structure. Always English, whatever the lang parameter says."},"chinese":{"type":"string","example":"雙星到坐","description":"Chinese name of the structure. Data, identical in every language."},"meaning":{"type":"string","example":"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.","description":"What the structure means and what the classical correction for it is."}},"required":["id","name","chinese","meaning"]},"palaces":{"type":"array","items":{"type":"object","properties":{"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center. Always English, safe to compare against and to key a grid cell on."},"base":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"period":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"mountain":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"water":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"combination":{"type":"object","properties":{"id":{"type":"string","example":"8-9","description":"Canonical key for the pair, lower number first, so a palace holding mountain 9 and water 8 resolves to the same entry as one holding mountain 8 and water 9."},"name":{"type":"string","example":"Prosperity Doubled","description":"Name of the formation. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Prosperidad doblada","description":"Formation name in the requested language, for display only. Present only when lang is set to a language other than English."},"chinese":{"type":"string","example":"八逢紫曜","description":"Chinese name of the formation. Data, identical in every language."},"nature":{"type":"string","example":"auspicious","description":"Whether the formation helps or harms."}},"required":["id","name","nature"],"description":"The named classical formation for this mountain and water pair. Absent for the pairs the tradition does not name, where the composed reading carries the meaning instead."},"reading":{"type":"string","example":"Fire producing the wealth Earth, and the ruling star of the current period sitting with the one that ruled the last. It reads as celebration attached to money: marriage, birth, a business milestone, and property that appreciates while it is lived in.","description":"What this palace means, composed from the two stars and the phase relation between them. Named formations return their own passage; the rest are built from the star pair."}},"required":["palace","base","period","mountain","water","reading"]},"description":"All nine palaces, centre first and then along the Lo Shu flight path. Each of the nine stars appears exactly once on each plate, which is the property that makes a chart checkable."}},"required":["period","facing","sitting","straddling","mountainCenterStar","waterCenterStar","mountainFlight","waterFlight","structure","palaces"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/flying-stars/annual/{year}":{"get":{"operationId":"getAnnualFlyingStars","tags":["Feng Shui"],"summary":"Annual flying stars - Yearly feng shui star chart API","description":"Return the annual flying star plate for a solar year: which of the nine stars occupies each of the nine palaces, what it means there, and which element strengthens or drains it. The annual plate is universal and does not depend on any building, so it is the layer every yearly feng shui guide is built on. The changeover is Li Chun in early February rather than Lunar New Year, and the exact date is returned so a caller can apply the plate on the right day.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Solar year, 1900 to 2100. The year runs from Li Chun to Li Chun, so a date in January belongs to the previous year here."},"required":true,"description":"Solar year, 1900 to 2100. The year runs from Li Chun to Li Chun, so a date in January belongs to the previous year here.","name":"year","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The nine palaces of the annual plate with meanings and remedies","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"The solar year this plate is for."},"centerStar":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"changeoverDate":{"type":"string","example":"2026-02-04","description":"The date this plate takes effect, which is Li Chun and NOT Lunar New Year. Lunar New Year 2026 falls on 17 February, roughly two weeks later, and applying the new plate from that date is the most common error in annual feng shui."},"palaces":{"type":"array","items":{"type":"object","properties":{"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center. Always English, safe to compare against and to key a grid cell on."},"star":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"name":{"type":"string","example":"Five Yellow","description":"Display name of the star in this palace. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Cinco Amarilla","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"nature":{"type":"string","example":"inauspicious","description":"The untimely reading of the star, auspicious or inauspicious."},"enhancer":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"remedy":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"meaning":{"type":"string","example":"Earth of the central palace, the one star with no trigram and no direction of its own, and the affliction every school treats as the most serious.","description":"What the star does in the sector it has flown to this period."}},"required":["palace","star","name","element","nature","enhancer","remedy","meaning"]},"description":"All nine palaces with the star that flew there, centre first and then along the Lo Shu path. The plate is universal: it is the same for every building on earth."}},"required":["year","centerStar","changeoverDate","palaces"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/flying-stars/monthly":{"get":{"operationId":"getMonthlyFlyingStars","tags":["Feng Shui"],"summary":"Monthly flying stars - Month by month feng shui overlay API","description":"Return the monthly flying star plate, the faster overlay that sits on top of the annual one. Months here are SOLAR months: month 1 begins at Li Chun in early February and each month begins at the next of the twelve major solar terms, so they never line up with calendar months. Omit both parameters to get the month in progress. Built for monthly guidance features and for timing work around an affliction that only lands for part of the year.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Solar year, 1900 to 2100. Defaults to the solar year in progress, which changes at Li Chun rather than on 1 January."},"required":false,"description":"Solar year, 1900 to 2100. Defaults to the solar year in progress, which changes at Li Chun rather than on 1 January.","name":"year","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"Solar month, 1 to 12, where 1 begins at Li Chun in early February. This is NOT the calendar month: solar month 1 covers roughly 4 February to 5 March. Defaults to the solar month in progress."},"required":false,"description":"Solar month, 1 to 12, where 1 begins at Li Chun in early February. This is NOT the calendar month: solar month 1 covers roughly 4 February to 5 March. Defaults to the solar month in progress.","name":"month","in":"query"}],"responses":{"200":{"description":"The nine palaces of the monthly plate with meanings and remedies","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Solar year of the plate. Echoes the year requested, or the solar year in progress when it was omitted."},"month":{"type":"number","example":1,"description":"Solar month of the plate, 1 to 12, where 1 is the month that begins at Li Chun in early February. Echoes the month requested, or the solar month in progress when it was omitted."},"centerStar":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"yearBranch":{"type":"string","example":"wu","description":"Earthly Branch of the solar year, which decides where the monthly sequence starts. Rat, Horse, Rabbit and Rooster years open on 8; Dragon, Dog, Ox and Goat years on 5; Tiger, Monkey, Snake and Pig years on 2."},"palaces":{"type":"array","items":{"type":"object","properties":{"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center. Always English, safe to compare against and to key a grid cell on."},"star":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"name":{"type":"string","example":"Five Yellow","description":"Display name of the star in this palace. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Cinco Amarilla","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"nature":{"type":"string","example":"inauspicious","description":"The untimely reading of the star, auspicious or inauspicious."},"enhancer":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"remedy":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"meaning":{"type":"string","example":"Earth of the central palace, the one star with no trigram and no direction of its own, and the affliction every school treats as the most serious.","description":"What the star does in the sector it has flown to this period."}},"required":["palace","star","name","element","nature","enhancer","remedy","meaning"]},"description":"All nine palaces of the monthly plate, centre first and then along the Lo Shu path."}},"required":["year","month","centerStar","yearBranch","palaces"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/flying-stars/stars":{"get":{"operationId":"listFlyingStars","tags":["Feng Shui"],"summary":"List the nine flying stars - Xuan Kong star reference API","description":"The reference catalogue of the nine flying stars: name, Chinese characters, five phase, home palace and trigram, the period each rules, what each means, and which element strengthens or drains it. The remedy element is what the star itself produces, because a harmful star is drained by giving it somewhere to go rather than fought with the phase that controls it. A pure reference endpoint that needs no chart.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":9,"default":20,"example":20,"description":"Maximum stars to return per page. Range 1 to 9, default 20."},"required":false,"description":"Maximum stars to return per page. Range 1 to 9, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of stars to skip for pagination. Default 0."},"required":false,"description":"Number of stars to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The nine flying stars with meanings, elements and remedies","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":9,"description":"Number of stars in the catalogue."},"limit":{"type":"number","example":20,"description":"Page size applied."},"offset":{"type":"number","example":0,"description":"Number of entries skipped."},"stars":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"name":{"type":"string","example":"Eight White","description":"Display name of the star. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Ocho Blanca","description":"Star name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat name exactly. Never compare against this value."},"chinese":{"type":"string","example":"八白","description":"Chinese characters for the star. Data, identical in every language."},"pinyin":{"type":"string","example":"Bā Bái","description":"Tone-marked pinyin for the star. Data, identical in every language."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"nature":{"type":"string","example":"auspicious","description":"The untimely reading of the star, auspicious or inauspicious. It is not the whole verdict: the ruling star of the period in force is prosperous whatever this says, and a star long past its period is the one that does damage. Only the 5 is harmful in every period."},"keywords":{"type":"array","items":{"type":"string","example":"wealth","description":"One theme the star governs, lower case, for tagging and for filtering."},"example":["wealth","accumulation","property","stability","savings"],"description":"Themes the star governs, for tagging and for quick summaries."},"meaning":{"type":"string","example":"Yang Earth in the northeastern palace, the wealth star that ruled from 2004 to 2023. It builds rather than wins: property, savings, a business that compounds, the kind of prosperity that survives a bad quarter.","description":"What the star does, how it reads when timely, and how it reads when it is not."},"enhancer":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"remedy":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center. Always English, safe to compare against and to key a grid cell on."},"period":{"type":"number","example":8,"description":"The twenty year period this star rules. A star is at its strongest during its own period and weakest long after it."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":7,"description":"Trigram number, the same identifier the I-Ching trigram endpoints use."},"english":{"type":"string","example":"Mountain","description":"English name of the trigram, byte identical to the I-Ching catalogue."},"chinese":{"type":"string","example":"艮","description":"Chinese character for the trigram. Data, identical in every language."}},"required":["number","english","chinese"],"description":"The trigram of the star palace. Absent for the 5, which owns the centre and has no trigram, which is also why the 5 is the one star with no direction of its own."},"base":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."}},"required":["number","name","chinese","pinyin","element","nature","keywords","meaning","enhancer","remedy","palace","period","base"]},"description":"The nine flying stars in Lo Shu order, 1 through 9."}},"required":["total","limit","offset","stars"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/afflictions/{year}":{"get":{"operationId":"getAnnualAfflictions","tags":["Feng Shui"],"summary":"Annual afflictions - Tai Sui, San Sha and Five Yellow API","description":"Return the four annual feng shui afflictions for a solar year with their exact positions: Tai Sui on the mountain of the year branch, Sui Po on the mountain opposite, the Three Killings across the cardinal span opposite the elemental frame of the year, and the Five Yellow wherever it lands on the annual star plate. Positions come with degree ranges rather than only sector names, because Tai Sui occupies 15 degrees and the neighbouring mountains of the same sector are unaffected. All four move at Li Chun in early February, not at Lunar New Year, and the changeover date is returned. Built for renovation planning, date selection and yearly guidance features.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Solar year, 1900 to 2100. The year runs from Li Chun to Li Chun, so a date in January belongs to the previous year here."},"required":true,"description":"Solar year, 1900 to 2100. The year runs from Li Chun to Li Chun, so a date in January belongs to the previous year here.","name":"year","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The four annual afflictions with mountains, degree spans and meanings","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"The solar year these positions are for."},"yearBranch":{"type":"string","example":"wu","description":"Earthly Branch of the solar year, in pinyin. Three of the four afflictions are derived from it. Always English pinyin, safe to compare against."},"changeoverDate":{"type":"string","example":"2026-02-04","description":"The date all four afflictions move, which is Li Chun and NOT Lunar New Year. In 2026 Lunar New Year falls on 17 February, roughly two weeks after the afflictions have already changed."},"taiSui":{"type":"object","properties":{"name":{"type":"string","example":"Tai Sui","description":"Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"chinese":{"type":"string","example":"太歲","description":"Chinese characters for the affliction. Data, identical in every language."},"pinyin":{"type":"string","example":"Tài Suì","description":"Tone-marked pinyin. Data, identical in every language."},"meaning":{"type":"string","example":"The Grand Duke, who occupies the mountain of the year branch. The standing rule is to sit with your back to Tai Sui and never to face him directly.","description":"What the affliction does and the standing rule for handling it."},"mountain":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Mountain id, the pinyin of the stem, branch or trigram that names it. Always English pinyin, safe to compare against."},"label":{"type":"string","example":"S2","description":"Compass label of the mountain, sector plus position 1 to 3 clockwise. The form a facing is usually quoted in."},"chinese":{"type":"string","example":"午","description":"Chinese character for the mountain. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ","description":"Tone-marked pinyin for the mountain. Data, identical in every language."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"yuan":{"type":"string","example":"heaven","description":"Which of the three dragons the mountain holds inside its sector: earth for the first mountain clockwise, heaven for the middle, human for the last. The heaven and human dragons share a polarity, which is why they share a chart."},"polarity":{"type":"string","example":"yin","description":"San Yuan polarity of the mountain, yang or yin, which decides whether a plate entering the centre flies forward or in reverse. This is NOT the natural polarity of the stem or branch and the two differ on eight of the 24 mountains."},"startDegree":{"type":"number","example":172.5,"description":"Start of the 15 degree span, in compass degrees. Wraps past 360 for the two northernmost mountains."},"endDegree":{"type":"number","example":187.5,"description":"End of the 15 degree span, in compass degrees."}},"required":["id","label","chinese","pinyin","direction","yuan","polarity","startDegree","endDegree"]},"direction":{"type":"string","example":"South","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, safe to compare against and to key styling on."},"animal":{"type":"string","example":"horse","description":"Zodiac animal of the year, which shares the sign Tai Sui occupies. Always English, safe to compare against."},"clashingAnimal":{"type":"string","example":"rat","description":"The animal directly opposite, which clashes with Tai Sui head on. People of this sign are the ones traditionally advised to take the most care during the year."}},"required":["name","chinese","pinyin","meaning","mountain","direction","animal","clashingAnimal"],"description":"The Grand Duke, occupying a single 15 degree mountain rather than a whole sector. Precision matters here more than anywhere else in the system, because the neighbouring mountains of the same sector are unaffected."},"suiPo":{"type":"object","properties":{"name":{"type":"string","example":"Sui Po","description":"Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"chinese":{"type":"string","example":"歲破","description":"Chinese characters for the affliction. Data, identical in every language."},"pinyin":{"type":"string","example":"Suì Pò","description":"Tone-marked pinyin. Data, identical in every language."},"meaning":{"type":"string","example":"The Year Breaker, sitting exactly opposite Tai Sui because it is the mountain the year branch clashes with.","description":"What the affliction does and the standing rule for handling it."},"mountain":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Mountain id, the pinyin of the stem, branch or trigram that names it. Always English pinyin, safe to compare against."},"label":{"type":"string","example":"S2","description":"Compass label of the mountain, sector plus position 1 to 3 clockwise. The form a facing is usually quoted in."},"chinese":{"type":"string","example":"午","description":"Chinese character for the mountain. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ","description":"Tone-marked pinyin for the mountain. Data, identical in every language."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"yuan":{"type":"string","example":"heaven","description":"Which of the three dragons the mountain holds inside its sector: earth for the first mountain clockwise, heaven for the middle, human for the last. The heaven and human dragons share a polarity, which is why they share a chart."},"polarity":{"type":"string","example":"yin","description":"San Yuan polarity of the mountain, yang or yin, which decides whether a plate entering the centre flies forward or in reverse. This is NOT the natural polarity of the stem or branch and the two differ on eight of the 24 mountains."},"startDegree":{"type":"number","example":172.5,"description":"Start of the 15 degree span, in compass degrees. Wraps past 360 for the two northernmost mountains."},"endDegree":{"type":"number","example":187.5,"description":"End of the 15 degree span, in compass degrees."}},"required":["id","label","chinese","pinyin","direction","yuan","polarity","startDegree","endDegree"]},"direction":{"type":"string","example":"South","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, safe to compare against and to key styling on."}},"required":["name","chinese","pinyin","meaning","mountain","direction"],"description":"The Year Breaker, always the mountain directly opposite Tai Sui."},"sanSha":{"type":"object","properties":{"name":{"type":"string","example":"San Sha","description":"Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"chinese":{"type":"string","example":"三煞","description":"Chinese characters for the affliction. Data, identical in every language."},"pinyin":{"type":"string","example":"Sān Shà","description":"Tone-marked pinyin. Data, identical in every language."},"meaning":{"type":"string","example":"The Three Killings, a 75 degree span opposite the elemental frame of the year. Never sit with your back to it, and facing it is safe.","description":"What the affliction does and the standing rule for handling it."},"direction":{"type":"string","example":"South","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, safe to compare against and to key styling on."},"frameElement":{"type":"string","example":"Fire","description":"The five phase the year branch forms with its trine. The Three Killings always sits in the cardinal direction opposite this frame."},"frameDirection":{"type":"string","example":"South","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, safe to compare against and to key styling on."},"startDegree":{"type":"number","example":322.5,"description":"Start of the afflicted span in compass degrees. The span crosses 360 when the affliction is in the north."},"endDegree":{"type":"number","example":37.5,"description":"End of the afflicted span in compass degrees."},"parts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"zai-sha","description":"Which of the three parts this is: jie-sha, zai-sha or sui-sha, in compass order. Always English, safe to compare against."},"name":{"type":"string","example":"Disaster Sha","description":"Display name of the part. Always English, whatever the lang parameter says."},"chinese":{"type":"string","example":"災煞","description":"Chinese characters for the part. Data, identical in every language."},"pinyin":{"type":"string","example":"Zāi Shà","description":"Tone-marked pinyin. Data, identical in every language."},"meaning":{"type":"string","example":"The middle component, sitting on the cardinal point itself, and the most volatile of the three. It reads as physical harm: sudden illness, accidents and injury.","description":"What this part of the span brings."},"mountain":{"type":"object","properties":{"id":{"type":"string","example":"wu","description":"Mountain id, the pinyin of the stem, branch or trigram that names it. Always English pinyin, safe to compare against."},"label":{"type":"string","example":"S2","description":"Compass label of the mountain, sector plus position 1 to 3 clockwise. The form a facing is usually quoted in."},"chinese":{"type":"string","example":"午","description":"Chinese character for the mountain. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ","description":"Tone-marked pinyin for the mountain. Data, identical in every language."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"yuan":{"type":"string","example":"heaven","description":"Which of the three dragons the mountain holds inside its sector: earth for the first mountain clockwise, heaven for the middle, human for the last. The heaven and human dragons share a polarity, which is why they share a chart."},"polarity":{"type":"string","example":"yin","description":"San Yuan polarity of the mountain, yang or yin, which decides whether a plate entering the centre flies forward or in reverse. This is NOT the natural polarity of the stem or branch and the two differ on eight of the 24 mountains."},"startDegree":{"type":"number","example":172.5,"description":"Start of the 15 degree span, in compass degrees. Wraps past 360 for the two northernmost mountains."},"endDegree":{"type":"number","example":187.5,"description":"End of the 15 degree span, in compass degrees."}},"required":["id","label","chinese","pinyin","direction","yuan","polarity","startDegree","endDegree"]}},"required":["id","name","chinese","pinyin","meaning","mountain"]},"description":"The three mountains of the span, first to last in compass order. They are one affliction read in three parts, not three separate ones, and disturbing any part is taken to wake the whole."}},"required":["name","chinese","pinyin","meaning","direction","frameElement","frameDirection","startDegree","endDegree","parts"],"description":"The Three Killings. Two readings of its extent are in circulation and both are given: the exact 75 degree branch span in startDegree and endDegree, and the 45 degree cardinal palace named in direction."},"fiveYellow":{"type":"object","properties":{"name":{"type":"string","example":"Five Yellow","description":"Display name of the affliction. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"chinese":{"type":"string","example":"五黃","description":"Chinese characters for the affliction. Data, identical in every language."},"pinyin":{"type":"string","example":"Wǔ Huáng","description":"Tone-marked pinyin. Data, identical in every language."},"meaning":{"type":"string","example":"The annual position of the 5, the one affliction that moves with the flying stars rather than with the year branch.","description":"What the affliction does and the standing rule for handling it."},"palace":{"type":"string","example":"South","description":"Palace the 5 flew to this year, one of the eight sectors or Center. Always English, safe to compare against."},"star":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"remedy":{"type":"string","example":"Metal","description":"The phase that drains the 5, which is what the 5 itself produces. Never treat it with Fire, which produces Earth and feeds it."}},"required":["name","chinese","pinyin","meaning","palace","star","remedy"],"description":"The Five Yellow, read off the annual star plate rather than from the year branch, which is why it is the only one of the four that has nothing to do with the animal of the year."}},"required":["year","yearBranch","changeoverDate","taiSui","suiPo","sanSha","fiveYellow"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bagua":{"get":{"operationId":"listBaguaSectors","tags":["Feng Shui"],"summary":"List Bagua sectors - Feng shui bagua map API","description":"The nine palaces of the compass Bagua map: the eight trigram sectors plus the centre, each with the life area it governs, its five phase, its colours, and both its Later Heaven and Earlier Heaven trigrams. This is the compass map aligned to true directions, so career is always North and wealth is always Southeast whichever way the entrance faces. Trigram details are served from the same source as the I-Ching trigram endpoints, so the two agree field for field. Built for floor plan overlays, room-by-room guides and any interface that maps a space onto life areas.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":9,"default":20,"example":20,"description":"Maximum sectors to return per page. Range 1 to 9, default 20."},"required":false,"description":"Maximum sectors to return per page. Range 1 to 9, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of sectors to skip for pagination. Default 0."},"required":false,"description":"Number of sectors to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The nine Bagua palaces with life areas, elements, colours and trigrams","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":9,"description":"Number of palaces in the map."},"limit":{"type":"number","example":20,"description":"Page size applied."},"offset":{"type":"number","example":0,"description":"Number of entries skipped."},"sectors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"wealth","description":"Life area id: career, knowledge, family, wealth, fame, love, children, helpful-people or health. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"name":{"type":"string","example":"Wealth and Abundance","description":"Display name of the life area. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Riqueza y abundancia","description":"Life area name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat name exactly. Never compare against this value."},"number":{"type":"number","example":4,"description":"Lo Shu number of the palace, 1 to 9. This is the same number the flying stars use, so a chart palace and a Bagua sector line up by it."},"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center for the ninth. Always English, safe to compare against."},"direction":{"type":"string","example":"Southeast","description":"Compass sector of the palace, taken from the trigram that sits there. Absent on the centre palace, which has no direction."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"colors":{"type":"array","items":{"type":"string","example":"green","description":"One colour of the phase this sector carries, lower case."},"example":["green","teal","brown"],"description":"Colours of the phase this sector carries, for activating it. Derived from the element rather than assigned per sector, so they cannot disagree with the element beside them."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"],"description":"The Later Heaven trigram of the sector, which is the arrangement every compass reading and every flying star chart uses. Absent on the centre palace."},"earlierHeavenTrigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"],"description":"The trigram that sits in this direction under the Earlier Heaven arrangement, read for the symbolic relation between opposite sectors. A different question from the Later Heaven trigram, not a competing answer. Absent on the centre palace."},"focus":{"type":"string","example":"Income, resources, accumulation","description":"What this sector governs, in a few words."},"meaning":{"type":"string","example":"The southeastern palace, held by Wind, and the sector most households want working. Wind is gradual and persistent, which is the point: this reads as income that builds through repeated effort rather than as sudden gain.","description":"What the sector governs and how to work with it."}},"required":["id","name","number","palace","element","colors","focus","meaning"]},"description":"The nine palaces of the compass Bagua map, in Lo Shu palace order starting at North and ending with the centre."}},"required":["total","limit","offset","sectors"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/bagua/{id}":{"get":{"operationId":"getBaguaSector","tags":["Feng Shui"],"summary":"Look up a Bagua sector - Life area reference API","description":"Look up one palace of the compass Bagua map by its life area id, such as wealth, career or love. Returns the compass sector it occupies, its five phase and colours, both trigram arrangements and what the sector governs. The health palace is the centre and carries no direction and no trigram, because the centre of the Lo Shu is not a trigram.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["career","knowledge","family","wealth","fame","love","children","helpful-people","health"],"example":"wealth","description":"Life area id. One of career, knowledge, family, wealth, fame, love, children, helpful-people, health."},"required":true,"description":"Life area id. One of career, knowledge, family, wealth, fame, love, children, helpful-people, health.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"One Bagua palace with its life area, element, colours and trigrams","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"wealth","description":"Life area id: career, knowledge, family, wealth, fame, love, children, helpful-people or health. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"name":{"type":"string","example":"Wealth and Abundance","description":"Display name of the life area. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Riqueza y abundancia","description":"Life area name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat name exactly. Never compare against this value."},"number":{"type":"number","example":4,"description":"Lo Shu number of the palace, 1 to 9. This is the same number the flying stars use, so a chart palace and a Bagua sector line up by it."},"palace":{"type":"string","example":"Southeast","description":"Palace of the Lo Shu grid: one of the eight compass sectors, or Center for the ninth. Always English, safe to compare against."},"direction":{"type":"string","example":"Southeast","description":"Compass sector of the palace, taken from the trigram that sits there. Absent on the centre palace, which has no direction."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"colors":{"type":"array","items":{"type":"string","example":"green","description":"One colour of the phase this sector carries, lower case."},"example":["green","teal","brown"],"description":"Colours of the phase this sector carries, for activating it. Derived from the element rather than assigned per sector, so they cannot disagree with the element beside them."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"],"description":"The Later Heaven trigram of the sector, which is the arrangement every compass reading and every flying star chart uses. Absent on the centre palace."},"earlierHeavenTrigram":{"type":"object","properties":{"number":{"type":"number","example":4,"description":"Trigram number, 1 to 8, the same identifier the I-Ching trigram endpoints use. It is a lookup key, not a ranking."},"chinese":{"type":"string","example":"巽","description":"Chinese character for the trigram. Data, identical in every language."},"english":{"type":"string","example":"Wind","description":"English name of the trigram, byte identical to the value the I-Ching trigram endpoints publish for this number."},"pinyin":{"type":"string","example":"Xùn","description":"Tone-marked pinyin for the trigram. Data, identical in every language."},"symbol":{"type":"string","example":"☴","description":"Unicode trigram symbol, for rendering a Bagua diagram without an icon set."},"binary":{"type":"string","example":"011","description":"Three lines bottom to top, 1 for yang and 0 for yin. The Eight Mansions classification of any sector is decided by which of these three lines differ from your own trigram."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"direction":{"type":"string","example":"Southeast","description":"Compass sector, one of North, Northeast, East, Southeast, South, Southwest, West, Northwest. Always English, whatever the lang parameter says, so it stays safe to compare against in code and against the same value on the I-Ching trigram endpoints."},"familyMember":{"type":"string","example":"Eldest Daughter","description":"Family role of the trigram. Read alongside an affliction to know which member of the household a sector points at."}},"required":["number","chinese","english","pinyin","symbol","binary","element","direction","familyMember"],"description":"The trigram that sits in this direction under the Earlier Heaven arrangement, read for the symbolic relation between opposite sectors. A different question from the Later Heaven trigram, not a competing answer. Absent on the centre palace."},"focus":{"type":"string","example":"Income, resources, accumulation","description":"What this sector governs, in a few words."},"meaning":{"type":"string","example":"The southeastern palace, held by Wind, and the sector most households want working. Wind is gradual and persistent, which is the point: this reads as income that builds through repeated effort rather than as sudden gain.","description":"What the sector governs and how to work with it."}},"required":["id","name","number","palace","element","colors","focus","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No Bagua sector with that life area id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/periods":{"get":{"operationId":"listNinePeriods","tags":["Feng Shui"],"summary":"List the nine periods - San Yuan period table API","description":"The nine twenty year periods of the 180 year San Yuan cycle from 1864 to 2043, each with its ruling star, five phase, palace and the exact Li Chun date it opened, plus which period is in force on a given date. A building takes the period it was completed in and keeps that period plate for life, so this is the table that decides which natal chart a property gets. Period 9 opened on 4 February 2024, which means a building finished in January 2024 is still a Period 8 building.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-08-23","description":"Date to resolve the current period for, in YYYY-MM-DD format. Defaults to today in UTC. Useful for asking which period a building was completed in."},"required":false,"description":"Date to resolve the current period for, in YYYY-MM-DD format. Defaults to today in UTC. Useful for asking which period a building was completed in.","name":"date","in":"query"}],"responses":{"200":{"description":"The nine periods with ruling stars and the period in force","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":9,"description":"Number of periods in the cycle. Always nine."},"cycleStartYear":{"type":"number","example":1864,"description":"First solar year of the recorded 180 year cycle."},"cycleEndYear":{"type":"number","example":2043,"description":"Last solar year of the recorded cycle. The cycle then repeats, so 2044 opens Period 1 again."},"date":{"type":"string","example":"2026-08-23","description":"The date the current period was resolved for. Echoes the date requested, or the current UTC date when it was omitted."},"currentPeriod":{"type":"number","example":9,"description":"The period in force on that date. Resolved at Li Chun, so a date in January belongs to the previous solar year and can fall in the previous period."},"periods":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":9,"description":"Period number, 1 to 9. A building takes the period it was completed in and keeps that period plate for its whole life, so this is the first input to every natal chart."},"startYear":{"type":"number","example":2024,"description":"First solar year of the period. The period opens at Li Chun of this year, in early February, not on 1 January."},"endYear":{"type":"number","example":2043,"description":"Last solar year of the period. The next period opens at Li Chun of the year after."},"startDate":{"type":"string","example":"2024-02-04","description":"Exact date the period opened, computed astronomically. Li Chun is commonly quoted as 4 February and falls on the 3rd or the 5th in roughly one year in four, which is what decides whether a building finished in early February belongs to this period or the last."},"era":{"type":"string","example":"lower","description":"Which sixty year era the period belongs to: upper, middle or lower, three periods each. Always English, safe to compare against."},"eraName":{"type":"string","example":"Lower Era","description":"Display name of the era."},"rulingStar":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."},"rulingStarName":{"type":"string","example":"Nine Purple","description":"Display name of the ruling star. Always English, whatever the lang parameter says. Use rulingStarNameLocalized for anything a reader sees."},"rulingStarNameLocalized":{"type":"string","example":"Nueve Purpura","description":"Ruling star name in the requested language, for display only. Present only when lang is set to a language other than English."},"element":{"type":"string","example":"Wood","description":"Five phase of this entry: Wood, Fire, Earth, Metal or Water. Always English so it stays safe to compare against and to key styling on. The full cycles live on the Chinese astrology elements endpoint."},"palace":{"type":"string","example":"South","description":"Palace the ruling star owns on the Lo Shu base plate. Always English, safe to compare against."},"trigram":{"type":"object","properties":{"number":{"type":"number","example":6,"description":"Trigram number, the same identifier the I-Ching trigram endpoints use."},"english":{"type":"string","example":"Fire","description":"English name of the trigram, byte identical to the I-Ching catalogue."},"chinese":{"type":"string","example":"離","description":"Chinese character for the trigram. Data, identical in every language."}},"required":["number","english","chinese"],"description":"Trigram of the ruling star palace. Absent for Period 5, whose star owns the centre and has no trigram."},"base":{"type":"number","example":8,"description":"Flying star number, 1 to 9. The number IS the identifier of the star: 8 is always the Eight White Earth star whichever plate it appears on."}},"required":["number","startYear","endYear","startDate","era","eraName","rulingStar","rulingStarName","element","palace","base"]},"description":"All nine periods of the 180 year cycle in order, each with its ruling star, element, palace and exact opening date."}},"required":["total","cycleStartYear","cycleEndYear","date","currentPeriod","periods"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}},"webhooks":{}}