TradAstro 开发者 API

面向二次开发的古典占星计算与主题解读接口。注册账号后即可在 开放平台 创建 API Key，按加权点数计费。

网站前端使用的 /api/*/compute 路由仅供产品 UI；**对外集成请只用 /api/v1/***。

目录

快速开始

curl -s -X POST https://tradastro.com/api/v1/natal \
  -H "Authorization: Bearer ta_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "house_system": "regiomontanus",
    "terms": "egyptian"
  }'

成功时返回 JSON，例如 { "snapshot": { ... } }，并带有月度配额响应头（见下文）。

鉴权与密钥

请求头（二选一）

Authorization: Bearer ta_live_...

或

X-Api-Key: ta_live_...

若两者同时存在，以 X-Api-Key 为准。密钥前缀固定为 ta_live_。

密钥生命周期

配额与套餐绑定在账号上，不是绑定在单个 Key 上。同一账号下多个 Key 共用当月点数。

配额、权重与限流

月度点数（账号级）

接口权重

每分钟限流（Key 级）

响应头（仅成功 2xx）

下列头表示当月账号配额（不是每分钟限流）：

失败响应（4xx/5xx）通常不含上述头。暂无 Retry-After。

套餐与计费

公共约定

公共数据结构

Person（人物出生信息）

用于顶层人物字段，或嵌套为 natal / chart_a / chart_b：

{
  "datetime": "1990-05-15T14:30:00",
  "timezone": "Asia/Shanghai",
  "latitude": 31.23,
  "longitude": 121.47,
  "label": "甲",
  "place_name": "上海"
}

aspect_settings（相位设置，可选）

多数计算类接口支持：

省略时使用引擎默认设置。

接口参考

除特别说明外，均为 POST，需鉴权，成功体为 JSON。

下列 JSON 为缩略样例：数组通常只保留 1～2 项，数值与文案为示意；完整字段以实际响应为准。引擎可能随版本增加可选字段。

POST /natal — 本命盘 · 权重 1

计算古典本命：行星、宫位、相位、尊贵、阿拉伯点、法达、小限等。

请求体：Person 字段 + 可选 house_system、terms、aspect_settings。

curl -s -X POST https://tradastro.com/api/v1/natal \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "house_system": "regiomontanus",
    "terms": "egyptian"
  }'

响应：{ "snapshot": NatalSnapshot }

{
  "snapshot": {
    "meta": {},
    "label": "Natal",
    "birth": {
      "datetime": "1990-05-15T14:30:00",
      "timezone": "Asia/Shanghai"
    },
    "settings": {
      "house_system": "regiomontanus",
      "aspect_matrix_order": ["sun", "moon", "mercury"]
    },
    "angles": { "asc": 182.45, "mc": 97.12 },
    "chart_ruler": { "planet": "venus" },
    "houses": [
      { "house": 1, "longitude": 182.45, "sign": "libra" }
    ],
    "planets": [
      {
        "id": "sun",
        "symbol": "☉",
        "longitude": 54.32,
        "sign": "taurus",
        "sign_symbol": "♉",
        "degree": 24,
        "minute": 19,
        "position": "24°19′ Taurus",
        "house": 8,
        "house_whole_sign": 8,
        "houses_ruled": [11],
        "houses_exalted": [],
        "speed": 0.96,
        "retrograde": false,
        "dignities": { "domicile": false, "exaltation": false },
        "dignity_score": null,
        "sect": "day",
        "orientality": null,
        "speed_class": "average",
        "solar_phase": null
      }
    ],
    "aspects": [
      {
        "body_a": "sun",
        "body_b": "moon",
        "type": "trine",
        "angle": 120,
        "orb": 1.42,
        "orb_deg": 1,
        "orb_min": 25,
        "orb_display": "1°25′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "lots": [{ "id": "fortune", "longitude": 210.1, "sign": "scorpio", "house": 2 }],
    "features": [],
    "firdaria": {
      "sect": "day",
      "current": { "major_lord": "venus", "sub_lord": "mercury" }
    },
    "profections": {
      "method": "annual",
      "current": { "house": 1, "lord": "venus", "sign": "libra" }
    }
  }
}

可选字段示例：house_scores、core_life_themes、personality_profile、行星 condition_summary / power 等（视引擎版本而定）。

POST /synastry — 比较盘 · 权重 2

双人比较盘（跨盘相位与关系向结果）。

curl -s -X POST https://tradastro.com/api/v1/synastry \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chart_a": {
      "datetime": "1990-05-15T14:30:00",
      "timezone": "Asia/Shanghai",
      "latitude": 31.23,
      "longitude": 121.47
    },
    "chart_b": {
      "datetime": "1992-08-20T09:00:00",
      "timezone": "Asia/Shanghai",
      "latitude": 39.90,
      "longitude": 116.40
    },
    "inner": "a"
  }'

响应样例：

{
  "snapshot": {
    "meta": {},
    "inner": "a",
    "chart_a": {
      "label": "Person A",
      "angles": { "asc": 182.45, "mc": 97.12 },
      "planets": [{ "id": "venus", "sign": "gemini", "house": 9 }],
      "houses": []
    },
    "chart_b": {
      "label": "Person B",
      "angles": { "asc": 24.1, "mc": 278.6 },
      "planets": [{ "id": "mars", "sign": "aries", "house": 1 }],
      "houses": []
    },
    "cross_aspects": [
      {
        "inner_body": "venus",
        "outer_body": "mars",
        "type": "trine",
        "angle": 120,
        "orb": 1.2,
        "orb_deg": 1,
        "orb_min": 12,
        "orb_display": "1°12′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "relationship_scoring": {
      "version": "current",
      "symmetric": {
        "attraction": { "score": 78, "label": "明显吸引" },
        "stability": { "score": 64, "label": "较稳定" },
        "tension": { "score": 38, "label": "张力适中" },
        "compatibility": { "score": 72, "label": "较为契合" }
      },
      "directional": {
        "a_to_b": { "score": 70, "label": "投入明显" },
        "b_to_a": { "score": 66, "label": "回应稳定" }
      },
      "summary": {
        "relationship_type": {
          "id": "balanced_attraction",
          "label": "吸引与稳定并存",
          "reasons": ["互动自然，彼此容易形成持续关注。"]
        },
        "highlights": ["情感表达较容易被对方接住。"],
        "risks": ["压力下可能出现节奏差异。"],
        "suggestions": ["保留直接沟通和独处空间。"]
      }
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "inner_label": "Person A",
      "outer_label": "Person B",
      "include_outer_planets": true
    }
  }
}

relationship_scoring 可能缺省；公开响应呈现分数与定性标签，不保证含内部计分明细字段。

POST /composite — 组合盘 · 权重 2

Davison 组合盘及结构向结果。请求体与比较盘相同，但不支持 inner。

响应样例：

{
  "snapshot": {
    "meta": {},
    "chart": {
      "label": "Davison Composite",
      "angles": { "asc": 113.2, "mc": 15.8 },
      "planets": [{ "id": "sun", "sign": "cancer", "house": 7 }],
      "aspects": [],
      "houses": [],
      "lots": [],
      "features": []
    },
    "chart_a": { "label": "Person A", "angles": { "asc": 182.45, "mc": 97.12 }, "planets": [] },
    "chart_b": { "label": "Person B", "angles": { "asc": 24.1, "mc": 278.6 }, "planets": [] },
    "composite_scoring": {
      "version": "current",
      "indices": {
        "structure": { "score": 74, "label": "结构稳固" },
        "attraction": { "score": 80, "label": "吸引明显" },
        "stability": { "score": 68, "label": "较稳定" },
        "conflict": { "score": 35, "label": "冲突可控" },
        "total": { "score": 73, "label": "整体协调" }
      },
      "summary": {
        "relationship_type": {
          "id": "stable_growth",
          "label": "稳定成长型",
          "reasons": ["关系具有持续建设的空间。"]
        },
        "highlights": ["共同目标较容易形成。"],
        "risks": ["重要决定上可能需要更多磨合。"],
        "suggestions": ["明确长期安排与责任边界。"]
      }
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "method": "davison",
      "chart_a_label": "Person A",
      "chart_b_label": "Person B",
      "composite_label": "Davison Composite",
      "include_outer_planets": true,
      "davison": {
        "datetime": "1991-07-02T23:45:00",
        "timezone": "UTC",
        "latitude": 35.565,
        "longitude": 118.935
      }
    }
  }
}

POST /transit — 流年 / 行运 · 权重 1

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "transit_datetime": "2026-07-18T12:00:00",
  "transit_timezone": "Asia/Shanghai"
}

响应样例（流年盘在 transit；跨盘相位在 cross_aspects）：

{
  "snapshot": {
    "meta": {},
    "natal": {
      "label": "Natal",
      "angles": { "asc": 182.45, "mc": 97.12 },
      "planets": [{ "id": "sun", "sign": "taurus", "house": 8 }]
    },
    "transit": {
      "label": "Transits 2026-07-18",
      "angles": { "asc": 210.3, "mc": 124.8 },
      "planets": [{ "id": "jupiter", "sign": "cancer", "house": 10, "retrograde": false }]
    },
    "cross_aspects": [
      {
        "inner_body": "sun",
        "outer_body": "jupiter",
        "type": "sextile",
        "angle": 60,
        "orb": 0.75,
        "orb_deg": 0,
        "orb_min": 45,
        "orb_display": "0°45′",
        "applying": true,
        "separating": false,
        "phase": "A"
      }
    ],
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "natal_label": "Natal",
      "transit_label": "Transits 2026-07-18",
      "transit_datetime": "2026-07-18T12:00:00",
      "transit_timezone": "Asia/Shanghai",
      "include_outer_planets": true,
      "include_minor_aspects": false
    }
  }
}

推运类接口（共用请求体）

以下五个接口共用请求形状：

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "directed_datetime": "2026-07-18T12:00:00",
  "directed_timezone": "Asia/Shanghai"
}

#### POST /solar-arc — 太阳弧 · 权重 1

响应形状与 /transit 相同（推运盘在 transit），settings 可含 solar_arc_degrees、progressed_datetime。

{
  "snapshot": {
    "natal": { "label": "Natal", "angles": { "asc": 182.45, "mc": 97.12 }, "planets": [] },
    "transit": { "label": "Solar Arc 2026", "angles": { "asc": 218.1, "mc": 132.7 }, "planets": [] },
    "cross_aspects": [],
    "settings": {
      "house_system": "regiomontanus",
      "transit_datetime": "2026-07-18T12:00:00",
      "transit_timezone": "Asia/Shanghai",
      "solar_arc_degrees": 36.18,
      "progressed_datetime": "1990-06-20T08:12:00"
    }
  }
}

#### POST /secondary-progressions — 次限单盘 · 权重 1

{
  "snapshot": {
    "meta": {},
    "natal_ref": {
      "label": "Natal",
      "birth": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai" },
      "place_name": "Shanghai"
    },
    "chart": {
      "label": "Secondary Progressions 2026",
      "angles": { "asc": 220.4, "mc": 135.2 },
      "planets": [{ "id": "moon", "sign": "leo", "house": 9 }],
      "aspects": [],
      "houses": []
    },
    "settings": {
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "directed_datetime": "2026-07-18T12:00:00",
      "directed_timezone": "Asia/Shanghai",
      "progressed_datetime": "1990-06-20T08:12:00",
      "age_years": 36.18
    }
  }
}

#### POST /secondary-progressions/comparison — 次限比较 · 权重 1

形状同 /transit（次限盘在 transit），settings 含 age_years、progressed_datetime 等。

#### POST /tertiary-progressions — 三限单盘 · 权重 1

形状同次限单盘；settings 额外可含 age_lunar_months。

{
  "snapshot": {
    "natal_ref": { "label": "Natal", "birth": {}, "place_name": "Shanghai" },
    "chart": {
      "label": "Tertiary Progressions 2026",
      "angles": { "asc": 248.7, "mc": 162.3 },
      "planets": []
    },
    "settings": {
      "directed_datetime": "2026-07-18T12:00:00",
      "age_lunar_months": 447.5,
      "age_years": 36.18
    }
  }
}

#### POST /tertiary-progressions/comparison — 三限比较 · 权重 1

形状同 /transit；settings 可含 age_lunar_months、age_years。

POST /solar-return — 太阳返照 · 权重 1

{
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "return_year": 2026,
  "return_latitude": 31.23,
  "return_longitude": 121.47,
  "return_timezone": "Asia/Shanghai"
}

响应样例：

{
  "snapshot": {
    "meta": {},
    "natal_ref": {
      "label": "Natal",
      "birth": {},
      "sun_longitude": 54.32,
      "place_name": "Shanghai"
    },
    "return_chart": {
      "label": "Solar Return 2026",
      "angles": { "asc": 143.8, "mc": 46.1 },
      "planets": [{ "id": "sun", "sign": "taurus", "house": 10 }],
      "aspects": [],
      "houses": []
    },
    "settings": {
      "return_year": 2026,
      "house_system": "regiomontanus",
      "terms": "egyptian",
      "exact_return_datetime": "2026-05-15T20:18:42+08:00",
      "return_timezone": "Asia/Shanghai",
      "next_return_datetime": "2027-05-16T02:06:00+08:00",
      "return_period_start": "2026-05-15T20:18:42+08:00",
      "return_period_end": "2027-05-16T02:06:00+08:00",
      "return_latitude": 31.23,
      "return_longitude": 121.47,
      "return_place_name": "Shanghai",
      "location_from_natal": false
    }
  }
}

POST /lunar-return — 月亮返照 · 权重 1

在太阳返照字段基础上增加必填 return_month（1–12）。

响应样例：

{
  "snapshot": {
    "natal_ref": {
      "label": "Natal",
      "moon_longitude": 287.9,
      "place_name": "Shanghai"
    },
    "return_chart": {
      "label": "Lunar Return July 2026",
      "angles": { "asc": 88.4, "mc": 351.2 },
      "planets": [{ "id": "moon", "sign": "capricorn", "house": 5 }]
    },
    "settings": {
      "return_year": 2026,
      "return_month": 7,
      "natal_moon_longitude": 287.9,
      "exact_return_datetime": "2026-07-09T14:42:00+08:00",
      "next_return_datetime": "2026-08-05T23:10:00+08:00",
      "return_period_start": "2026-07-09T14:42:00+08:00",
      "return_period_end": "2026-08-05T23:10:00+08:00",
      "return_timezone": "Asia/Shanghai"
    }
  }
}

POST /timing/focus — 人生议题时间窗 · 权重 3

耗时可能较长（最长约 120s）。

{
  "topic": "relationship",
  "natal": { "datetime": "1990-05-15T14:30:00", "timezone": "Asia/Shanghai", "latitude": 31.23, "longitude": 121.47 },
  "at_date": "2026-07-18",
  "locale": "zh-CN"
}

响应样例（已本地化组合，不含原始 facts）：

{
  "snapshot": {
    "topic": "relationship",
    "at_date": "2026-07-18",
    "headline": "未来一段时间，关系议题有较清晰的推进窗口。",
    "paragraphs": [
      "时间窗口用于观察趋势，请结合现实选择与实际关系状态。",
      "当前阶段更适合逐步确认彼此的投入方式。"
    ],
    "life_context": {
      "firdaria_period": { "lord": "venus", "start": "2024-03-10", "end": "2032-03-10" },
      "profection_year": { "house": 1, "lord": "venus", "start": "2026-05-15", "end": "2027-05-15" }
    },
    "windows": [
      {
        "start": "2026-09-03",
        "end": "2026-10-12",
        "strength": 82,
        "label": "窗口偏强",
        "notes": ["适合推进关系确认与重要沟通。"]
      }
    ],
    "reasons": ["互动与承诺议题在此阶段更容易获得回应。"],
    "risks": ["避免因期待过快而忽略现实磨合。"]
  }
}

POST /electional/scan — 择日扫描 · 权重 5

耗时较长（最长约 120s）。

event_type：marriage、business_open、contract_sign、finance、travel、relocation、job_interview、medical_cosmetic。

特殊错误：502 l1_unavailable、503 electional_not_ready。

响应样例（heatmap / hourly 实际很长，此处缩略）：

{
  "snapshot": {
    "meta": {},
    "event_type": "marriage",
    "anchor_date": "2026-10-10",
    "location": {
      "timezone": "Asia/Shanghai",
      "latitude": 31.23,
      "longitude": 121.47,
      "place_name": "Shanghai"
    },
    "score_summary": {
      "best": 86,
      "median": 61,
      "veto_pct": 18.5,
      "candidates_15m": 1450,
      "windows": 4
    },
    "heatmap": [
      {
        "ts": "2026-10-09T10:00:00+08:00",
        "score": 82,
        "level": "excellent",
        "breakdown": { "natal_cross": 80, "final": 82 }
      }
    ],
    "hourly": [
      {
        "ts": "2026-10-09T10:00:00+08:00",
        "vetoed": false,
        "reasons": [],
        "score": 82,
        "level": "excellent",
        "breakdown": { "natal_cross": 80, "final": 82 }
      }
    ],
    "windows": [
      {
        "start": "2026-10-09T09:30:00+08:00",
        "end": "2026-10-09T11:15:00+08:00",
        "score": 86,
        "peak_ts": "2026-10-09T10:15:00+08:00",
        "breakdown": { "natal_cross": 84, "final": 86 },
        "notes": ["整体条件协调，适合安排正式仪式。"],
        "warnings": []
      }
    ],
    "l1_summary": {
      "scan_start": "2026-09-25",
      "scan_end": "2026-10-25",
      "total_hours": 744,
      "veto_count": 138,
      "veto_pct": 18.5,
      "eclipse_blackout_dates": []
    }
  }
}

POST /horoscope/daily — 每日运势 · 权重 1

响应样例：

{
  "snapshot": {
    "meta": {},
    "natal_label": "Natal",
    "daily": {
      "date": "2026-07-18",
      "timezone": "Asia/Shanghai",
      "variant_seed": "2026-07-18:Natal",
      "focus": {
        "house": 10,
        "near_angle": "mc",
        "moon_sign": "virgo",
        "moon_dignity": "neutral"
      },
      "mood": {
        "level": "steady",
        "moon_dignity": "neutral",
        "aspect": {
          "outer_body": "moon",
          "inner_body": "venus",
          "type": "trine",
          "orb_deg": 1,
          "orb_min": 8,
          "applying": true
        }
      },
      "relations": {
        "level": "supportive",
        "aspect": null,
        "seventh_ruler": "mars"
      },
      "action": {
        "level": "favorable",
        "void_of_course": false,
        "profection_lord_hit": {
          "lord": "venus",
          "trigger": "jupiter",
          "type": "sextile",
          "strength": "strong"
        }
      },
      "risk_window": null
    }
  }
}

POST /horoscope/monthly — 每月运势 · 权重 1

响应样例：

{
  "snapshot": {
    "meta": {},
    "natal_label": "Natal",
    "monthly": {
      "period_start": "2026-07-09T14:42:00+08:00",
      "period_end": "2026-08-05T23:10:00+08:00",
      "return_datetime": "2026-07-09T14:42:00+08:00",
      "variant_seed": "2026-07:Natal",
      "theme": {
        "lr_asc_in_natal_house": 10,
        "lr_moon_house": 3,
        "lr_chart_ruler": "mercury",
        "lr_chart_ruler_dignity": "neutral",
        "lr_moon_dignity": "strong"
      },
      "scores": {
        "career": { "value": 78, "max": 100, "factors": ["事业推进感较明显。"] },
        "relationships": { "value": 66, "max": 100, "factors": ["沟通与回应较为稳定。"] }
      },
      "peak_days": [
        { "date": "2026-07-22", "signal": "适合推进重要沟通。", "weight": 0.86 }
      ]
    }
  }
}

scores 的键名为动态集合，勿写死仅含 career / relationships。

主题解读 · 权重 2

请求体（二选一）：出生数据（同 /natal）+ 可选 format；或 { "snapshot": <natal snapshot>, "format": "sections" }。

curl -s -X POST https://tradastro.com/api/v1/interpretations/love \
  -H "Authorization: Bearer ta_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T14:30:00",
    "timezone": "Asia/Shanghai",
    "latitude": 31.23,
    "longitude": 121.47,
    "format": "sections"
  }'

format: "sections" 样例：

{
  "sections": [
    {
      "key": "love_overview",
      "title_zh": "爱情概览",
      "paragraphs": ["你在关系中重视稳定回应，也需要保留适度的个人空间。"],
      "facts_zh": [],
      "tone": "positive"
    },
    {
      "key": "love_romance",
      "title_zh": "恋爱与吸引",
      "paragraphs": ["你的吸引力表达自然，感情升温通常需要持续互动。"],
      "facts_zh": [],
      "tone": "neutral"
    }
  ]
}

format: "report" 样例：

{
  "section": {
    "key": "love_fortune",
    "title_zh": "爱情运",
    "paragraphs": [
      "【爱情概览】",
      "你在关系中重视稳定回应，也需要保留适度的个人空间。",
      "【恋爱与吸引】",
      "你的吸引力表达自然，感情升温通常需要持续互动。"
    ],
    "facts_zh": [],
    "tone": "positive"
  }
}

约定：facts_zh 固定为空数组；tone 为 positive / neutral / caution；段落为结论文案，不暴露计分依据。

响应结构说明

本命盘核心字段：angles、houses、planets、aspects、lots、firdaria、profections 等。推运比较类把「外盘」统一放在 transit（含流年、太阳弧、次限/三限比较）。合盘为 chart + chart_a / chart_b。返照为 return_chart + 周期时间字段。

对接建议：对目标接口打一次真实请求，将返回 JSON 固化为客户端类型；勿依赖未文档化的内部键名。

错误码

示例：

{ "error": "invalid_input", "details": { "formErrors": [], "fieldErrors": { "datetime": ["Required"] } } }

{ "error": "quota_exceeded", "used": 2000, "quota": 2000 }

目录接口

无需鉴权：

GET https://tradastro.com/api/v1
GET https://tradastro.com/api/v1/catalog

返回示例字段：

{
  "version": "v1",
  "auth": ["Authorization: Bearer <api_key>", "X-Api-Key: <api_key>"],
  "endpoints": [
    {
      "method": "POST",
      "path": "/api/v1/natal",
      "weight": 1,
      "summary_zh": "...",
      "summary_en": "..."
    }
  ]
}

版本与兼容

接入流程与 FAQ

建议流程

常见问题

Q: 月度配额是按 Key 还是按账号？

A: 按账号汇总；多 Key 共用同一配额。每分钟 60 次则是按 Key。

Q: 能否用网站里的 chartId？

A: 公开 v1 不支持 chartId；请传完整出生数据，或解读接口回传本命 snapshot。

Q: 合盘/解读里的分数如何计算？

A: 公开 API 不返回计分公式与权重明细；产品向结果以分数区间与结论文案呈现。

Q: 爱星盘那种 SDK / 白标小程序有吗？

A: 当前提供 HTTP JSON API；白标与私有部署请邮件洽谈。

Q: 超时怎么设？

A: 普通接口数秒内；timing/focus 与 electional/scan 建议客户端超时 ≥ 120s。

接口一览（速查）