西方占星-法達星限 (Firdaria)

文件說明

        法達星限(Firdaria)是古典西方占星學中嚴謹的分時大運體系。系統首先採用黃道幾何地平演算法精準判定盤主為日生盤(Day Chart)或夜生盤(Night Chart),進而分配不同的七政星體執政順序,開展為期 75 年的人生大運與子運時間軸。API 內部自動對齊盤主當前自然年齡,精準鎖定當前正在行進的大限主星與子運主星,深度剖析當前運勢主題、財富事業突破點與潛在考驗。

  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 及宮位主題均採用標準化的數值枚舉。點擊 此處 訪問 資料集合 - 西方占星枚舉表

請求方式

POST GET

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

請求標頭 (Headers)

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

請求參數

欄位 型別 描述
api_key String 存取金鑰 (API Key)
year Int 公曆出生年 例: 1988
month Int 公曆出生月 例: 8
day Int 公曆出生日 例: 7
hours Int 公曆出生時(0-23) 例: 12
minute Int 公曆出生分 (0-59) 例: 30     
如果不知道具體分,可以傳數字 0
sex Int 性別 0男 1女
longitude Float 出生十進位經度 例:-77.036871    
選填,預設北京經度。
經度範圍:-180~180,浮點數,小數點後最多6位。
latitude Float 出生十進位緯度 例:38.907192    
選填,預設北京緯度。
緯度範圍:-90~90,浮點數,小數點後最多6位。
timezone String 時區(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',
    'year' => '1988',
    'month' => '11',
    'day' => '8',
    'hours' => '12',
    'minute' => '20',
    'sex'    => 1,
    'longitude' => '116.407396',
    'latitude' => '39.904200',
    '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": "firdaria", // 星盤型別:firdaria (法達星限固定值)
      "is_day_chart": true,     // 晝夜盤判定:true 代表日生盤,false 代表夜生盤
      "chart_sect": "Day (日生盤)", // 晝夜盤文字描述(支援多語言)
      "current_period": {       // ⭐ 系統精準鎖定的當事人【當前正在走】的大限與子運
        "major": {              // 當前大限主星
          "planet": "Sun",
          "planet_english": "Sun",
          "planet_chinese": "太陽",
          "planet_chinese_traditional": "太陽",
          "start_time": "2026-03-27 20:03:00", // 當前大限開始時間
          "end_time": "2036-03-27 20:03:00"   // 當前大限結束時間
        },
        "sub": {                // 當前子運主星
          "sub_planet": "Venus",
          "planet_english": "Venus",
          "planet_chinese": "金星",
          "planet_chinese_traditional": "金星",
          "start_time": "2026-03-27 20:03:00",
          "end_time": "2027-08-28 17:08:34"
        }
      },
      "natal_info": {           // 盤主本命基礎資訊
        "gender": "male",
        "birthday": "1988-11-8 12:20:00",
        "longitude": 116.407396,
        "latitude": 39.904200,
        "timezone": "Asia/Shanghai",
        "house_system": "P",
        "numerology": "4"
      }
    },
    "detail_info": { // 核心排盤資料與解析
      // ================= 1. 法達 75 年大限與子運完整時間軸 =================
      "firdaria_timeline": [ // 75年大運時間軸完整集合
        {
          "major_planet": "Sun", // 大運主星代碼
          "planet_english": "Sun",
          "planet_chinese": "太陽",
          "planet_chinese_traditional": "太陽",
          "years": 10,           // 掌管年限 (日生盤太陽管10年)
          "start_time": "2026-03-27 20:03:00", // 本大限開始時間
          "end_time": "2036-03-27 20:03:00",   // 本大限結束時間
          "sub_periods": [       // 該大限內部細分的 7 個子運區間
            {
              "sub_planet": "Sun",
              "planet_english": "Sun",
              "planet_chinese": "太陽",
              "planet_chinese_traditional": "太陽",
              "start_time": "2026-03-27 20:03:00",
              "end_time": "2027-08-28 17:08:34"
            },
            {
              "sub_planet": "Venus",
              "planet_english": "Venus",
              "planet_chinese": "金星",
              "planet_chinese_traditional": "金星",
              "start_time": "2027-08-28 17:08:34",
              "end_time": "2029-01-29 02:17:08"
            }
            // ... 其餘子運區間省略 ...
          ]
        }
        // ... 其餘大限階段省略 (金星8年、水星13年、月亮9年等,共計75年) ...
      ],

      // ================= 2. 本命星盤核心天象資料 =================
      "chart_data": { // 盤主本命單盤資料,法達演算法依此評估大運主星落座、落宮與受剋狀態
        "housesData": [ ... ],
        "signData": [ ... ],
        "planetData": [ ... ],
        "attributeData": { ... },
        "patternData": [ ... ]
      },

      // ================= 3. 法達大運專屬解析文案 =================
      "chart_description": { // 多維度大運解析(根據請求參數 lang 自動切換 zh-cn/zh-tw/en-us)
        "summary": [ // 【陣列】法達大運總綱(日生/夜生大運總論)
          {
            "target": "日生盤法達大運總綱",
            "description": "太陽為主導星的日生盤,人生發展往往依托於個人目標、名譽聲望與自我意志的顯化..."
          }
        ],
        "houses": [], // 【重要】法達不解讀靜態宮頭,置空佔位
        "planets": {  // 【物件】法達大運核心星體落座與落宮深度解讀
          "sign": [
            {
              "target": "大運星【太陽】落入天蠍座",
              "description": "當行至太陽大運時,太陽落入天蠍座意味著這個階段充滿深刻蛻變與意志考驗..."
            }
          ],
          "house": [
            {
              "target": "大運星【太陽】落入第8宮",
              "description": "太陽行運掌管第八宮生活領域,此階段焦點涉及財務整合、共有資產及深刻危機轉化..."
            }
          ]
        },
        "angles": [], // 【重要】法達不看四軸大運,置空佔位
        "aspects": [  // 【陣列】大運主星與本命盤其他主星的相位連動(判定運勢阻力與助力)
          {
            "target": "太陽 合相 (0°) 土星",
            "description": "大運主星太陽遇土星合相,代表該運程期內責任重大,需腳踏實地累積,方能化阻力為成就..."
          }
        ]
      },

    "chart_svg": "<svg>...</svg>" // 高解析度星盤向量圖原始碼
    }
  }
}

失敗回傳範例

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