星座运势 API 开发指南总目录
约 9 分钟 入门星座运势API官方指南目录免费接口API 文档索引
# 星座运势 API 开发指南总目录
接口 872（星座运势）· 免费服务 · POST / GET · 返回 JSON · 官方自营（昆明秀派科技有限公司）· 适用：开发者 / 产品经理 / 运营 · 阅读时间：约 8 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 星座运势接口（apiCode=872）共 2 个接入点：星座运势查询（872-1）与星座配对（872-2）。
- 本目录收录 13 篇指南，按入门、场景实战、技术深挖、行业方案、生态集成五层组织。
- 全系列的数据来自官方文档与 2026-09-18 的真实调用实测，实测与文档不一致的地方按实测写并注明文档原文口径。
## 接口一句话速览
星座运势接口（apiCode=872）提供十二星座的今日、明日、本周、本月、本年运势，以及双星座配对指数，适用于星座社区、爱情匹配、心灵治愈等场景。注册后默认可免费调用，平台为防止滥用设有使用档次限制。数据每天 1 点、7 点、17 点更新（接口文档页「更新频率」字段原文），支持 MCP 服务与 OpenAPI 3.0 文档。
| 接入点 | 名称 | 说明 |
|---|---|---|
| 872-1 | 星座运势查询 | 五周期运势，支持按 `date` 自动识别星座 |
| 872-2 | 星座配对 | 四个必填参数，返回八类指数与七段文案 |
## 文章总目录
### 入门层
1. [星座运势查询：用 Python / cURL / Node.js 跑通第一次调用](https://www.showapi.com/guides/horoscope-quickstart-872) — 从 AppKey 到第一条今日运势，含三种语言的完整代码与两层状态码判断。
2. [星座运势查询返回字段全解：五个周期的字段对照与实测类型](https://www.showapi.com/guides/horoscope-response-fields-872) — 五个周期共 15 到 18 个字段的逐项说明与类型实测。
3. [星座配对：用四个必填参数算出配对指数](https://www.showapi.com/guides/constellation-match-quickstart-872) — 四个必填参数到一张结果页的完整流程。
### 场景实战层
4. [星座配对返回字段全解：22 个返回字段的含义与实测取值](https://www.showapi.com/guides/constellation-match-fields-872) — 八类指数、七段文案与元信息字段的对照表。
5. [星座运势查询的 date 参数怎么用？按生日识别星座与 12 个边界实测](https://www.showapi.com/guides/horoscope-by-date-872) — 接口实际使用的星座日期边界逐日实测表。
6. [星座运势查询不传 needX 开关会返回什么？五个周期实测规则](https://www.showapi.com/guides/horoscope-multi-period-872) — 四个开关的返回规则与一次取齐的写法。
### 技术深挖层
7. [星座运势查询的指数怎么读：5 分制与 100 分制两套口径](https://www.showapi.com/guides/horoscope-index-meaning-872) — 两套量纲的字段对照、类型处理与归一化写法。
8. [星座运势查询的缓存怎么设：按星座加周期加日期建键](https://www.showapi.com/guides/horoscope-cache-872) — 键粒度实验、TTL 对齐与预热任务的完整实现。
9. [星座运势查询返回 -1 是什么意思？两层状态码分层排查](https://www.showapi.com/guides/horoscope-error-handling-872) — 实测错误对照表与分层异常处理代码。
### 行业方案层
10. [在星座社区与社交 App 里接入星座运势查询](https://www.showapi.com/guides/horoscope-community-app-872) — 数据表设计、刷新时序与分享图生成。
11. [星座类产品的三条内容线：星座运势查询与星座配对的组合用法](https://www.showapi.com/guides/horoscope-product-plan-872) — 每日运势、配对互动、周期内容三条线的内容结构与增值点位置。
### 生态集成层
12. [星座运势 API 接进 Cherry Studio / ChatBox：MCP 配置与两个工具](https://www.showapi.com/guides/horoscope-mcp-872) — MCP 端点、四步握手与两个可用工具。
13. [星座运势 API 导入 Postman / Swagger UI：OpenAPI 3.0 文档的用法](https://www.showapi.com/guides/horoscope-openapi-872) — 文档地址、接入点级超时配置与代码生成注意事项。
## 相关资源
| 资源 | 链接 |
|---|---|
| 接口详情页（872） | `https://www.showapi.com/apiGateway/view/872` |
| 接入点 1：星座运势查询 | `https://www.showapi.com/apiGateway/view/872/1` |
| 接入点 2：星座配对 | `https://www.showapi.com/apiGateway/view/872/2` |
| OpenAPI 3.0（YAML） | `https://www.showapi.com/openapi/market/872.yaml` |
| OpenAPI 3.0（JSON） | `https://www.showapi.com/openapi/market/872.json` |
| AppKey 管理 | `https://www.showapi.com/console#/myApp` |
| 免费接口与档位说明 | `https://www.showapi.com/free-api` |
## 阅读建议
第一次接入先读第 1、2 篇，拿到数据再看自己业务需要的周期。做星座社区或社交产品，第 5、8、10、11 篇是重点。用 AI 工具链的话，直接看第 12、13 篇。
只想查具体的一个问题，按目录标题找对应那篇即可，每篇的 FAQ 都覆盖了该主题最常见的误用点。
## 实测一览
系列文章中标注为实测的数据，来自 2026-09-18 对两个接入点的真实调用。几处与接口文档不一致的地方已在对应文章里说明：
| 项 | 文档口径 | 实测 |
|---|---|---|
| 五个周期对象的形态 | `Object[]` | 单个对象 |
| `ret_code` 类型 | 参数表标注 String | 数字 `0` |
| 12 星座日期边界 | 未给出 | 与常见对照表存在偏移，已在第 5 篇列出 |
| 接入点 2 返回的 `star1` / `star2` | 未说明 | 与传入顺序不保证一致 |
| 接入点 2 的超时 | 文档页不展示 | 读 5 秒 / 连接 5 秒 |
## FAQ
**Q1：星座运势接口收费吗？**
免费服务。注册后默认可免费调用，平台为防止滥用设有使用档次限制，具体档位见免费接口与档位说明页。
**Q2：数据多久更新一次？**
接口文档页标注为每天 1 点、7 点、17 点更新，两个接入点共用这个更新频率。
**Q3：星座配对的结果可信吗？**
接口文档明确标注「数据结果仅供娱乐参考」，产品中作为趣味互动呈现即可。
**Q4：两个接入点需要分别拿 AppKey 吗？**
不需要。同一个接口下的接入点共用一个 AppKey，也是同一套计费口径。
**Q5：这套指南的数据来源是什么？**
接口文档、产品说明页与免费接口页的原文口径，加上 2026-09-18 的真实调用实测。文档与实测冲突时按实测写，并注明文档原文。
**Q6：接口有多少个接入点？**
2 个。侧栏与 OpenAPI 文档的 `paths` 一致，都是 `/872-1` 与 `/872-2`。
