西方占星-月返照

文档说明

        西占月返照是行运月亮精准回归你本命月亮度数时，以你当前所在地起盘的月度运势星盘，周期约27–28天，可看作当月的 “迷你本命盘”，核心看月亮落宫、上升星座、四轴与关键相位，精准呈现这一月的情绪基调、内心需求、生活重心、人际与安全感状态，是解读月度短期运势与心理波动的核心工具。

  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/lunarreturn

请求头

字段 类型 描述
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
点击 此处 查看完整时区列表。
target_longitude Float 返照地十进制经度 例：-77.036871    
非必传，默认出生地经度。
经度范围：-180～180，浮点数，小数点后最多6位。
target_latitude Float 返照地十进制纬度 例：38.907192    
非必传，默认出生地纬度。
纬度范围：-90～90，浮点数，小数点后最多6位。
target_timezone String 返照地时区（IANA 格式），例：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 容许度模型，例：2
非必传，默认 2
支持参数：1:严格(偏小), 2:标准(默认), 3:宽泛(偏大), 4:自定义
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' => '2',
    'compress' => '1' // 开启数据压缩以提高传输速度

返回参数

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

成功返回示例

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

{
  "errcode": 0, // 状态码：0代表成功
  "errmsg": "请求成功",
  "notice": "本次测算结果仅供娱乐使用...",
  "data": {
    "base_info": { // 基础排盘参数
      "chart_type": "lunar_return", // 星盘类型：lunar_return (月返照固定值)
      "natal_info": { // 本命出生信息
        "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": { // 月返目标时间/地点信息
        "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. 宫位与飞星数据 =================
        "housesData": [
          {
            "house_id": 1, // 宫位编号(1-12)
            "house_life": "命宫", // 宫位中文含义，枚举值请参阅 [数据集合-西方占星]
            "longitude": 298.7166572, // 宫首绝对黄道经度(0-360)
            "sign": { // 宫首落入星座信息
              "sign_id": 9, // 星座系统编号(0-11)
              "sign_english": "Capricorn", //星座英文名称，枚举值请参阅 [数据集合-西方占星]
              "sign_chinese": "摩羯",       //星座简体中文，枚举值请参阅 [数据集合-西方占星]
              "sign_chinese_traditional": "摩羯", //星座繁体中文，枚举值请参阅 [数据集合-西方占星]
              "sign_font": "J", // 星座图标映射码，枚举值请参阅 [数据集合-西方占星]
              "deg": 28, "min": 43, "sec": 0 // 宫首在该星座内的精准度、分、秒
            },
            "main_planet": [ // 守护星/宫主星信息
              {
                "code_name": "6",   //星体的唯一标识符，枚举值请参阅 [数据集合-西方占星]
                "planet_english": "Saturn", //星体英文名称，枚举值请参阅 [数据集合-西方占星]
                "planet_chinese": "土星",    //星体中文名称，枚举值请参阅 [数据集合-西方占星]
                "planet_chinese_traditional": "土星",//星体繁体中文名称，枚举值请参阅 [数据集合-西方占星]
                "planet_font": "Sa" //星体图标映射码，枚举值请参阅 [数据集合-西方占星]
              }
            ],
            "planet_array": [ // 宫内落入的所有星体列表
              {
                "object_type": "angle", //天体类型，(planet行星/asteroid小行星/arabic_part阿拉伯点/angle四轴/lunar虚点)，枚举值请参阅 [数据集合-西方占星]
                "code_name": "ASC",     //星体的唯一标识符，枚举值请参阅 [数据集合-西方占星]
                "planet_english": "Ascendant",//星体英文名称，枚举值请参阅 [数据集合-西方占星]
                "planet_chinese": "上升", //星体中文名称，枚举值请参阅 [数据集合-西方占星]
                "planet_chinese_traditional": "上升點",//星体繁体中文名称，枚举值请参阅 [数据集合-西方占星]
                "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",
            "longitude": 225.9841641, // 绝对经度
            "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)，即实际交角与基准相位的偏差
              }
            ]
          }
          // ... 其他星体数据省略 ...
        ],

        // ================= 4. 全局统计与高阶格局 =================
        "attributeData": { // 星盘元素与阴阳统计(按属性分组，前端可直接遍历画雷达图)
          "fire": [ /* 火相元素星体列表 */ ],
          "earth": [ /* 土相元素星体列表 */ ],
          "air": [ /* 风相元素星体列表 */ ],
          "water": [ /* 水相元素星体列表 */ ],
          "cardinal": [ /* 本位星座星体列表 */ ],
          "fixed": [ /* 固定星座星体列表 */ ],
          "mutable": [ /* 变动星座星体列表 */ ],
          "yang": [ /* 阳性星体列表 */ ],
          "yin": [ /* 阴性星体列表 */ ]
        },
        "patternData": [ // 自动识别的高阶特殊格局
          {
            "pattern_id": "yod", //格局标识ID ，枚举值请参阅 [数据集合-西方占星]
            "pattern_en": "Yod", //格局英文名 ，枚举值请参阅 [数据集合-西方占星]
            "pattern_zh": "上帝之指", //格局中文名 ，枚举值请参阅 [数据集合-西方占星]
            "pattern_zht": "上帝之指",//格局繁体中文名 ，枚举值请参阅 [数据集合-西方占星]
            "objects": [ /* 构成该格局的具体星体列表 */ ]
          }
         // ... 其他格局省略 ...
        ]
      },

      // ================= 专业文案与高精渲染图 =================
      "chart_description": {  // 多维度结构化解析文案（内容根据请求参数 lang 自动切换 zh-cn/zh-tw/en-us）
         "summary": [ // 【数组】月返整体基调与核心议题
          {
            "target": "运势基调：月亮落入第4宫",
            "description": "月返月亮落四宫，本月核心消耗聚焦在家庭与内心安全感层面..."
          }
        ],
         "houses": [ // 【数组】月返宫头落入星座的解析
          {
            "target": "返照第1宫落入狮子座",
            "description": "月返第一宫被强力激活：今年「自我重塑」是你的核心命题。个人形象、行动力与存在..."
          },
          {
            "target": "返照第8宫落入双鱼座",
            "description": "月返第八宫被强力激活：今年「深度与蜕变」的能量极具冲击力。共享资源..."
          }
          // ... 剩余宫位解析省略 ...
        ],
        "planets": { // 【对象】返照的深度解析
          "sign": [ // 行星落入星座的解析（行为模式/性格特质）
            {
              "target": "返照月亮落入狮子座",
              "description": "月返月亮落入狮子座，今年你的情绪需要「被看见与被赞美」，安全感源于..."
            }
            // ... 其他行星落座解析省略 ...
          ],
          "house": [ // 行星落入宫位的解析
            {
              "target": "返照月亮落入狮子座",
              "description": "月返月亮落入狮子座，本月你的情绪张扬且渴望被..."
            },
            {
              "target": "返照太阳落入第11宫",
              "description": "月返太阳落第十一宫，本月你的核心精力聚焦在社交圈..."
            }
            // ... 其他行星落宫解析省略 ...
          ]
        },
        "angles": [ // 【数组】四轴点（Asc/Mc/Ic/Dsc）的落点解析
          {
            "target": "返照上升落入金牛座",
            "description": "月返上升金牛座，本月你的对外态度偏向稳重与务实、..."
          }
          // ... 其他轴点解析省略 ...
        ],
        "aspects": [  // 【数组】月返照盘重要相位的深度互动解析
          {
            "target": "返照月亮 对分相 冥王星",
            "description": "月返月亮冲冥王星，本月你的情绪在..."
          }
          // ... 其他相位解析省略 ...
        ],
      },

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

失败返回示例

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