Tropical 与 Sidereal 占星：开发者的 API 支持指南

如果你在做占星 app，迟早会遇到这个问题：

Why does one chart say Aries, while another chart says Pisces for the same person?

多数情况下，计算没有坏。两张星盘使用了不同 zodiac systems。

Tropical astrology 和 sidereal astrology 都使用同样的十二星座名称：Aries、Taurus、Gemini、Cancer 等。区别在于 zodiac 从哪里开始。

Tropical 从三月春分点开始。Sidereal 使用基于星体的参考点。这个差异会改变 Sun、Moon、Ascendant、planets 和 houses 显示的 sign。

对开发者来说，最重要的是不要隐藏这个设置。如果 app 能返回 tropical 或 sidereal chart，用户必须知道自己看到的是哪一个。

简短版本

Tropical astrology 是多数现代 Western astrology apps 的默认值。

Sidereal astrology 是多数 Vedic、Jyotish 和 kundli apps 的默认值。

可以这样开始：

If you are building	Usually use
Western birth chart calculator	Tropical
Western daily horoscope app	Tropical
Western synastry or compatibility app	Tropical
Vedic chart or kundli app	Sidereal
Nakshatra, dasha, Panchang, or gochar features	Sidereal
App that supports both Western and Vedic astrology	Let the user choose

这不是谁对谁错。两个系统服务不同传统。

Tropical astrology 是什么

Tropical astrology 绑定季节。

在 tropical astrology 中，Aries 从三月春分开始。春分是太阳穿过天赤道、昼夜大致相等的时间点。

从那里开始，zodiac 被分成十二个 30 度 signs：

Aries      0 to 30
Taurus    30 to 60
Gemini    60 to 90
Cancer    90 to 120
...
Pisces    330 to 360

所以 tropical Aries 不是在说真实天空中的 Aries constellation。它是季节 zodiac 的第一个 sign。

多数现代 Western astrology 都这样使用。如果美国或欧洲用户搜索 "my birth chart"、"my rising sign"、"my moon sign"，通常期待 tropical Western chart，除非他们明确提到 sidereal、Vedic、Jyotish 或 Lahiri。

所以如果你做 Western astrology API，tropical 通常应是默认值。

Tropical astrology 的使用场景

Tropical 常见于：

Western natal charts
Sun sign horoscopes
Psychological astrology
Modern relationship compatibility
Western transit readings
Solar returns 和其他 Western timing techniques

语言通常像这样：

Your Sun is in Leo.
Your Moon is in Scorpio.
Your Ascendant is Virgo.
Venus is transiting your seventh house.

星盘仍然可能包含 houses、aspects、dignities、transits 等技术细节，但底层 zodiac 通常是 tropical。

Sidereal astrology 是什么

Sidereal astrology 使用基于星体的 zodiac。

核心点是 tropical 和 sidereal zodiac 已经不再对齐。地球朝向会长期缓慢移动，这叫 precession。

由于这个偏移，同一颗行星的 tropical position 和 sidereal position 常会落在不同 sign。

现代粗略例子：

Tropical Sun: 5 Aries
Sidereal Sun: about 11 Pisces

太阳没有移动。出生数据没有变。只是参考 zodiac 不同。

Sidereal astrology 的使用场景

Sidereal 最常见于 Vedic astrology，也叫 Jyotish。

如果 app 包含这些功能，多半属于 sidereal：

Kundli charts
Rashi charts
Nakshatras
Dashas
Panchang
Gochar transits
Vedic compatibility
Muhurat or electional timing
Lahiri ayanamsha

也有 Western sidereal astrologers，但受众更具体。多数产品里，实际分界是：

Western astrology page -> tropical by default
Vedic astrology page -> sidereal by default

如果一个产品混合两种传统，请把选择显示出来。

Ayanamsha 是什么？

对初学开发者来说，ayanamsha 可以理解为 tropical zodiac 和某个 sidereal zodiac 之间的 offset。

简化理解：

sidereal position = tropical position - ayanamsha

生产环境中，不要自己硬算，交给占星计算引擎。精确 offset 取决于日期和所选 ayanamsha 系统。

常见选项：

Ayanamsha	Common use
`lahiri`	Common default for Vedic and Jyotish charts.
`raman`	Used by some Vedic astrologers.
`kp`	Used in KP astrology.
`fagan_bradley`	Often used in Western sidereal astrology.
`yukteshwar`	Used by some sidereal practitioners.

"sidereal" 这个词本身不一定够。严肃的 astrology API 应该说明使用了哪个 ayanamsha。

一个简单例子

假设用户出生时 Sun 在 tropical Aries 前几度。

Western birth chart 页面可能显示：

Sun in Aries
Zodiac: Tropical

Vedic chart 页面使用 Lahiri sidereal 可能显示：

Sun in Pisces
Zodiac: Sidereal
Ayanamsha: Lahiri

两者可以来自同一组出生日期、时间和地点。

问题在于 app 只显示：

Sun in Pisces

用户没有上下文。如果他期待的是 Western chart，就会以为你算错了。

API 应该支持什么

zodiac system 必须是显式设置。

Tropical chart 请求可以这样：

{
  "zodiac_type": "tropical"
}

Sidereal chart 请求可以这样：

{
  "zodiac_type": "sidereal",
  "sidereal_ayanamsa": "lahiri"
}

响应也应该回显这些设置，不要让开发者猜。

有用的响应 metadata：

{
  "meta": {
    "zodiac_type": "sidereal",
    "sidereal_ayanamsa": "lahiri",
    "house_system": "whole_sign",
    "time_known": true
  }
}

这几个字段能减少大量后续混乱。

FreeAstroAPI 示例

Western tropical natal chart：

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Alex",
    "year": 1994,
    "month": 8,
    "day": 11,
    "time_known": true,
    "hour": 6,
    "minute": 42,
    "city": "Los Angeles",
    "lat": 34.0522,
    "lng": -118.2437,
    "tz_str": "AUTO",
    "house_system": "placidus",
    "zodiac_type": "tropical"
  }'

Lahiri ayanamsha 的 sidereal chart：

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Alex",
    "year": 1994,
    "month": 8,
    "day": 11,
    "time_known": true,
    "hour": 6,
    "minute": 42,
    "city": "Los Angeles",
    "lat": 34.0522,
    "lng": -118.2437,
    "tz_str": "AUTO",
    "house_system": "whole_sign",
    "zodiac_type": "sidereal",
    "sidereal_ayanamsa": "lahiri"
  }'

如果你渲染 SVG 或 PNG chart wheel，图像必须和数据使用同一 zodiac setting。Sidereal JSON 配 tropical chart image 会立刻让用户困惑。

参考 Western Natal、Western Chart SVG 和 Vedic Chart。

如何选择默认值

页面写的是 "Western astrology"，默认 tropical。

页面写的是 "Vedic astrology"、"Jyotish"、"kundli"、"nakshatra" 或 "dasha"，默认 sidereal。多数 Vedic app 以 lahiri 作为安全起点。

通用平台应提供清楚选项：

Zodiac system: Tropical | Sidereal

如果选择 Sidereal，再显示：

Ayanamsha: Lahiri

UI 里不要放太长天文解释。用户需要知道 chart 属于哪个传统。

有帮助的 UI 文案

坏 label：

Mode: Standard

更好：

Zodiac system: Tropical

带短提示：

Zodiac system: Tropical
Used by most modern Western astrology charts.

Sidereal：

Zodiac system: Sidereal
Used by Vedic/Jyotish charts and some Western sidereal charts.

缓存不要漏掉 zodiac type

不要只用下面这些做 cache key：

birth date + birth time + city

Tropical 和 sidereal chart 可以使用同一组出生数据，但返回不同 signs。

cache key 应包含：

birth_datetime_utc
+ latitude
+ longitude
+ timezone
+ house_system
+ zodiac_type
+ sidereal_ayanamsa
+ engine_version

这样不会在 sidereal 页面展示 tropical 数据，也不会反过来。

AI 占星 app 也需要同样上下文

如果用 LLM 写解释，不要让模型猜 zodiac system。

把计算设置和 chart 一起发送：

{
  "instruction": "Interpret only the supplied chart data. Do not recalculate signs.",
  "calculation_settings": {
    "zodiac_type": "sidereal",
    "sidereal_ayanamsa": "lahiri",
    "house_system": "whole_sign"
  },
  "placements": {
    "sun": "Pisces 11",
    "moon": "Cancer 28",
    "ascendant": "Leo 3"
  }
}

这很重要，因为网上大多数占星文本是 tropical Western astrology。如果 chart 是 Vedic sidereal，prompt 必须明确说明。

常见错误

错误 1：把 sidereal 当成纯显示选项

Sidereal 不只是 UI label。它改变 signs 和解释所用的 zodiac longitudes。

错误 2：说 sidereal 却隐藏 ayanamsha

严肃用户会关心 ayanamsha。支持 sidereal chart 时，请在响应中显示，必要时也在 UI 显示。

错误 3：用 tropical 文本解释 sidereal 数据

Western tropical 的报告文本不一定适合 Vedic sidereal placements。名称看起来一样，传统和解释方式可能不同。

错误 4：比较 signs 时不检查 zodiac system

数据库里 "Moon in Cancer" 也要知道是 tropical Cancer 还是 sidereal Cancer。

错误 5：不解释 signs 为什么变了

如果提供 toggle，用户切换后会看到 signs 改变。旁边放一句短解释，可以减少支持问题。

FAQ

Sidereal 比 tropical 更准确吗？

不能这样简单比较。它们是不同传统使用的不同 zodiac systems。产品应该计算用户选择的系统，并清楚标注。

为什么我的 Sun sign 变了？

可能是 chart 从 tropical 切到 sidereal，或反过来。出生数据没变，zodiac system 变了。

Vedic astrology 总是 sidereal 吗？

多数 Vedic 和 Jyotish apps 使用 sidereal，常见默认是 Lahiri ayanamsha。做 nakshatras、dashas、Panchang 或 kundli charts 时，sidereal 应作为默认。

Western astrology 总是 tropical 吗？

多数现代 Western astrology 是 tropical，但 Western sidereal astrology 也存在。普通 Western birth chart calculator 预期默认是 tropical。

应该让用户选择吗？

如果产品同时服务 Western 和 Vedic 用户，是的。纯 Western chart calculator 可以默认 tropical 并说明。纯 Vedic 产品则默认 sidereal 并显示 ayanamsha。

最后记住

Tropical vs sidereal 不是小技术细节。它会改变用户看到的 signs。

清楚的占星 app 应该：

Western features 多数用 tropical
Vedic 和 Jyotish features 用 sidereal
在 UI 显示 zodiac system
在请求和响应中包含 zodiac_type
使用 sidereal chart 时包含 sidereal_ayanamsa
保持 chart images、reports、caches 和 AI prompts 使用同一设置

这样用户看到的 chart 会符合预期传统，开发者也有足够 metadata 构建可靠产品。