西方占星-行运盘

文档说明

        西占行运盘是基于当下天体运行位置与本命盘星体、宫位形成的相位互动，通过分析行运星体触发的能量影响，解读个人在特定阶段的运势起伏、外在事件、心境变化与发展机遇。它以本命盘为基础，是占星体系中用于判断阶段性运势走向、把握时机与规避风险的实用分析方法。

  1. 自动时区与夏令时（DST）处理： 开发者只需传入 IANA 标准时区（如 Asia/Shanghai），接口将自动检索全球历史时区数据库，完美处理不同年份的夏令时偏移，无需手动换算 UTC。
  2. 关于真太阳时： 西方占星基于绝对 UTC 时间与地理坐标计算恒星时，无需额外计算真太阳时。请勿将换算后的真太阳时带入接口，以免造成坐标偏差。
  3. 高性能数据压缩支持： 强烈建议在生产环境开启 compress=1 接口将采用标准 GZIP 算法压缩报文，可大幅缩减报文体积，显著提升接口响应速度，并节省服务器外网带宽成本。
  4. 多维度数据输出： 接口不仅返回原始的 JSON 坐标数据，还同步下发高解析度的 SVG 矢量星盘图，支持前端直接渲染。点击 此处 访问 前端星盘SVG渲染开发文档
  5. 标准化数据映射： 为了确保前后端逻辑的严精对接，接口返回的所有天体代码、相位类型、星座 ID 及宫位主题均采用标准化的数值枚举。点击 此处 访问 数据集合 - 西方占星枚举表

请求方式

POST GET 

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

请求头

字段 类型 描述
Content-Type String application/x-www-form-urlencoded

请求参数

字段 类型 描述
api_key String 密钥
year Int 公历出生年 例: 1988
month Int 公历出生月 例: 8
day Int 公历出生日 例: 7
hours Int 公历出生时(0-23) 例: 12
minute Int 公历出生分 (0-59) 例: 30     
如果不知道具体分，可以传数字 0
sex Int 性别 0男 1女
target_year Int 公历推运年 例: 1988
target_month Int 公历推运月 例: 8
target_day Int 公历推运日 例: 7
target_hours Int 公历推运时(0-23) 例: 12
target_minute Int 公历推运分 (0-59) 例: 30     
如果不知道具体分，可以传数字 0
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 容许度模型，例：5
非必传，默认 5
支持参数：1:严格, 2:标准, 3:宽泛, 4:自定义, 5:推运专用(全相位1度默认)
orb_conjunction Float 合相 (0°) 容许度，例：8
当 orb_model=4 时生效。 非必传，默认 8
orb_semisextile Float 半六分相 (30°) 容许度，例：2
当 orb_model=4 时生效。 非必传，默认 2
orb_sextile Float 六分相 (60°) 容许度，例：6
当 orb_model=4 时生效。 非必传，默认 6
orb_square Float 四分相 (90°) 容许度，例：6
当 orb_model=4 时生效。 非必传，默认 6
orb_trine Float 三分相 (120°) 容许度，例：6
当 orb_model=4 时生效。 非必传，默认 6
orb_quincunx Float 梅花相 (150°) 容许度，例：3
当 orb_model=4 时生效。 非必传，默认 3
orb_opposition Float 对分相 (180°) 容许度，例：8
当 orb_model=4 时生效。 非必传，默认 8
lang String 多语言：zh-cn 、zh-tw     
非必传，如果不传递这个参数，默认为 zh-cn
compress Int 是否开启数据压缩(标准压缩模式)。例：1：开启 2：关闭     
非必传，如果不传递该参数，默认值为 2（返回纯文本 JSON）。

强烈推荐配置：
占星排盘数据包含大量星体、宫位、相位交角等节点，报文较大。
为大幅降低网络传输延迟，节省您的服务器外网带宽，强烈建议在生产环境传入 compress=1。

接口响应机制与解压说明（完全符合 HTTP 标准）：
当 compress=1 时，本接口会在底层进行 GZIP 压缩，并下发标准的 Content-Encoding: gzip 响应头。
对接端是否需要编写解压代码，取决于您所使用的 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,

    'target_year' => '2025',
    'target_month' => '11',
    'target_day' => '8',
    'target_hours' => '12',
    'target_minute' => '20',

    'longitude' => '116.407396',
    'latitude' => '39.904200',
    'timezone' => 'Asia/Shanghai',
    'house_system' => 'P',
    'additional_objects' => '1,2,7', // 开启宿命点、凯龙星、福点
    'orb_model' => '5',
    'compress' => '1' // 开启数据压缩以提高传输速度

返回参数

字段 类型 描述
errcode String 请求状态码 0成功 其它为失败
errmsg String 状态码说明
notice String 声明
data Json 数据信息

成功返回示例

为了方便开发者快速构建数据模型，以下是完整的核心 JSON 结构说明（已折叠重复的数组项）：

{
  "errcode": 0, // 状态码：0代表成功
  "errmsg": "请求成功",
  "notice": "本次测算结果仅供娱乐使用...",
  "data": {
    "base_info": { // 基础排盘参数
      "chart_type": "transit", // 星盘类型：transit (行运盘固定值)
      "natal_info": { // 本命出生信息 (B盘底盘)
        "gender": "male", //性别(male男/female女)
        "birthday": "2026-3-28 9:32:00",// 出生时间
        "longitude": 116.4224,// 出生十进制经度
        "latitude": 39.9348,// 出生十进制纬度
        "timezone": "Asia/Shanghai",// IANA时区
        "house_system": "P",// 宫位制代码(P=普拉西度制)
        "numerology": "5"  // 核心命理：西方生命密码/生命灵数(1-9)
      },
      "target_info": { // 推运目标时间/地点信息 (A盘行运)
        "gender": "male",   // 占位字段，推运计算不使用，保持结构一致
        "birthday": "2026-3-28 9:32:00",// 推运目标时刻
        "longitude": 116.42240097766,// 推运目标地点经度（默认同本命）
        "latitude": 39.934827272396, // 推运目标地点纬度（默认同本命）
        "timezone": "Asia\/Shanghai", // 推运目标时区（默认同本命）
        "house_system": "P", // 宫位制代码（默认同本命）
        "numerology": "5"    // 占位字段，推运计算不使用
      }
    },
    "detail_info": {
      "chart_data": { // 核心测算结果集合
        // ================= 1. 推运+本命盘基础数据 (A方为行运星象，B方为本命底盘) =================
        "person_a_natal": { ... },   // 行运盘除了 patternData 之外的完整数据，包含 housesData/signData/planetData/attributeData，结构同本命盘接口，可参考本命盘数据，此处省略以节省篇幅。
        "person_b_natal": { ... },   // 本命盘除了 patternData 之外的完整数据，结构同上。

        // ================= 2. 行运对本命的深度触发数据 (复用双盘比对结构) =================
        "synastry": {
          "meta": { // 比对数据复杂度元统计
            "object_count_a": 14,       // 行运启用的星体与虚点总数
            "object_count_b": 14,       // 本命启用的星体与虚点总数
            "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": { // 行运星体及状态 (Transit)
                "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": { // 被触发的本命星体及状态
                "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": "合相", //相位中文名，枚举值请参阅 [数据集合-西方占星]
                "aspect_chinese_traditional": "合相",//相位繁体中文名，枚举值请参阅 [数据集合-西方占星]
                "orb": 1.4722332,             // 容许度误差 (实际角度差与基准角度的偏差度数)
                "deg": 0, //容许度误差转化为度结构
                "min": 0, //容许度误差转化为分结构
                "sec": 0, //容许度误差转化为秒结构
                "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": [ // 行运星体过境本命宫位数据(外圈 Transit 影响内圈 Natal )
            {
              "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, // 被触发的本命具体宫位 ID，枚举：1～12
              "house_name": "福德宫", // 本命宫位含义
              "relative_deg": 10.2035627, // 在该本命宫位内的相对偏移度数
              "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低)
            }
            // ... 行运其他星体的过宫数据省略 ...
          ],

          "house_overlay_b_in_a": [], //【重要】本命星体落入行运宫位在占星学中缺乏实际参考意义，此处固定为空数组以保持接口结构统一。

          "angle_contacts": [ // 四轴与敏感点的触发（行运星触发本命轴点，或行运轴点触发本命星）
            {
              "type": "A_angle_to_B_planet", //触发方向标识，枚举值："A_angle_to_B_planet" 触发方向标识："A_angle_to_B_planet" (行运四轴扫过本命星)，"B_angle_to_A_planet" (行运星体触碰本命四轴)
              "angle_english": "Ascendant", //四轴/敏感点信息英文名，枚举值：Ascendant//Midheaven/ImumCoeli/Descendant/Vertex
              "angle_chinese": "上升", //四轴/敏感点信息中文名，枚举值：上升/天顶/天底/下降/宿命点
              "angle_chinese_traditional": "上升點", //四轴/敏感点信息繁体中文名，枚举值：上升點/天頂/天底/下降點/宿命點
              "planet_english": "Sun", //星体英文名称，枚举值请参阅 [数据集合-西方占星]
              "planet_chinese": "太阳", //星体中文名称，枚举值请参阅 [数据集合-西方占星]
              "planet_chinese_traditional": "太陽", //星体繁体中文名称，枚举值请参阅 [数据集合-西方占星]
              "allow": 90, // 发生相位的基准角度 (0/30/60/90/120/150/180)
              "aspect_english": "Square", //相位英文名，枚举值请参阅 [数据集合-西方占星]
              "aspect_chinese": "四分相", //相位中文名，枚举值请参阅 [数据集合-西方占星]
              "aspect_chinese_traditional": "四分相", //相位繁体中文名，枚举值请参阅 [数据集合-西方占星]
              "orb": 5.7248766, // 容许度误差 (实际角度差与基准角度的偏差度数)
              "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，可参阅 [数据集合-西方占星]
            }
            // ... 其它相位互动数据省略 ...
          ],
        }
      },

      // ================= 专业文案与高精渲染图 =================
      "chart_description": { //多维度结构化解析文案，内容根据请求参数 lang 自动切换 zh-cn/zh-tw/en-us）
        "summary": [ // 【数组】推运盘整体基调与核心议题
          {
            "target": "推运概述",
            "description": "当前行运天象对你产生如下影响..."
          }
        ],
        "houses": [ // 【数组】推运盘宫头落入星座的解析
          {
            "target": "行运太阳落入11宫",
            "description": "这段时间你的社交活动将变得频繁..."
          }
        ],
        "planets": [], //【重要】行运盘此处文案无意义，固定为空数组
        "aspects": [  // 【数组】行运盘重要相位的深度互动解析
          {
            "target": "行运太阳 合相 本命海王星",
            "description": "直觉力提升，适合进行艺术创作..."
          }
        ],
        "angles": [ // 【数组】行运盘四轴点(Asc/Mc/Ic/Dsc)相位解析
          {
            "target": "行运上升点过运",
            "description": "自我意识觉醒的关键时期..."
          }
        ]
      },

      // 推运盘高精度星盘矢量图源码(详见前端SVG图片开发文档)
      "chart_svg": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<svg width=\"720\" height=\"720\" ...>...</svg>"
    }
  }
}

失败返回示例

{
  "errcode": -1,
  "errmsg": "经度必须在 -180 ~ 180 之间"
}
汇总