星座配对：5 分钟接入指南（用 star1/star2 + 性别算出配对指数）
# 星座配对：5 分钟接入指南（用 star1/star2 + 性别算出配对指数）
> 接入点 872-2 · 免费 · POST/GET · JSON · 适用：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## TL;DR
- 星座配对是 ShowAPI 接口 872 的接入点 2，传入两个星座（`star1/star2`）及各自性别（`gender1/gender2`）即返回配对指数与文案。
- 四个参数**全部必填**；返回含综合/爱情/婚姻/天长地久等 8 类指数与多段解析文案。
- 文档明确标注「数据结果仅供娱乐参考」，产品中务必保留该免责声明。
## Why：这能解决什么
恋爱匹配、社交破冰、会员增值等场景常需要「你和 TA 配不配」的轻量互动。星座配对接口一次返回综合配对指数、爱情/婚姻/天长地久/两情相悦/友情/亲情指数、配对比重，以及恋爱建议、配对示例、缘分解析、注意事项、速配点评等多段文案，几乎可直接展示。
## What：接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/872-2?appKey={your_appKey}` |
| 接入点 | 872-2（星座配对） |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 鉴权 | AppKey |
| 计费 | 免费（设档位限制） |
| 免责 | 「数据结果仅供娱乐参考」 |
请求参数（均必填）：`star1`（星座1英文码）、`gender1`（1男0女）、`star2`（星座2英文码）、`gender2`（1男0女）。
## How：第一次调用
### 步骤 1：获取 AppKey
在 [AppKey 管理](https://www.showapi.com/console#/myApp) 复制 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=男 0=女
"star2": "shuiping", # 水瓶座
"gender2": "0",
}
r = requests.get(url, params=params, timeout=10)
data = r.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误: ret_code={body.get('ret_code')}")
print("综合配对指数:", body.get("match"))
print("爱情指数:", body.get("love"), "婚姻指数:", body.get("married"))
```
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"
```
Node.js（fetch）：
```js
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");
const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
const data = await res.json();
if (String(data.showapi_res_body?.ret_code) !== "0") throw new Error("业务失败");
console.log(data.showapi_res_body.match);
```
### 步骤 3：解析返回
返回 `match`（综合配对指数，如「70分」）、`love`/`married`/`forever`/`lqxy`/`friendship`/`affection`（各维度指数）、`proportion`（配对比重如「54:46」）、以及 `suggest`/`match_case`/`predestination`/`attention`/`review` 等文案字段。详见[配对字段全解](https://www.showapi.com/guides/constellation-match-fields-872)。
## 返回示例（结构示意）
```json
{
"showapi_res_body": {
"match": "70分",
"love": "3", "married": "2", "forever": "1", "lqxy": "3",
"friendship": "2", "affection": "2", "proportion": "54:46",
"grxz1": "天蝎座", "grxz2": "水瓶座",
"star1": "tianxie", "star2": "shuiping",
"gender1": "男", "gender2": "女",
"suggest": "（恋爱建议示例）",
"predestination": "（缘分解析示例）",
"review": "还蛮不错的一对",
"ret_code": "0"
}
}
```
## 进阶 / 边界
- **全部必填**：四个参数缺一不可，缺失会触发业务错误。
- **仅供娱乐**：评分与文案为娱乐性质，前端必须展示「结果仅供娱乐参考」，不可包装成严肃匹配结论。
- **指数均为字符串**：`match` 形如「70分」、`love` 形如「3」，展示前需自行解析为数值做星级/进度条渲染。
## FAQ
**Q：四个参数都必须传吗？**
A：是的，`star1/gender1/star2/gender2` 均为必填。性别用 1（男）/0（女）。
**Q：能只传一个星座做「自配」吗？**
A：接口设计为双星座配对，需两个星座 + 性别。单星座运势请使用接入点 1（[星座运势查询](https://www.showapi.com/guides/horoscope-quickstart-872)）。
**Q：配对结果能当真吗？**
A：文档明确标注「仅供娱乐参考」，请勿用于严肃场景，产品中保留免责声明即可。
## 下一步阅读
- [星座配对：返回字段与配对指数全解](https://www.showapi.com/guides/constellation-match-fields-872)
- [星座运势 API：星座社区与社交 App 集成场景设计](https://www.showapi.com/guides/horoscope-community-app-872)
- [星座运势 API：星座运营产品方案](https://www.showapi.com/guides/horoscope-product-plan-872)
- **本系列共 13 篇**：查看[星座运势 API 开发指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
