星座配对：用四个必填参数算出配对指数
约 14 分钟 入门星座配对API快速接入配对指数免费接口
# 星座配对：用四个必填参数算出配对指数
接入点 872-2 · 免费服务 · POST / GET · 返回 JSON · 适用：新注册用户、社交产品开发者 · 阅读时间：约 6 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 星座配对接口（apiCode=872）的接入点 2 接收 `star1`、`gender1`、`star2`、`gender2` 四个必填参数，返回 22 个字段。
- 指数全是字符串：`match` 形如 `50分`，`love` / `married` / `forever` / `lqxy` / `friendship` / `affection` 是纯数字字符串，`proportion` 形如 `58:42`。
- `gender1`、`gender2` 的取值口径是「1 为男，其他值按女处理」；2026-09-18 实测性别不参与指数计算。
## 这个接口解决什么
「你和 TA 配不配」是社交产品里转化率很高的一次互动。用户填两个星座和性别，接口一次返回综合配对指数、爱情、婚姻、天长地久、两情相悦、友情、亲情七项分数，加配对比重和五段解析文案，结果页基本不用再加工。
星座配对接口（apiCode=872）的接入点 2 结构很平，返回值就是一层键值对，没有嵌套。
## 接口速览
| 项 | 值 |
|---|---|
| 接口地址 | `https://route.showapi.com/872-2?appKey={your_appKey}` |
| 接入点 | 872-2 星座配对 |
| 请求方式 | POST / GET（表单 `application/x-www-form-urlencoded`） |
| 返回格式 | JSON |
| 鉴权 | AppKey |
| 计费 | 免费服务，与同接口其他接入点统一计费 |
| 必填参数 | `star1`、`gender1`、`star2`、`gender2` |
| 超时 | 读 5 秒 / 连接 5 秒（取自 OpenAPI 文档，比接入点 1 的 15 秒短） |
| 免责口径 | 接口文档明确「数据结果仅供娱乐参考」 |
四个参数都是必填，缺任意一个都无法返回配对结果。
## 第一次调用
### 步骤 1：拿到 AppKey
登录 ShowAPI 后，在 AppKey 管理里复制你的 AppKey，替换下面代码里的 `YOUR_APPKEY`。
### 步骤 2：发请求
Python（requests）：
```python
import requests
url = "https://route.showapi.com/872-2"
params = {
"appKey": "YOUR_APPKEY",
"star1": "tianxie", # 天蝎座
"gender1": "1", # 1 为男
"star2": "shuiping", # 水瓶座
"gender2": "0", # 0 为女
}
try:
r = requests.get(url, params=params, timeout=5) # 超时对齐文档的 5 秒
r.raise_for_status()
data = r.json()
except requests.RequestException as e:
raise RuntimeError(f"请求失败: {e}")
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误 {data.get('showapi_res_code')}: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误: {body.get('remark')}")
# 指数都是字符串，渲染前自行解析
score = int(str(body["match"]).replace("分", ""))
print("综合配对指数:", score, "| 比重:", body["proportion"], "|", body["review"])
```
cURL：
```bash
curl -G "https://route.showapi.com/872-2" \
--data-urlencode "appKey=YOUR_APPKEY" \
--data-urlencode "star1=tianxie" \
--data-urlencode "gender1=1" \
--data-urlencode "star2=shuiping" \
--data-urlencode "gender2=0" \
--max-time 5
```
Node.js（fetch）：
```javascript
const url = new URL("https://route.showapi.com/872-2");
url.searchParams.set("appKey", "YOUR_APPKEY");
url.searchParams.set("star1", "tianxie");
url.searchParams.set("gender1", "1");
url.searchParams.set("star2", "shuiping");
url.searchParams.set("gender2", "0");
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
const data = await res.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
const body = data.showapi_res_body;
if (String(body.ret_code) !== "0") throw new Error(body.remark);
const score = parseInt(String(body.match), 10); // "50分" -> 50
console.log(score, body.proportion, body.review);
console.log("结果仅供娱乐参考");
} catch (e) {
console.error("配对结果暂不可用:", e.message);
}
```
### 步骤 3：读返回
配对结果没有嵌套，`showapi_res_body` 下直接是 22 个字段。渲染一张结果页需要的主要是三类：`match` 做综合分，`proportion` 做双方比重条，`review` / `suggest` / `predestination` 做文案区。
`gender1`、`gender2` 回显的是中文「男」「女」，不是你传进去的 `1` / `0`。字段逐项含义见配对返回字段全解。
## 返回示例（2026-09-18 真实返回，长文案已截断）
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"match": "50分",
"love": "2", "married": "2", "forever": "2", "lqxy": "5",
"friendship": "2", "affection": "3",
"proportion": "58:42",
"grxz1": "天蝎座", "grxz2": "水瓶座",
"star1": "tianxie", "star2": "shuiping",
"gender1": "男", "gender2": "女",
"review": "需要努力维持的一对",
"remark": "查询成功！",
"ret_code": 0
}
}
```
同一对星座重复请求结果一致，2026-09-18 用同参数连调两次，返回体逐字节相同，可以放心做缓存。
## 参数说明
`star1`、`star2` 取十二星座英文码：`baiyang`、`jinniu`、`shuangzi`、`juxie`、`shizi`、`chunv`、`tiancheng`、`tianxie`、`sheshou`、`mojie`、`shuiping`、`shuangyu`。
`gender1`、`gender2` 的文档口径是「1 为男，0 为女」。2026-09-18 实测传 `2` 和 `9` 时接口把两方都按女处理并回显「女」，所以实际生效的是「值为 `1` 判男，其余判女」。
`gender1`、`gender2` 与返回的 `star1`、`star2` 不保证按同一顺序对应。2026-09-18 实测传入 `star1=baiyang`（`gender1=0`）、`star2=jinniu`（`gender2=1`）时，返回的是 `star1=jinniu`、`star2=baiyang`，而 `gender1` 仍为「女」。把 `grxz1` 和 `gender1` 拼成「用户 A」的展示元素时，顺序会错位。
## 结果页的展示建议
指数是字符串，先用 `parseInt` 或 `Number()` 转成数值再算进度条长度。`match` 自带「分」字，取值时把单位去掉。
各维度的满分基线接口文档没有给出，展示上建议用相对星级或相对条，不要标注具体百分比。
配对结果是娱乐性质，接口文档明确标注「数据结果仅供娱乐参考」。结果页和分享图保留这句说明。
## FAQ
**Q1：四个参数都必须传吗？**
必须。2026-09-18 实测缺 `gender2` 时，系统级返回 `showapi_res_code: -1`、`showapi_res_error: must input gender2 field`，业务体为空。
**Q2：能只传一个星座吗？**
不能，接口按双星座设计。查单个星座的运势用接入点 1 的星座运势查询。
**Q3：性别会影响配对分数吗？**
2026-09-18 实测不影响。`star1=shizi, gender1=1` 配 `star2=jinniu`，`gender2` 分别传 `0` 和 `1`，两次返回的 `match`、`love`、`proportion`、`review`、`attention` 全部相同。性别字段回显的是传入位置的取值，不参与指数计算。
**Q4：`star1` 传错会怎样？**
实测 `star1=xxx` 时系统级 `showapi_res_code` 为 `0`，业务层返回 `ret_code: -1`、`remark: 未查询到相关星座之间的匹配，请确认输入是否正确！`。
**Q5：能拿配对分数做严肃的匹配结论吗？**
不建议。接口文档标注「数据结果仅供娱乐参考」，产品里保留这句免责说明。
## 下一步阅读
- [星座配对返回字段全解：22 个字段的含义与实测取值](https://www.showapi.com/guides/constellation-match-fields-872)
- [星座类产品的三条内容线](https://www.showapi.com/guides/horoscope-product-plan-872)
- [星座运势查询：用 Python / cURL / Node.js 跑通第一次调用](https://www.showapi.com/guides/horoscope-quickstart-872)
- [在星座社区与社交 App 里接入星座运势查询](https://www.showapi.com/guides/horoscope-community-app-872)
- **本系列共 13 篇**：查看[星座运势 API 指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
