星盘API文档 - 占星图表API接口文档

欢迎使用AI星盘专业占星图表API！我们提供完整的星盘API服务，包括本命盘API、行运盘API、合盘API、推运盘API等。支持单盘、双盘和三盘的各种组合分析。所有占星API都返回结构化的JSON数据和可选的SVG图表，确保您能够轻松集成到任何应用程序中。

请求网址，chart.12sign.top

API概览

我们的API分为三个主要类别，每个类别都有其特定的用途和功能：

单盘API接口

生成单个占星图表API，包括本命盘API、行运盘API、推运盘API等各种类型。适用于个人占星分析和基础图表生成。

本命盘行运盘次限推运太阳弧推运

双盘API接口

比较两个图表的相互关系API，如本命盘与行运盘的对比、合盘API分析等。适用于关系分析和时间预测。

本命vs行运合盘本命vs次限

三盘API接口

同时分析三个图表的复合关系API，提供更深层次的占星洞察。适用于复杂的占星分析和专业咨询。

本命+次限+行运本命+太阳弧+行运本命+组合盘+行运

快速开始

所有API端点都使用HTTP POST方法，接受JSON格式的请求数据，并返回结构化的响应。

基本请求格式

POST /api/chart
Content-Type: application/json

{
  "chart_type": "natal",
  "data": {
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "second": 0,
    "latitude": 39.9042,
    "longitude": 116.4074,
    "timezone": 8
  },
  "house_system": "placidus",
  "include_svg": true
}
                

响应格式

{
  "success": true,
  "data": {
    "planets": [...],
    "houses": [...],
    "aspects": [...]
  },
  "svg_content": "..."
}
                

认证

目前API处于开放测试阶段，无需认证即可使用。在生产环境中，我们将提供API密钥认证机制。

速率限制

为确保服务稳定性，我们对API请求实施以下限制：

每分钟最多60次请求
每小时最多1000次请求
每天最多10000次请求

错误处理

当API请求失败时，您将收到包含以下字段的JSON响应：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误的详细描述",
    "status": HTTP状态码
  }
}
                

常见HTTP状态码

状态码	描述	处理建议
200 OK	请求成功	正常处理响应数据
400 Bad Request	请求参数无效或缺失	检查请求参数是否正确
429 Too Many Requests	超出了API请求速率限制	减少请求频率
500 Internal Server Error	服务器内部错误	联系客服支持

常见错误代码

错误代码	描述	解决方案
INVALID_CHART_TYPE	提供的图表类型无效	检查chart_type参数是否为支持的值
INVALID_DATE	提供的日期无效	确保日期参数格式正确且有效
INVALID_LOCATION	提供的地理位置无效	检查纬度和经度值是否在有效范围内
RATE_LIMIT_EXCEEDED	超出API请求速率限制	减少请求频率

支持的星体和特殊点

本项目基于 Swiss Ephemeris (Swisseph) 常量定义星体，主要分为五大类别：

I. 主要行星 (MAJOR PLANETS)

这些是占星学中用于构建核心命盘的传统和现代行星。

中文名称	英文名称 (Constant)
太阳	SUN
月亮	MOON
水星	MERCURY
金星	VENUS
火星	MARS
木星	JUPITER
土星	SATURN
天王星	URANUS
海王星	NEPTUNE
冥王星	PLUTO

II. 交点与特殊点 (NODES AND POINTS)

用于计算轨道交叉点和月亮远点（莉莉丝）。

中文名称	英文名称 (Constant)
平均北交点	MEAN_NODE
真实北交点	TRUE_NODE
平均莉莉丝	MEAN_LILITH
真实莉莉丝	OSCU_LILITH
插值莉莉丝	INTP_LILITH

III. 小行星与半人马群 (ASTEROIDS AND CENTAURS)

支持占星学中常用的四大小行星和两个重要的半人马星体。

中文名称	英文名称 (Constant)
凯龙星	CHIRON
福勒斯	PHOLUS
谷神星	CERES
智神星	PALLAS
婚神星	JUNO
灶神星	VESTA

IV. 汉堡学派/乌兰学派虚拟行星 (HAMBURG PLANETS)

支持由汉堡学派（Uranian Astrology）使用的八个虚拟超海王星体 (TNOs)。

中文名称	英文名称 (Constant)
丘比特	CUPIDO
哈迪斯	HADES
宙斯	ZEUS
克洛诺斯	KRONOS
阿波罗	APOLLON
阿德墨托斯	ADMETOS
武尔肯	VULKANUS
波塞冬	POSEIDON

V. 恒星 (FIXED STARS)

本项目支持计算一系列重要的恒星的黄道坐标，以便进行合相分析。

恒星名称 (Name)	英文名称 (Constant)
ALDEBARAN (毕宿五)	ALDEBARAN
ANTARES (心宿二)	ANTARES
REGULUS (轩辕十四)	REGULUS
SPICA (角宿一)	SPICA
SIRIUS (天狼星)	SIRIUS
BETELGEUSE (参宿四)	BETELGEUSE
POLLUX (北河三)	POLLUX
FOMALHAUT (北落师门)	FOMALHAUT
ALGOL (大陵五)	ALGOL

示例用例

以下是一些常见的API使用场景：

生成本命盘

生成用户的本命星盘，显示行星位置和相位关系。

POST /api/chart
Content-Type: application/json

{
  "chart_type": "natal",
  "data": {
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "second": 0,
    "latitude": 39.9042,
    "longitude": 116.4074,
    "timezone": 8
  },
  "house_system": "placidus",
  "include_svg": true
}
                    

合盘分析

比较两个人的星盘，分析他们之间的相位关系。

POST /api/chart
Content-Type: application/json

{
  "chart_type": "synastry",
  "data": {
    "person1": {
      "year": 1990,
      "month": 5,
      "day": 15,
      "hour": 14,
      "minute": 30,
      "second": 0,
      "latitude": 39.9042,
      "longitude": 116.4074,
      "timezone": 8
    },
    "person2": {
      "year": 1992,
      "month": 8,
      "day": 20,
      "hour": 10,
      "minute": 15,
      "second": 0,
      "latitude": 31.2304,
      "longitude": 121.4737,
      "timezone": 8
    }
  },
  "include_svg": true
}
                    

技术支持

如果您在使用API过程中遇到任何问题，请通过以下方式联系我们：

联系微信：13971065169
技术文档：查看具体接口文档获取详细信息
示例代码：每个接口文档都包含完整的使用示例