西方占星-比較盤 (Synastry)

文件說明

        西占比較盤 (Synastry)是西方占星學中用於解析雙人關係（如情侶、合夥人、親子關係）的核心工具。它通過將兩人的本命星盤進行物理位置上的相互疊加，精準計算一方星體落入另一方具體宮位的情況（即環境與領域的影響），以及雙方星體間形成的有效相位交角（即能量間的化學反應），從而全面剖析兩人的吸引力、契合度、衝突點及緣分深淺。

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

請求方式

POST GET 

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

請求標頭 (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
點擊 此處 查看完整時區列表。
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' => '1999',
    'person_b_month' => '11',
    'person_b_day' => '8',
    'person_b_hours' => '12',
    'person_b_minute' => '20',
    'person_b_sex' => 1,
    'person_b_longitude' => '116.407396',
    'person_b_latitude' => '39.904200',
    'person_b_timezone' => 'Asia/Shanghai',

    '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": "synastry", // 星盤型別：synastry (比較盤 (Synastry)固定值)
      "person_a": {
        "gender": "male", //性別(male男/female女)
        "birthday": "1988-11-8 12:20:00", // A方 出生時間
        "longitude": 116.407396,        // A方 出生十進位經度
        "latitude": 39.9042,            // A方 出生十進位緯度
        "timezone": "Asia/Shanghai",      // A方 IANA時區
        "house_system": "P",              // A方 宮位制程式碼
        "numerology": "9"                 // A方 核心命理：西方生命密碼/生命靈數(1-9)
      },
      "person_b": {
        "gender": "female", //性別(male男/female女)
        "birthday": "1990-10-12 14:45:00", // B方 出生時間
        "longitude": 116.422400,         // B方 出生十進位經度
        "latitude": 39.934827,           // B方 出生十進位緯度
        "timezone": "Asia/Shanghai",       // B方 IANA時區
        "house_system": "P",               // B方 宮位制程式碼
        "numerology": "4"                  // B方 核心命理：西方生命密碼/生命靈數(1-9)
      }
    },
    "detail_info": {
      "chart_data": { // 核心測算結果集合
        // ================= 1. 雙方本命星盤基礎資料 =================
        "person_a_natal": { ... }, // A方本命星盤除了 patternData 之外的完整資料，包含 housesData/signData/planetData/attributeData，結構同本命星盤 API，可參考本命星盤資料，此處省略以節省篇幅。
        "person_b_natal": { ... }, // B方本命星盤除了 patternData 之外的完整資料，結構同上。

        // ================= 2. 比較盤 (Synastry)深度比對交互資料 =================
        "synastry": {
          "meta": { // 比對資料複雜度元統計
            "object_count_a": 14,       // A方啟用的星體與虛點總數
            "object_count_b": 14,       // B方啟用的星體與虛點總數
            "planet_aspect_count": 34,  // 雙方構成的有效星體交角總數
            "house_overlay_count": 28   // 星體落入彼此宮位的總交互次數
          },

          "planet_aspects": [ // 雙方星體形成的交叉相位列表
            {
              "from": "A_0", // 發起方標識：A方太陽 (A_後面跟星體的唯一識別碼 code_name)，枚舉值請參閱 [資料集合-西方占星-code_name]
              "to": "B_6",   // 接收方標識：B方土星 (B_後面跟星體的唯一識別碼 code_name)，枚舉值請參閱 [資料集合-西方占星-code_name]
              "planet_a": { // A方發生相位的星體及狀態
                "code_name": "0",   //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Sun", //星體英文名，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese": "太陽", //星體中文名，枚舉值請參閱 [資料集合-西方占星]
                "planet_chinese_traditional": "太陽", //星體繁體中文名，枚舉值請參閱 [資料集合-西方占星]
                "planet_font": "Su",//星體圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
                "longitude": 6.405695,// 絕對經度
                "speed": 0.9899524,  //運行速度，枚舉：正數代表非逆行，負數代表逆行，null代表不適用
                "is_retrograde": false, // 是否逆行標記，枚舉：true代表逆行，false代表非逆行
                "sign": { // 該星體所在星座資訊
                  "deg": 6, "min": 24, "sec": 21, //星體所在星座精準度、分、秒
                  "sign_id": 0, /// 星座系統編號(0-11)
                  "sign_english": "Aries",
                  "sign_chinese": "牡羊",
                  "sign_chinese_traditional": "牡羊",
                  "sign_font": "A" //星座圖標映射碼，枚舉值請參閱 [資料集合-西方占星]
                }
              },
              "planet_b": { // B方發生相位的星體及狀態
                "code_name": "6",
                "planet_english": "Saturn",
                "planet_chinese": "土星",
                "planet_chinese_traditional": "土星",
                "planet_font": "Sa",
                "longitude": 4.9334618,
                "speed": 0.1248473,
                "is_retrograde": false,
                "sign": {
                  "deg": 4, "min": 56, "sec": 0,
                  "sign_id": 0,
                  "sign_english": "Aries",
                  "sign_chinese": "牡羊",
                  "sign_chinese_traditional": "牡羊",
                  "sign_font": "A"
                }
              },
              "aspect": { // 形成的具體相位資訊
                "allow": 0,                   // 發生相位的基準角度 (0/30/60/90/120/150/180)
                "aspect_english": "Conjunction",//相位英文名，枚舉值請參閱 [資料集合-西方占星]
                "aspect_chinese": "合相 (0°)", //相位中文名，枚舉值請參閱 [資料集合-西方占星]
                "aspect_chinese_traditional": "合相 (0°)",//相位繁體中文名，枚舉值請參閱 [資料集合-西方占星]
                "orb": 1.4722332,             // 容許度 (Orb) 誤差 (實際角度差與基準角度的偏差度數)
                "deg": 0, //容許度 (Orb) 誤差轉化為度結構
                "min": 0, //容許度 (Orb) 誤差轉化為分結構
                "sec": 0, //容許度 (Orb) 誤差轉化為秒結構
                "in_out": "0", // "1"代表入相(能量漸強), "-1"代表出相(能量漸弱), "0"代表無
                "type": "positive",           // 相位性質 (positive積極/challenging挑戰/neutral中性)
                "strength": 0.836,            // 相位綜合能量強度得分，取值範圍 [0.05, 2.0]。值越大代表相位能量越強（前端可根據此值域，使用插值演算法動態調節連線的粗細或不透明度，例如：1.5以上畫粗實線，0.5以下畫細虛線）。
                "polarity": "fusion"          // 相位語義極性分類 (fusion強烈融合/flow和諧流動/friction衝突成長/integrative_tension整合張力)
              }
            }
            // ... 其他幾十組相位資料省略 ...
          ],

          "aspect_links": [ // 相位連線精簡資料集合 (供前端可視化連線直接使用)
            {
              "from": "A_0",
              "to": "B_6",
              "aspect": "Conjunction",
              "type": "positive",
              "orb": 1.4722332,
              "in_out": "-1",
              "strength": 0.836,
              "polarity": "fusion"
            }
          ],

          "house_overlay_a_in_b": [ // A方星體落入B方宮位資料 (外圈A影響內圈B)
            {
              "planet": { // 產生影響的 A 方行星
                "code_name": "0", //星體的唯一標識符，枚舉值請參閱 [資料集合-西方占星]
                "planet_english": "Sun",
                "planet_chinese": "太陽",
                "planet_chinese_traditional": "太陽",
                "planet_font": "Su",
                "longitude": 6.405695,
                "speed": 0.9899524,
                "is_retrograde": false,
                "sign": {
                    "deg": 6,
                    "min": 36,
                    "sec": 23,
                    "sign_id": 0,
                    "sign_english": "Aries",
                    "sign_chinese": "牡羊",
                    "sign_chinese_traditional": "牡羊",
                    "sign_font": "A"
                }
              },
              "house_id": 11, // 落入 B 方的具體宮位 ID， 枚舉：1～12
              "house_name": "福德宮", // B方宮位含義
              "relative_deg": 10.2035627, // 在 B方該宮位內的相對偏移度數
              "relative_dms": { "deg": 10, "min": 12, "sec": 13 }, // 相對偏移換算的度分秒
              "house_theme": "friends_hopes", // 宮位主管主題方向，枚舉值請參閱 [資料集合-西方占星]
              "house_weight": 1, // 宮位先天影響力權重，取值範圍 [1.0, 1.4]，枚舉值請參閱 [資料集合-西方占星]
              "overlay_strength": 1.43, // 本次落宮對雙人關係的能量強化得分，取值範圍 [0.57, 2.0]。值越大代表該星體對該宮位領域的影響越具統治力。
              "house_focus_level": "high" // 落宮焦點等級 (high高/medium中/low低)
            }
            // ... A方其它星體的落宮資料省略 ...
          ],

          "house_overlay_b_in_a": [ // B方星體落入A方宮位資料 (外圈B影響內圈A)
            // 資料結構同上 `house_overlay_a_in_b`
          ],

          "angle_contacts": [ //計算並記錄 「A的四軸/敏感點」 與 「B的星體」 之間的相位互動（以及 B的四軸 與 A的星體）
            {
              "type": "A_angle_to_B_planet", //觸發方向標識，枚舉值："A_angle_to_B_planet" (代表 A 的四軸/敏感點，被 B 的行星觸發了)，"B_angle_to_A_planet" (代表 B 的四軸/敏感點，被 A 的行星觸發了)
              "angle_english": "Ascendant", //四軸/敏感點資訊英文名，枚舉值：Ascendant//Midheaven/ImumCoeli/Descendant/Vertex
              "angle_chinese": "上升", //四軸/敏感點資訊中文名，枚舉值：上升/天頂 (Midheaven/MC)/天底 (Imum Coeli/IC)/下降/宿命點
              "angle_chinese_traditional": "上升點 (Ascendant)", //四軸/敏感點資訊繁體中文名，枚舉值：上升點 (Ascendant)/天頂 (Midheaven/MC)/天底 (Imum Coeli/IC)/下降點 (Descendant)/宿命點
              "planet_english": "Sun", //星體英文名稱，枚舉值請參閱 [資料集合-西方占星]
              "planet_chinese": "太陽", //星體中文名稱，枚舉值請參閱 [資料集合-西方占星]
              "planet_chinese_traditional": "太陽", //星體繁體中文名稱，枚舉值請參閱 [資料集合-西方占星]
              "allow": 90, // 發生相位的基準角度 (0/30/60/90/120/150/180)
              "aspect_english": "Square", //相位英文名，枚舉值請參閱 [資料集合-西方占星]
              "aspect_chinese": "四分相 (90°)", //相位中文名，枚舉值請參閱 [資料集合-西方占星]
              "aspect_chinese_traditional": "四分相 (90°)", //相位繁體中文名，枚舉值請參閱 [資料集合-西方占星]
              "orb": 5.7248766, // 容許度 (Orb) 誤差 (實際角度差與基準角度的偏差度數)
              "deg": 5, "min": 43, "sec": 30, //誤差換算 度分秒
              "in_out": "0", // "1"代表入相(能量漸強), "-1"代表出相(能量漸弱), "0"代表無，注意：因為四軸是數學虛點沒有物理運行速度，所以在 angle_contacts 中該欄位永遠固定輸出 "0"
              "aspect_type": "challenging", //相位吉凶屬性，枚舉值：positive(和諧)/challenging(挑戰)/neutral(中性)，可參閱 [資料集合-西方占星]
              "strength": 0.054, //相位綜合強度得分，浮點數，範圍通常在 0.05 ~ 2.0 之間。低於 0.05 的噪音已被過濾，分數越高說明該觸發現象在關係中越震撼/宿命。
              "polarity": "neutral" //能量極性/語義標籤，用於輔助解讀器或前端生成更細膩的文案，枚舉值：fusion/integrative_tension/flow/friction/neutral，可參閱 [資料集合-西方占星]
            }
            // ... 其它相位互動資料省略 ...
          ],
        }
      },

      // ================= 3. 專業文案與高精渲染圖=================
        "chart_description": {  //多維度結構化解析文案，內容根據請求參數 lang 自動切換 zh-cn/zh-tw/en-us）
          "summary": [ // 【陣列】雙人互動基調總述
            {
              "target": "雙人互動基調：高強度羈絆", // 解析的主題標籤
              "description": "你們之間有著專屬的磁場..."   // 詳盡的文案描述
            }
          ],
          "houses": { // 【物件】行星落入對方宮位的深度解析（區分主客體）
            "a_in_b": [ // A方行星落入B方宮位的解析列表
              {
                "target": "A盤太陽落入B盤第8宮",
                "description": "A的太陽落入B的第八宮..."
              }
            ],
            "b_in_a": [ // B方行星落入A方宮位的解析列表
              {
                "target": "B盤太陽落入A盤第8宮",
                "description": "B的太陽落入A的第八宮..."
              }
            ]
          },
          "planets": [], //【重要】比較盤 (Synastry)此處文案無意義，固定為空陣列
          "aspects": [  //【陣列】雙人星體交角（相位）的深度互動解析
            {
              "target": "A盤月亮 合相 (0°) B盤月亮",
              "description": "A的月亮與B的月亮形成合相 (0°)，能量高度重疊..."
            }
          ],
          "angles": [ // 【陣列】四軸點（Asc/Mc/Ic/Dsc）與對方行星的互動解析
            {
              "target": "A盤上升 三分相 (120°) B盤金星",
              "description": "A的金星與B的上升成拱相..."
            }
          ]
        },
      "chart_svg": { // 雙人合盤雙輪 SVG 向量圖源碼 (詳見前端SVG圖片開發文件)
        "a_in_b": "<svg>...</svg>", // 視角一：B 盤在內圈，A 盤在外圈
        "b_in_a": "<svg>...</svg>"  // 視角二：A 盤在內圈，B 盤在外圈
      }
    }
  }
}

失敗回傳範例

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