西方占星-馬克思盤 (Marks)

文件說明

馬克思盤（Marks Chart，簡稱馬盤）是西方關係占星學中探討雙方在互動中「真實心理心態與主觀內在態度」的權威工具。其數學邏輯是先計算出兩人的時空中點（Davison Midpoint），再將該時空盤與特定對象的個人本命盤進行「二次中點幾何折衷」。馬盤以第一人稱單向心態視角深度剖析「盤主在這段關係中的內在真實感受與心結」，或是「對方心底究竟如何看待我」。

自動時區與日光節約時間 (DST)處理： 開發者只需傳入 IANA 標準時區（如 Asia/Shanghai），API將自動檢索全球歷史時區資料庫，完美處理不同年份的日光節約時間 (DST)偏移，無需手動換算 UTC。
關於真太陽時： 西方占星基於絕對 UTC 時間與地理坐標計算恒星時，無需額外計算真太陽時。請勿將換算後的真太陽時帶入API，以免造成坐標偏差。
高性能資料壓縮支援： 強烈建議在生產環境開啟 compress=1 API將採用標準 GZIP 演算法壓縮報文，可大幅縮減報文體積，顯著提升API 回應速度，並節省伺服器外網頻寬成本。
多維度資料輸出： API不僅返回原始的 JSON 坐標資料，還同步下發高解析度的 SVG 向量星盤圖，支援前端直接渲染。點擊此處訪問 前端星盤SVG渲染開發文件
標準化資料映射： 為了確保前後端邏輯的嚴謹對接，API返回的所有天體程式碼、相位型別、星座 ID 及宮位主題均採用標準化的數值枚舉。點擊此處訪問 資料集合 - 西方占星枚舉表

請求方式

POST GET

https://api.yuanfenju.com/index.php/v1/Astrology/marks

請求標頭 (Headers)

欄位	型別	描述
Content-Type	String	application/x-www-form-urlencoded

請求參數

欄位	型別	描述
api_key	String	存取金鑰 (API Key)
person_a_year	Int	A方公曆出生年例: 1988
person_a_month	Int	A方公曆出生月例: 8
person_a_day	Int	A方公曆出生日例: 7
person_a_hours	Int	A方公曆出生時(0-23) 例: 12
person_a_minute	Int	A方公曆出生分 (0-59) 例: 30 `如果不知道具體分，可以傳數字 0`
person_a_sex	Int	A方性別 0男 1女
person_a_longitude	Float	A方出生十進位經度例：-77.036871 `選填，預設北京經度。經度範圍：-180～180，浮點數，小數點後最多6位。`
person_a_latitude	Float	A方出生十進位緯度例：38.907192 `選填，預設北京緯度。緯度範圍：-90～90，浮點數，小數點後最多6位。`
person_a_timezone	String	A方時區（IANA 格式），例：Asia/Shanghai `選填，預設 Asia/Shanghai 點擊此處查看完整時區列表。`
person_b_year	Int	B方公曆出生年例: 1988
person_b_month	Int	B方公曆出生月例: 8
person_b_day	Int	B方公曆出生日例: 7
person_b_hours	Int	B方公曆出生時(0-23) 例: 12
person_b_minute	Int	B方公曆出生分 (0-59) 例: 30 `如果不知道具體分，可以傳數字 0`
person_b_sex	Int	B方性別 0男 1女
person_b_longitude	Float	B方出生十進位經度例：-77.036871 `選填，預設北京經度。經度範圍：-180～180，浮點數，小數點後最多6位。`
person_b_latitude	Float	B方出生十進位緯度例：38.907192 `選填，預設北京緯度。緯度範圍：-90～90，浮點數，小數點後最多6位。`
person_b_timezone	String	B方時區（IANA 格式），例：Asia/Shanghai `選填，預設 Asia/Shanghai 點擊此處查看完整時區列表。`
subject	String	檢視心態視角主體例：a `選填，預設 a。支援參數： a：計算 A 對 B 的心態盤（A 視角看 B，揭示 A 的內在心理與真實態度） b：計算 B 對 A 的心態盤（B 視角看 A，揭示「我在對方眼中的真實模樣」）`
house_system	String	宮位制程式碼例：P `選填，預設 P` 支援參數：P, K, O, R, C, A, E, W, T, M, B, X, V
additional_objects	String	附加星體及虛點，英文逗號分隔，如：`1,2,7` `選填，預設空` 支援的編號： 1(宿命點 Vertex), 2(凱龍星 Chiron), 3(谷神星 Ceres), 4(智神星 Pallas), 5(婚神星 Juno), 6(灶神星 Vesta), 7(福點 Part of Fortune), 8(真交點 true Node), 9(平莉莉絲 mean Lilith), 10(普賽克 Psyche), 11(厄洛斯 Eros), 12(妊神星 Haumea), 13(鬩神星 Eris), 14(鳥神星 Makemake), 15(平交點 mean Node), 16(南交點 south Node)。
orb_model	Int	容許度 (Orb)模型，例：2 `選填，預設 2` 支援參數：1:嚴格(偏小), 2:標準(預設), 3:寬泛(偏大), 4:自定義
orb_conjunction	Float	合相 (0°) 容許度 (Orb)，例：8 `當 orb_model=4 時生效。選填，預設 8`
orb_semisextile	Float	半六分相 (30°) 容許度 (Orb)，例：2 `當 orb_model=4 時生效。選填，預設 2`
orb_sextile	Float	六分相 (60°) 容許度 (Orb)，例：6 `當 orb_model=4 時生效。選填，預設 6`
orb_square	Float	四分相 (90°) 容許度 (Orb)，例：6 `當 orb_model=4 時生效。選填，預設 6`
orb_trine	Float	三分相 (120°) 容許度 (Orb)，例：6 `當 orb_model=4 時生效。選填，預設 6`
orb_quincunx	Float	梅花相 (150°) 容許度 (Orb)，例：3 `當 orb_model=4 時生效。選填，預設 3`
orb_opposition	Float	對分相 (180°) 容許度 (Orb)，例：8 `當 orb_model=4 時生效。選填，預設 8`
lang	String	多語言：zh-cn 、zh-tw、en-us `選填，如果不傳遞這個參數，預設為 zh-cn`
compress	Int	是否開啟資料壓縮(標準壓縮模式)。例：1：開啟 2：關閉選填，如果不傳遞該參數，預設值為 2（返回純文字 JSON）。強烈推薦設定：占星排盤資料包含大量星體、宮位、相位交角等節點，報文較大。為大幅降低網路傳輸延遲，節省您的伺服器外網頻寬，強烈建議在生產環境傳入 compress=1。 API 回應機制與解壓縮說明（完全符合 HTTP 標準）：當 compress=1 時，本API會在底層進行 GZIP 壓縮，並下發標準的 Content-Encoding: gzip 回應標頭 (Headers)。對接端是否需要編寫解壓縮程式碼，取決於您所使用的 HTTP 請求用戶端： ✅ 情況一：使用現代高級 HTTP 庫（理論上無需任何修改）絕大多數現代封裝庫（如 Python requests、Java OkHttp / Spring WebClient、Node.js axios、Go net/http 等）在檢測到該 Header 時，會自動在底層靜默完成解壓縮。 👉 您無需編寫任何手動的解壓縮程式碼，像平常一樣直接獲取 Response Body 即可得到明文 JSON 資料。 ⚠️ 情況二：使用語言原生或底層網路模塊（需手動設定或解壓縮）如果您發現拿到的是亂碼或二進位資料流，說明您的原生用戶端不會自動處理 GZIP，此時需要您手動介入： 1. PHP 原生 cURL：無需寫解壓縮程式碼，但必須在發送請求前增加設定 curl_setopt($curl, CURLOPT_ENCODING, ""); 讓底層自動處理。 2. Java 11+ 原生 HttpClient：需以 HttpResponse.BodyHandlers.ofInputStream() 接收二進位資料流，並手動套用 GZIPInputStream 讀取還原。 3. 其他原生模塊：收到位元組資料流後，請呼叫對應語言的 GZIP 解壓縮函數（如 Python 的 gzip.decompress()）進行明文還原。

請求參數範例

$request_data = [
    'api_key' => 'FsF1CsVevk3N17w7oBkSydfSk',

    'person_a_year' => '1988',
    'person_a_month' => '11',
    'person_a_day' => '8',
    'person_a_hours' => '12',
    'person_a_minute' => '20',
    'person_a_sex' => 0,
    'person_a_longitude' => '116.407396',
    'person_a_latitude' => '39.904200',
    'person_a_timezone' => 'Asia/Shanghai',

    'person_b_year' => '1992',
    'person_b_month' => '6',
    'person_b_day' => '15',
    'person_b_hours' => '18',
    'person_b_minute' => '30',
    'person_b_sex' => 1,
    'person_b_longitude' => '121.473701',
    'person_b_latitude' => '31.230416',
    'person_b_timezone' => 'Asia/Shanghai',

    'subject' => 'a', // 視角主體：a 代表 A對B的心態盤，b 代表 B對A的心態盤
    'house_system' => 'P',
    'additional_objects' => '1,2,7', // 開啟宿命點、凱龍星、福點
    'orb_model' => '2',
    'compress' => '1', // 開啟資料壓縮以提高傳輸速度
];

回傳參數

欄位	型別	描述
errcode	String	狀態碼 0成功其它為失敗
errmsg	String	狀態碼說明
notice	String	聲明
data	Json	資料內容

成功回傳範例

為了方便開發者快速構建資料模型，以下是完整的核心 JSON 結構說明（已折疊重複的陣列項目）：

{
  "errcode": 0, // 狀態碼：0代表成功，其他代表失敗
  "errmsg": "請求成功",  // 狀態說明
  "notice": "本次測算結果僅供娛樂使用...",
  "data": {
    "base_info": { // 基礎排盤參數
      "chart_type": "marks", // 星盤型別：marks (馬克思盤固定值)
      "subject": "a",        // 檢視主體：a 代表 A看B的心態，b 代表 B看A的心態
      "subject_desc": "Person A to Person B", // 主體心態方向說明
      "person_a": {
        "gender": "male", //性別 (male男 / female女)
        "birthday": "1988-11-8 12:20:00", // A方 出生時間
        "longitude": 116.407396,          // A方 出生十進位經度
        "latitude": 39.904200,            // A方 出生十進位緯度
        "timezone": "Asia/Shanghai",      // A方 IANA時區
        "house_system": "P",              // A方 宮位制程式碼
        "numerology": "4"                 // A方 核心命理：西方生命密碼/生命靈數 (1-9)
      },
      "person_b": {
        // B方輸入參數，結構同上
      },
      "marks_info": {                     // 盤主馬克思盤二次中點資訊（本張心理盤的實際排盤時空基準）
        "gender": "male",                 // 視角主體性別
        "birthday": "1989-10-3 7:52:00", // 時空盤與主體本命盤的二次時間中點
        "longitude": 116.407396,          // 二次球面經度中點
        "latitude": 39.904200,            // 二次球面緯度中點
        "timezone": "Asia/Shanghai",      // 基準時區
        "house_system": "P",              // 採用的宮位制
        "numerology": "6"                 // 心態盤的生命靈數
      }
    },
    "detail_info": {
      "chart_data": { // 馬盤核心測算結果集合 (作為單盤實體)
        // ================= 1. 宮位與飛星資料 =================
        "housesData": [ // 12宮位資料集合 (馬盤自身的宮位)
          {
            "house_id": 1, // 宮位編號 (1-12)
            "house_life": "命宮", // 宮位中文含義，枚舉值請參閱 [資料集合-西方占星]
            "longitude": 205.585605, // 馬盤第一宮宮頭絕對經度
            "sign": { // 宮首落入星座資訊
              "sign_id": 6,// 星座系統編號(0-11)
              "sign_english": "Libra", //星座英文名稱，枚舉值請參閱 [資料集合-西方占星]
              "sign_chinese": "天秤",   //星座簡體中文，枚舉值請參閱 [資料集合-西方占星]
              "sign_chinese_traditional": "天秤",//星座繁體中文，枚舉值請參閱 [資料集合-西方占星]
              "sign_font": "G",     //星座圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
              "deg": 25, "min": 35, "sec": 8 // 宮頭所在的精確度分秒
            },
             "main_planet": [ // 守護星/宮主星資訊
              {
                "code_name": "6",   //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Saturn", //星體英文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese": "土星",    //星體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese_traditional": "土星",//星體繁體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_font": "Sa" //星體圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
              }
            ],
            "planet_array": [ // 宮內落入該馬盤 (Marks)的所有星體列表
               {
                "object_type": "angle", //天體型別，(planet行星/asteroid小行星/arabic_part阿拉伯點/angle四軸/lunar虛點)，枚舉值請參閱 [資料集合-西方占星]
                "code_name": "ASC",     //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Ascendant",//星體英文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese": "上升", //星體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese_traditional": "上升點 (Ascendant)",//星體繁體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_font": "Asc",   //星體圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
                "longitude": 298.7166572,// 絕對經度
                "speed": null,  // 運行速度，枚舉：正數代表非逆行，負數代表逆行，null代表不適用
                "is_retrograde": false, // 是否逆行標記，枚舉：true代表逆行，false代表非逆行
                "deg": 0, "min": 0, "sec": 0  // 星體在本宮內的相對度、分、秒
              }
            ],
            "ruler_fly_into": [ //宮主星飛星資訊(高階占星斷事必備)
              {
                "source_house_id": 1, // 起始宮位(1-12)，枚舉值跟 house_id 完全一致
                "main_planet_code_name": "6", //星體唯一標識，枚舉值跟 code_name 完全一致
                "main_planet_english": "Saturn",//星體英文名，枚舉值跟 planet_english 完全一致
                "main_planet_chinese": "土星",   //星體中文名，枚舉值跟 planet_chinese 完全一致
                "main_planet_chinese_traditional": "土星",//星體繁體中文名，枚舉值跟 planet_chinese_traditional 完全一致
                "fall_house_id": 11,    //飛入的目標宮位(1-12) (即：1宮主星飛11宮)，枚舉值跟 house_id 完全一致
                "fall_sign_id": 8,      //飛入的目標星座編號(0-11)，枚舉值跟 sign_id 完全一致
                "fall_sign_english": "Sagittarius", //落入星座英文，枚舉值跟 sign_english 完全一致
                "fall_sign_chinese": "射手",  //落入星座中文，枚舉值跟 sign_chinese 完全一致
                "fall_sign_chinese_traditional": "射手" //落入星座繁體中文，枚舉值跟 sign_chinese_traditional 完全一致
              }
            ]
          }
          // ... 剩餘 11 宮資料省略 ...
        ],

        // ================= 2. 星座狀態分布 =================
         "signData": [
          {
            "sign_id": 0,  // 星座系統編號(0-11)
            "sign_english": "Aries", //星座英文名稱，枚舉值請參閱 [資料集合-西方占星]
            "sign_chinese": "牡羊",   //星座中文名稱，枚舉值請參閱 [資料集合-西方占星]
            "sign_chinese_traditional": "牡羊", //星座繁體中文名稱，枚舉值請參閱 [資料集合-西方占星]
            "sign_font": "A", // 星座圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
            "sign_attribute": { // 星座元素與模式屬性(含多語言)
              "element":   // --- 四元素屬性 ---
                    {
                        "id": "fire", //元素標識符 (fire/earth/air/water)，枚舉值請參閱 [資料集合-西方占星]
                        "en": "Fire", //元素英文名，枚舉值請參閱 [資料集合-西方占星]
                        "zh": "火相",  //元素中文名，枚舉值請參閱 [資料集合-西方占星]
                        "zht": "火相"  //元素繁體中文名，枚舉值請參閱 [資料集合-西方占星]
                    },
              "mode":     // --- 三方四正/特質屬性 ---
                    {
                        "id": "cardinal", //特質標識符 (cardinal/fixed/mutable) ，枚舉值請參閱 [資料集合-西方占星]
                        "en": "Cardinal", //特質英文名 ，枚舉值請參閱 [資料集合-西方占星]
                        "zh": "本位",      //特質簡體中文 ，枚舉值請參閱 [資料集合-西方占星]
                        "zht": "本位"      //特質繁體中文 ，枚舉值請參閱 [資料集合-西方占星]
                    }
            },
            "sign_guardian": [ /* 預設守護星資訊 */
               {
                "code_name": "4",   //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Mars",//星體英文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese": "火星", //星體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese_traditional": "火星", //星體繁中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_font": "Ma" //星體圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
                }
            ],
            "planet_array": [ /* 當前落入該星座的星體列表 */
              {
                "object_type": "planet",//天體型別，(planet行星/asteroid小行星/arabic_part阿拉伯點/angle四軸/lunar虛點)，枚舉值請參閱 [資料集合-西方占星]
                "code_name": "4",   //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Mars", //星體英文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese": "火星",  //星體中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese_traditional": "火星", //星體繁中文名稱，枚舉值請參閱 [資料集合-西方占星]
                "planet_font": "Ma",    //星體圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
                "longitude": 0.6487775, // 絕對經度
                "house_id": 2, // 所在宮位(1-12)
                "speed": 0.1383146, //運行速度，枚舉：正數代表非逆行，負數代表逆行，null代表不適用
                "is_retrograde": false, // 是否逆行標記，枚舉：true代表逆行，false代表非逆行
                "deg": 0, "min": 38, "sec": 56 // 該星體在該星座內的相對度、分、秒
              }
            ]
          }
          // ... 剩餘 11 星座資料省略 ...
        ],

        // ================= 3. 行星交角與相對坐標 =================
        "planetData": [ // 馬盤星體詳細資料及內部相位集合
          {
            "object_type": "planet",//天體型別，(planet行星/asteroid小行星/arabic_part阿拉伯點/angle四軸/lunar虛點)，枚舉值請參閱 [資料集合-西方占星]
            "code_name": "0",
            "planet_english": "Sun",
            "planet_chinese": "太陽",
            "planet_chinese_traditional": "太陽",
            "planet_font": "Su",
            "speed": 1.0045795,
            "is_retrograde": false,
            "house_id": 9, // 落入宮位
            "house_longitude": 22.7125, // 宮內相對十進位經度
            "house_deg": 22, "house_min": 42, "house_sec": 45, // 宮內相對度、分、秒
            "sign": { // 落入星座及星座內相對度分秒
              "deg": 15,
              "min": 59,
              "sec": 3,
              "sign_id": 7,
              "sign_english": "Scorpio",
              "sign_chinese": "天蠍",
              "sign_chinese_traditional": "天蠍",
              "sign_font": "H"
            },
            "planet_allow_degree": [ // 相位交角列表(與其他星體形成的有效相位)
              {
                "object_type": "planet",
                "code_name": "9",
                "planet_english": "Pluto",
                "planet_chinese": "冥王星",
                "planet_chinese_traditional": "冥王星",
                "planet_font": "Pl",
                "current_longitude": 222.650268, // 目標星體絕對經度
                "allow": 120,// 相位基準角度 (0/30/60/90/120/150/180)
                "aspect_english": "Trine", //相位英文名，枚舉值請參閱 [資料集合-西方占星]
                "aspect_chinese": "拱相",   //相位中文名，枚舉值請參閱 [資料集合-西方占星]
                "aspect_chinese_traditional": "拱相", //相位繁體中文名，枚舉值請參閱 [資料集合-西方占星]
                "in_out": "1", // "1"代表入相(能量漸強), "-1"代表出相(能量漸弱), "0"代表無
                "deg": 3, "min": 20, "sec": 2 // 容許度 (Orb) 誤差，即實際交角與基準相位的偏差
              }
            ]
          }
          // ... 其他星體資料省略 ...
        ],

        "attributeData": { // 馬盤星體元素與模式能量統計
          "fire": [ ... ],  // 火元素星體集合
          "earth": [ ... ], // 土元素星體集合
          "air": [ ... ],   // 風元素星體集合
          "water": [ ... ], // 水元素星體集合
          "cardinal": [ ... ], // 本位星座分布
          "fixed": [ ... ],    // 固定星座分布
          "mutable": [ ... ]   // 變動星座分布
          "yang": [ /* 陽性星體列表 */ ],
          "yin": [ /* 陰性星體列表 */ ]
        },

        "patternData": [ // 馬盤內形成的整體相位格局
          {
            "pattern_id": "yod", //格局標識ID ，枚舉值請參閱 [資料集合-西方占星]
            "pattern_en": "Yod", //格局英文名 ，枚舉值請參閱 [資料集合-西方占星]
            "pattern_zh": "上帝之指", //格局中文名 ，枚舉值請參閱 [資料集合-西方占星]
            "pattern_zht": "上帝之指",//格局繁體中文名 ，枚舉值請參閱 [資料集合-西方占星]
            "objects": [ /* 構成該格局的具體星體列表 */ ]
          }
          // ... 其他格局省略 ...
        ]
      },

      // ================= 5. 專業解讀與高解析渲染圖 =================
      "chart_description": {  // 多維度結構化解析文本（依據請求參數 lang 自動切換 zh-cn/zh-tw/en-us）
        "summary": [ // 【陣列】馬盤心理核心基調（日月主觀心態配置總結）
          {
            "target": "馬盤太陽天蠍座，月亮雙魚座",
            "description": "面對對方時，對另一半抱有極深的情感依戀與佔有慾，內心敏銳且充滿執念..."
          }
        ],
        "houses": [], // 【陣列】馬盤宮頭無實質獨立意義，置空佔位（保持單盤大一統 Schema 規範）
        "planets": { // 【物件】馬盤核心行星落星座與落宮深度解析（主觀心理訴求）
          "sign": [
            {
              "target": "馬盤太陽落入天蠍座",
              "description": "面對對方時，在與對方相處時表現出極強的控制欲、排他性與深層執著..."
            }
          ],
          "house": [
            {
              "target": "馬盤太陽落入第8宮",
              "description": "面對對方時，渴望與對方進行深度的靈魂綁定與資源信任交互..."
            }
          ]
        },
        "angles": [ // 【陣列】馬盤四軸點（上升/天頂/下降/天底）落星座解析
          {
            "target": "馬盤上升落入天秤座",
            "description": "面對對方時，在對方面前表現出客氣、配合、溫和且注重表面和諧的外在態度..."
          }
        ],
        "aspects": [  // 【陣列】馬盤內部心理矛盾與行動驅動相位解析
          {
            "target": "馬盤太陽 合相 土星",
            "description": "面對對方時，這段關係時感到沉重的責任與克制，容易產生壓抑感或長期承諾負擔..."
          }
        ]
      },

      "chart_svg": "<svg>...</svg>" // 高精度星盤向量圖源碼(詳見前端SVG圖片開發文件)
    }
  }
}

失敗回傳範例

{
  "errcode": -1,
  "errmsg": "經度必須在 -180 ~ 180 之間"
}