AstroSage API：构建类似 AstroSage 的占星聊天 App 或 Bot

如果你在搜索 AstroSage API，通常是想做三类产品之一：

1. 一个回答出生盘问题的 astrology chat app。
2. WhatsApp、Telegram、Discord 或网站 bot。
3. 一整套占星平台，包含 Vedic chart、dasha、Panchang、match making、horoscope 和 compatibility。

FreeAstroAPI 与 AstroSage 没有关联。对开发者有价值的是架构思路：我们的 Vedic 和 astrology endpoints 返回生产级结构化结果，覆盖面适合构建 AstroSage-like 用户体验。

换句话说，不要让 LLM 编造 chart math。API 负责确定性占星数据，AI 层负责把这些数据讲清楚。

为什么 AstroSage-like app 需要结构化占星数据

如果 bot 从 prompt 里尝试计算所有东西，占星聊天产品很容易出错。模型可能语气自信，但 ascendant、Moon Nakshatra、Vimshottari dasha、Panchang 或 compatibility 细节是错的。

更适合生产的做法：

1. 解析用户城市、timezone、latitude 和 longitude。
2. 调用 chart、dasha、Panchang、transit 或 compatibility endpoints。
3. 把结构化响应作为 source of truth 保存。
4. 让 chat model 只解释 API 返回的数据。
5. 保留内部引用，知道答案来自哪个 endpoint payload。

这样 app 有智能助理的体验，计算仍然确定、可重复。

AstroSage-style bot 的核心 endpoints

需要 onboarding payload 时，用 POST /api/v2/vedic/calculate。某个聊天回合只问一个问题时，用更专门的 endpoint，比如 “What dasha am I in?” 或 “Is today good for starting something?”。

推荐 MCP chat pipeline

如果你的 app 是 AI agent，优先使用 Hosted MCP 或自己的 tool-calling 层，而不是把每个 endpoint 硬塞进 prompt。

流程：

1. 分析用户问题，判断需要哪个占星事实。
2. 检查需要的 JSON 是否已在 cache 中。
3. 没有 cache 时，选择正确 MCP tool 或 API endpoint。
4. 用用户保存的出生数据和当前问题上下文调用工具。
5. 用 endpoint、input hash、user id 和 timestamp 缓存原始 JSON。
6. 给 AI 用户问题和相关 JSON。
7. 要求 AI 只根据 JSON 写最终回答，不补编缺失事实。

第一轮 AI 更像 router，不直接回答用户：

{
  "intent": "current_dasha_question",
  "needs_tool": true,
  "tool": "vedic_dasha",
  "cache_key": "user_123:vedic_dasha:2026-04-24:lahiri",
  "reason": "The user asked which dasha is active today."
}

然后 backend 执行 tool call，保存 JSON，再做第二轮 AI：

User question:
{question}

Tool JSON:
{cached_or_fresh_json}

Instruction:
Answer only from the Tool JSON. If the JSON does not contain the requested fact, say what additional tool or birth detail is needed.

这比让模型在一轮里判断、计算、解释都可靠。

Cache 策略

按 user、endpoint、normalized input、date 或 date range 缓存。

始终保存完整原始 JSON。可以另外保存小的 "facts" object 用于检索，但原始响应对调试和答案审计很重要。

Follow-up 处理

后续消息要先复用上下文，再考虑新 tool call。

把 conversation memory、cached astrology facts 和 fresh tool calls 分开，后续对话会稳定很多。

可组合的公共 endpoints

Vedic astrology endpoints

Western astrology endpoints

Chart rendering and visual endpoints

Astrocartography endpoints

Horoscope and simple sign endpoints

Chinese astrology endpoints

Utility and platform endpoints

逐步构建 chat app

Step 1: collect birth data once

Onboarding form 应收集：

• Name
• Date of birth
• Time of birth
• Birth city
• Latitude and longitude when available
• Timezone, or AUTO

生产环境中，坐标比城市名可靠，因为很多城市同名。用 city search 帮用户选对地点。

curl -G "https://api.freeastroapi.com/api/v2/geo/search" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "q=Mumbai" \
  --data-urlencode "country=IN" \
  --data-urlencode "limit=5"

Step 2: create the user's core Vedic profile

onboarding 后调用 full calculate endpoint，把响应作为用户 astrology profile 保存。

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "year": 1994,
    "month": 8,
    "day": 11,
    "hour": 6,
    "minute": 42,
    "city": "Mumbai",
    "lat": 19.0760,
    "lng": 72.8777,
    "tz_str": "AUTO",
    "ayanamsha": "lahiri",
    "vargas": [1, 9, 10],
    "include_yogas": true,
    "include_panchang": true,
    "include_shadbala": true,
    "include_ashtakavarga": true,
    "dasha_levels": 3
  }'

这个响应足以回答 Lagna、Moon Nakshatra、当前 dasha、career yogas、D9 和婚姻等常见问题。

Step 3: route each user question

不要每条消息都调用所有 endpoints。先分类 intent。

这样可以控制延迟和成本。

Step 4: pass structured facts into the LLM

Prompt 应告诉 LLM 解释 API payload，不要重新计算。

You are an astrology assistant for a Vedic astrology app.
Use only the structured API facts below.
Do not invent planetary positions, dashas, Nakshatras, yogas, or compatibility scores.
If the needed fact is missing, ask for the missing input or say that this endpoint was not called.

User question:
{user_message}

FreeAstroAPI facts:
{json_from_relevant_endpoint}

Step 5: add memory without changing the chart

• Permanent facts: birth data, chart positions, dasha timeline, vargas, Panchang at birth.
• Session memory: preferred language, tone, current goal, relationship context, recent questions.
• Fresh facts: today's Panchang, current dasha, current Gochar, daily horoscope.

这样可以避免 assistant 把之前的解释当成新的 chart fact。

Step 6: build safe answer templates

每个聊天答案最好有固定形状：

1. 直接回答，一两句话。
2. 来自 API payload 的证据。
3. 实用解释。
4. 可选的下一步问题或动作。

You are currently in Moon Mahadasha and Saturn Antardasha.
The API dasha payload shows Moon as the active Mahadasha lord and Saturn as the active sub-period lord for the selected reference date.
This usually focuses the reading on emotional security, home, responsibility, and long-term discipline.
If you want, I can compare this dasha with your current Gochar timeline.

建议 app 架构

在 frontend 和 FreeAstroAPI 之间放一个小 backend。

User interface
  -> Your backend chat route
  -> Intent classifier
  -> FreeAstroAPI endpoint call
  -> Structured payload store
  -> LLM response generation
  -> Chat answer with endpoint-backed facts

不要把 API key 暴露到 browser JavaScript。x-api-key 保留在服务器端。

Minimal Node.js server example

const API_BASE = "https://api.freeastroapi.com";

async function getVedicProfile(birthData: Record<string, unknown>) {
  const response = await fetch(`${API_BASE}/api/v2/vedic/calculate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.FREEASTROAPI_KEY || "",
    },
    body: JSON.stringify({
      ...birthData,
      tz_str: "AUTO",
      ayanamsha: "lahiri",
      vargas: [1, 9, 10],
      include_yogas: true,
      include_panchang: true,
      include_shadbala: true,
      include_ashtakavarga: true,
      dasha_levels: 3,
    }),
  });

  if (!response.ok) {
    throw new Error(`FreeAstroAPI request failed: ${response.status}`);
  }

  return response.json();
}

SEO content strategy

如果公开发布 app，可以围绕真实搜索意图建立页面：

• "AstroSage API alternative"
• "Vedic astrology API"
• "Kundli API for developers"
• "Dasha API"
• "Panchang API"
• "Astrology chatbot API"
• "Build an astrology bot"

每个页面都应该解释具体功能、展示 live example、列出使用的 endpoint，并链接到文档。

常见错误

1. 不要让 LLM 从原始出生数据计算 chart。
2. 不要忽略 timezone 和历史地点处理。
3. 不要每条消息都调用昂贵 endpoints。
4. 不要混用 Western 和 Vedic 概念而不标注系统。
5. 不要把生成解释当成确定性 chart data。
6. 不要只存最终文本。也要存 API payload。

开始构建

FreeAstroAPI 提供 Vedic charts、dasha、Panchang、compatibility、Gochar、horoscopes、Western charts、synastry、moon data 和 chart rendering 的计算层。

先接入 Vedic calculate endpoint，再添加 dasha 和 Panchang intents，之后扩展到 compatibility、Gochar 和 daily horoscope。