--- name: api.cn402.com description: api.cn402.com provides a collection of APIs covering traditional Chinese cultural and metaphysical systems, including Chinese calendar and festival data, feng shui divination tools, I Ching and Liu Yao readings, Traditional Chinese Medicine references, and dream/fortune-slip oracles. All endpoints return structured data drawn from classical Chinese reference material. The host serves agents that need to integrate Chinese cultural, calendrical, or divinatory content into their workflows. host: api.cn402.com --- # api.cn402.com api.cn402.com is a specialized data host focused exclusively on traditional Chinese cultural systems. It serves agents and applications that need structured access to Chinese lunar calendar conversions, festival lookups, feng shui compass data, I Ching and Liu Yao divination, TCM meridian and constitution references, and almanac data. It is distinct from general-purpose calendar or health APIs in that all content is rooted in classical Chinese traditions rather than Western or universal frameworks. ## When to use this host Use api.cn402.com when an agent requires structured data from traditional Chinese cultural systems: lunar calendar conversion, Chinese festival identification, feng shui compass or flying star charts, I Ching or Liu Yao divination, TCM meridian or constitution references, or Zhougong dream interpretation. All content is China-specific and classical in origin. Do not use this host for Western holiday calendars, Western astrology, tarot, general nutrition or medical databases, real-time geomagnetic or weather data, or Gregorian-only calendar arithmetic — use a general-purpose calendar API or health data API for those needs. This host also does not support lunar-to-Gregorian reverse conversion; for that, a dedicated lunisolar conversion library or API is required. ## Capabilities ### Chinese Calendar and Date Utilities Converts Gregorian dates to lunar calendar equivalents and retrieves solar term, zodiac, and ganzhi metadata for any given date. These skills form the foundational date layer that other clusters depend on. - **`convert-gregorian-to-lunar`** — Converts a Gregorian calendar date to Chinese lunar calendar date, including lunar year/month/day, leap-month flag, ganzhi pillars, zodiac sign, and weekday. - **`fetch-chinese-almanac-today`** — Returns Chinese almanac data for a given date including auspicious activities (yi), avoid activities (ji), lunar date, ganzhi, zodiac, solar term, and festival. ### Festival and Cultural Events Identifies Chinese festivals for a given date or year and returns associated cultural customs, traditional foods, and auspicious or inauspicious activities. - **`fetch-chinese-festival-by-date`** — Returns Chinese festival names, lunar date, and solar/lunar calendar events for today or a specified date. - **`fetch-cn-festival-calendar`** — Returns a list of Chinese festivals for a given year, including Gregorian solar dates, lunar dates, and Chinese names, with the current year as default. - **`fetch-chinese-festival-customs`** — Returns traditional Chinese festival customs, auspicious/inauspicious activities, and traditional foods for a given date or named festival. ### Feng Shui and Geomancy Provides structured feng shui reference data including the 24-mountain compass table and Xuan Kong flying star palace charts for a given year and house sitting direction. - **`fetch-24mountain-fengshui`** — Returns the full 24-mountain (二十四山) compass table from Chinese feng shui, with optional lookup by mountain name or compass degree, including direction, degree range, element, yin/yang, trigram, family, and color for each of the 24 segments. - **`fetch-flying-star-fengshui-chart`** — Returns a Xuan Kong flying star (九宫紫白) chart for a given year and house sitting direction, including all 9 palace star assignments and current period metadata. ### Divination and Oracle Systems Covers multiple classical Chinese divination methods: I Ching hexagram catalog and random draws, Liu Yao six-line hexagram readings, fortune slip oracles, and Zhougong dream interpretation. - **`fetch-iching-hexagram-list`** — Returns the complete catalog of all 64 I Ching hexagrams in King Wen order, each with number, Chinese name, full name, trigram symbol, upper/lower trigrams, element, and a brief description. - **`fetch-iching-random-hexagram`** — Returns a randomly drawn I Ching hexagram using the three-coin six-line method, including the primary hexagram, changed hexagram, changing lines, and traditional Chinese judgment and image texts. - **`fetch-liuyao-divination`** — Generates a Liu Yao (六爻) hexagram reading using the Jing Fang Najia method, returning the primary hexagram, changing lines, and interpretive analysis for a given date or question. - **`fetch-fortune-slip-reading`** — Returns a traditional Chinese fortune slip (qiānzi) draw with slip number, auspicious level, poem, and interpretation, optionally filtered by temple deity. - **`fetch-zhougong-dream-meaning`** — Looks up traditional Chinese Zhougong dream interpretations by keyword, returning matched entries with keyword and meaning from a 105-entry dictionary. ### Traditional Chinese Medicine References Returns TCM meridian data, solar-term-based seasonal health guidance, and constitution analysis from scored questionnaire responses. - **`fetch-tcm-meridian`** — Returns Traditional Chinese Medicine meridian data for the 12 main channels plus Ren and Du vessels, including name, fullname, and acupoint count, by name or full list. - **`fetch-tcm-solar-term-health-guide`** — Returns Traditional Chinese Medicine seasonal health advice for the current or a specified date, including the active solar term (jieqi), adjacent terms, and diet/lifestyle recommendations. - **`fetch-tcm-constitution-analysis`** — Submits scored answers for a Traditional Chinese Medicine 9-constitution quiz and returns the dominant constitution type with recommendations. ## Workflows ### Daily Chinese Cultural Briefing *Use when an agent needs to produce a comprehensive daily summary covering lunar date, active solar term, almanac auspicious/inauspicious activities, and any Chinese festival for a given date.* 1. **`convert-gregorian-to-lunar`** — Convert the target Gregorian date to its lunar calendar equivalent, obtaining ganzhi, zodiac, and leap-month status. 2. **`fetch-chinese-almanac-today`** — Retrieve almanac data for the same date, including yi/ji activity guidance, solar term, and festival flag. 3. **`fetch-chinese-festival-by-date`** — Confirm whether the date is a Chinese festival and retrieve festival names and lunar calendar details. 4. **`fetch-chinese-festival-customs`** — If a festival is present, fetch associated customs, traditional foods, and recommended or avoided activities. ### Festival Cultural Detail Lookup *Use when an agent needs to go beyond a festival name and retrieve full cultural context — customs, foods, and activities — for a specific date or named festival.* 1. **`fetch-chinese-festival-by-date`** — Determine whether the date is a festival and retrieve the festival name(s). 2. **`fetch-chinese-festival-customs`** — Use the festival name or date to fetch customs, auspicious/inauspicious activities, and traditional foods. ### I Ching Reading with Reference Lookup *Use when an agent needs to perform a random I Ching divination and then cross-reference the resulting hexagram against the full catalog for additional metadata.* 1. **`fetch-iching-random-hexagram`** — Draw a random hexagram using the three-coin method, obtaining the primary hexagram, changing lines, and traditional texts. 2. **`fetch-iching-hexagram-list`** — Look up the drawn hexagram number in the full 64-hexagram catalog to retrieve trigram composition, element, and supplementary metadata. ### TCM Seasonal Health and Constitution Assessment *Use when an agent needs to combine a user's TCM constitution type with seasonal health guidance relevant to the current solar term.* 1. **`fetch-tcm-constitution-analysis`** — Submit the user's 60 scored questionnaire answers to determine their dominant TCM constitution type and recommendations. 2. **`fetch-tcm-solar-term-health-guide`** — Retrieve solar-term-based dietary and lifestyle advice for the current or target date to contextualize the constitution recommendations seasonally. ### Feng Shui Site Assessment *Use when an agent needs to assess a property's feng shui by resolving its compass bearing to a 24-mountain entry and then computing the annual flying star chart for that sitting direction.* 1. **`fetch-24mountain-fengshui`** — Resolve the property's compass bearing or mountain name to its element, trigram, yin/yang, and directional attributes. 2. **`fetch-flying-star-fengshui-chart`** — Compute the Xuan Kong flying star chart for the target year using the resolved sitting direction, returning per-palace star assignments. ## Skill reference ### `fetch-zhougong-dream-meaning` **Zhougong Dream Oracle** — Looks up traditional Chinese Zhougong dream interpretations by keyword, returning matched entries with keyword and meaning from a 105-entry dictionary. *Use when:* Use when a user or agent needs to interpret a dream using traditional Chinese Zhougong (周公解梦) symbolism and provides a Chinese keyword such as 蛇 (snake), 飞 (flying), or 水 (water). *Not for:* Do not use for non-Chinese dream interpretation or Western dream symbolism; use a general dream dictionary API instead. Not suitable for queries in languages other than Chinese. **Inputs:** - `q` (string, required) — Dream subject keyword in Chinese to look up in the Zhougong dream dictionary. **Returns:** Returns a query echo and a matches array of Zhougong dream entries, each with a Chinese keyword and its traditional interpretation string. **Example:** `GET https://api.cn402.com/zhanbu/zhougong?q=蛇` --- ### `fetch-chinese-festival-by-date` **CN402 Chinese Festival Lookup** — Returns Chinese festival names, lunar date, and solar/lunar calendar events for today or a specified date. *Use when:* Use when an agent needs to determine whether a given date (or today) is a Chinese festival, or to retrieve the list of festival names and lunar calendar details for that date. *Not for:* Do not use for non-Chinese calendar systems or Western holiday lookups; use a general holiday API instead. **Inputs:** - `date` (string) — Date to look up in YYYY-MM-DD format. Defaults to today if omitted. **Returns:** Returns date, lunar_date, is_festival boolean, and arrays for festivals, builtin_solar, and builtin_lunar — all empty when no festival falls on the queried date. **Example:** `GET https://api.cn402.com/festival/today?date=2026-05-28` --- ### `fetch-24mountain-fengshui` **24 Mountain Feng Shui** — Returns the full 24-mountain (二十四山) compass table from Chinese feng shui, with optional lookup by mountain name or compass degree, including direction, degree range, element, yin/yang, trigram, family, and color for each of the 24 segments. *Use when:* Use when an agent needs feng shui compass data for one or all 24 mountains (罗盘二十四山), such as resolving a compass bearing to its mountain attributes or retrieving element, trigram, and yin/yang metadata by mountain name. *Not for:* Do not use for Western astrology, Ba Zi (eight characters) birth chart analysis, or real-time geomagnetic readings; those require separate APIs. **Inputs:** - `name` (string) — Mountain name to look up, e.g. a single character or sequence like 壬, 子, or 癸. Returns the matching shan entry in the lookup field. - `degree` (number) — Compass bearing in degrees (0–360). Returns the mountain whose 15° segment contains this degree in the lookup field. **Returns:** Returns count=24, a shan map of all 24 mountain objects each with direction, 15° degree range, element, yin/yang, trigram, family, and color, plus a lookup object for the matched mountain when a query parameter is supplied. **Example:** `GET https://api.cn402.com/fengshui/24shan?degree=345` --- ### `fetch-fortune-slip-reading` **Divination Slip Oracle** — Returns a traditional Chinese fortune slip (qiānzi) draw with slip number, auspicious level, poem, and interpretation, optionally filtered by temple deity. *Use when:* Use when the user or agent requests a Chinese fortune slip reading, divination result, or temple oracle draw, and needs a slip number, luck level, classical poem, and interpretive guidance. *Not for:* Do not use for Western astrology, tarot, or I Ching hexagram readings. Not suitable for real-time price or market data queries. **Inputs:** - `temple` (string) — Temple slip set to draw from. Optional. Examples: 观音 (Guanyin), 关帝 (Guan Di). If omitted, a random draw is performed. **Returns:** Returns a fortune slip draw with slip number (e.g. 80), auspicious level (e.g. 中吉), classical poem, prose interpretation, historical title, draw timestamp, and library metadata. **Example:** `GET https://api.cn402.com/zhanbu/qianzi?temple=关帝` --- ### `fetch-flying-star-fengshui-chart` **Flying Star Feng Shui Chart** — Returns a Xuan Kong flying star (九宫紫白) chart for a given year and house sitting direction, including all 9 palace star assignments and current period metadata. *Use when:* Use when an agent needs to compute or display a Xuan Kong flying star feng shui chart for a specific year and house sitting direction, including per-palace star numbers, star attributes (element, nature, domain), and the current 9-period cycle. *Not for:* Do not use for Ba Zi (eight characters) birth chart analysis, general Chinese astrology, or real-time geomancy calculations unrelated to flying star palace grids. **Inputs:** - `year` (integer, required) — The year for which to generate the flying star chart, in YYYY format. - `sitting` (string, required) — House sitting direction in Chinese characters (e.g. 子, 北, 午, 南). Determines the base orientation of the flying star chart. **Returns:** Returns a year_chart with 9 directional palaces each containing a star number and full star_info (name, element, color, nature, domain), plus current_period metadata for the active 9-period cycle (e.g. 九运 2024–2043). **Example:** `GET https://api.cn402.com/fengshui/feixing?year=2026&sitting=子` --- ### `fetch-liuyao-divination` **LiuYao Divination** — Generates a Liu Yao (六爻) hexagram reading using the Jing Fang Najia method, returning the primary hexagram, changing lines, and interpretive analysis for a given date or question. *Use when:* Use when an agent needs a traditional Chinese Liu Yao divination reading — either for a specific date or an open question — and requires structured hexagram data including trigrams, line types, Najia mappings, Shi/Ying positions, and analysis. *Not for:* Do not use for Ba Zi (eight characters) birth chart analysis, Feng Shui site assessments, or Western astrology readings; those require different endpoints. **Inputs:** - `date` (string) — Divination date in YYYY-MM-DD format. Defaults to today if omitted. - `question` (string) — Optional question to ask the oracle. If omitted, a general reading is cast. **Returns:** Returns a ben_gua object with upper/lower trigrams, six Najia-mapped lines, Shi/Ying positions, a changing_yao array, and an analysis summary; bian_gua is null when no lines change. **Example:** `GET https://api.cn402.com/zhanbu/liuyao?date=2025-06-15&question=Will+my+business+venture+succeed+this+year%3F` --- ### `fetch-iching-hexagram-list` **I Ching Hexagram List** — Returns the complete catalog of all 64 I Ching hexagrams in King Wen order, each with number, Chinese name, full name, trigram symbol, upper/lower trigrams, element, and a brief description. *Use when:* Use when an agent needs the full list of I Ching hexagrams with their metadata, such as to look up a hexagram by number or name, display the complete catalog, or map trigram combinations to hexagram entries. *Not for:* Do not use for performing an I Ching divination or casting a reading; this endpoint only returns the static reference catalog, not a randomized or interpreted reading. **Returns:** Returns count=64 and a hexagrams array of 64 objects, each with num, name, fullname, gua symbol, upper/lower trigrams, element, and a short descriptive phrase in Chinese. **Example:** `GET https://api.cn402.com/iching/list` --- ### `fetch-tcm-meridian` **TCM Meridian Lookup** — Returns Traditional Chinese Medicine meridian data for the 12 main channels plus Ren and Du vessels, including name, fullname, and acupoint count, by name or full list. *Use when:* Use when an agent needs structured data about TCM meridians — either a specific meridian by Chinese or English name, or the complete list of all 14 meridians with their acupoint counts. *Not for:* Do not use for individual acupoint details or acupuncture point locations; this endpoint returns meridian-level data only, not point-level data. **Inputs:** - `name` (string) — Meridian name to filter by (e.g. 肺 or Lung, 心 or Heart). Omit to return all 14 meridians. **Returns:** Returns count=14 and a list of all 14 meridians (12 main + Ren + Du), each with name, fullname, and points_count; e.g. 膀胱经 has 67 points. **Example:** `GET https://api.cn402.com/tcm/meridian` --- ### `fetch-chinese-festival-customs` **Chinese Festival Customs** — Returns traditional Chinese festival customs, auspicious/inauspicious activities, and traditional foods for a given date or named festival. *Use when:* Use when an agent needs cultural details about a traditional Chinese festival — including customs, recommended/avoided activities, and traditional foods — for a specific date or festival name such as 春节 or 中秋节. *Not for:* Do not use for general Chinese calendar or lunar date conversion; this endpoint returns cultural customs data, not calendar arithmetic or horoscope readings. **Inputs:** - `date` (string) — Date in YYYY-MM-DD format to look up festival customs for. Defaults to today if omitted. - `festival` (string) — Festival name in Chinese or English (e.g. 春节 or Spring Festival) to retrieve customs for a specific festival regardless of date. **Returns:** Returns a festival object with name, customs array (e.g. 贴春联, 放鞭炮), auspicious/inauspicious activity lists, traditional foods, and cultural meaning for the matched festival. **Example:** `GET https://api.cn402.com/folk/festival-custom?festival=春节` --- ### `fetch-iching-random-hexagram` **I Ching Random Hexagram** — Returns a randomly drawn I Ching hexagram using the three-coin six-line method, including the primary hexagram, changed hexagram, changing lines, and traditional Chinese judgment and image texts. *Use when:* Use when an agent or user requests a random I Ching divination reading, needs a hexagram draw with changing lines, or wants traditional Yijing text (tuan, xiang) for interpretation or fortune-telling purposes. *Not for:* Do not use for looking up a specific hexagram by number or name; this endpoint returns a random draw only and accepts no query parameters to select a hexagram. **Returns:** Returns a full six-line hexagram draw with yao values, primary hexagram (ben_gua) and changed hexagram (bian_gua) objects containing name, trigrams, element, and classical tuan/xiang texts, plus changing line positions and interpretive advice. **Example:** `GET https://api.cn402.com/iching/random` --- ### `fetch-tcm-constitution-analysis` **TCM Constitution Analyzer** — Submits scored answers for a Traditional Chinese Medicine 9-constitution quiz and returns the dominant constitution type with recommendations. *Use when:* Use when an agent has collected 60 numeric scores (1–5 per question) from a TCM constitution questionnaire and needs to determine the user's dominant TCM body constitution type along with health recommendations. *Not for:* Do not use to retrieve the questionnaire itself (questions, scoring rules, constitution descriptions) — call the same endpoint with no query params for that. Not suitable for general health diagnosis or non-TCM wellness assessments. **Inputs:** - `answers` (string, required) — Comma-separated 1–9 numeric scores for 9 questions representing the aggregated scores per constitution type. Each value corresponds to one of the 9 TCM constitution categories (A–I). **Returns:** Returns the dominant TCM constitution type key and English name, a scores object for all 9 types, and an array of health recommendations for the dominant type. **Example:** `GET https://api.cn402.com/tcm/constitution?answers=3,2,4,1,2,3,2,1,3` --- ### `fetch-tcm-solar-term-health-guide` **Solar Term Health Guide** — Returns Traditional Chinese Medicine seasonal health advice for the current or a specified date, including the active solar term (jieqi), adjacent terms, and diet/lifestyle recommendations. *Use when:* Use when an agent needs TCM-based health guidance tied to the Chinese 24 solar terms calendar, such as dietary advice, lifestyle tips, or organ focus for a given date or today. *Not for:* Do not use for Western medical advice, general nutrition databases, or real-time weather data. Not suitable for querying historical health records or personalized medical diagnoses. **Inputs:** - `date` (string) — Date in YYYY-MM-DD format to retrieve solar term health advice for. Defaults to today if omitted. **Returns:** Returns the active solar term (e.g. 小满), previous and next jieqi with dates, and a TCM advice object covering health focus, recommended diet, foods to avoid, and behavioral guidance. **Example:** `GET https://api.cn402.com/tcm/season?date=2026-05-28` --- ### `fetch-chinese-almanac-today` **Today Almanac API** — Returns Chinese almanac data for a given date including auspicious activities (yi), avoid activities (ji), lunar date, ganzhi, zodiac, solar term, and festival. *Use when:* Use when an agent needs date-specific Chinese almanac information such as auspicious or inauspicious activities, lunar calendar details, zodiac, or solar term (jieqi) for today or a specified date. *Not for:* Do not use for detailed almanac breakdowns beyond the daily summary; use the /almanac endpoint instead. Not suitable for Gregorian calendar conversions or non-Chinese calendar systems. **Inputs:** - `date` (string) — Date in YYYY-MM-DD format to retrieve almanac data for. Defaults to today in Asia/Shanghai timezone if omitted. **Returns:** Returns a JSON object with the Gregorian date, lunar date, ganzhi, zodiac, solar term state, yi (auspicious) and ji (avoid) activity lists, lucky directions, and festival info for the requested date. **Example:** `GET https://api.cn402.com/today?date=2026-05-28` --- ### `convert-gregorian-to-lunar` **Lunar Date Converter** — Converts a Gregorian calendar date to Chinese lunar calendar date, including lunar year/month/day, leap-month flag, ganzhi pillars, zodiac sign, and weekday. *Use when:* Use when an agent needs to convert a specific Gregorian date (or today's date) to its Chinese lunar calendar equivalent, including traditional ganzhi stems-and-branches, zodiac animal, and leap-month status. *Not for:* Do not use for converting lunar dates back to Gregorian, or for Western astrological calculations; this endpoint is specific to the Chinese lunisolar calendar system. **Inputs:** - `date` (string) — Gregorian date to convert in YYYY-MM-DD format. Defaults to today's date if omitted. **Returns:** Returns solar_date, a lunar_date object with year/month/day/leap_month and Chinese numeral strings, ganzhi year/month/day pillars, zodiac animal, and weekday in Chinese. **Example:** `GET https://api.cn402.com/lunar?date=2026-05-28` --- ### `fetch-cn-festival-calendar` **CN Festival Calendar** — Returns a list of Chinese festivals for a given year, including Gregorian solar dates, lunar dates, and Chinese names, with the current year as default. *Use when:* Use when an agent needs to look up Chinese public holidays or traditional festivals (e.g., Spring Festival, Mid-Autumn Festival) for a specific year, including their Gregorian and lunar calendar dates. *Not for:* Do not use for non-Chinese holiday calendars or for real-time event scheduling; use a general calendar API for other countries' holidays. **Inputs:** - `year` (integer) — The year to retrieve festivals for, in YYYY format. Defaults to the current year if omitted. **Returns:** Returns year, count (24), and a festivals array with Chinese name, type (Gregorian or lunar), solar_date, and optional lunar_date for each festival in the requested year. **Example:** `GET https://api.cn402.com/festival/cn?year=2026` ---