身份证归属地查询：5 分钟接入，从注册到拿到第一条籍贯/生日/性别
# 身份证归属地查询：5 分钟接入，从注册到拿到第一条籍贯/生日/性别
> 接口：身份证归属地查询（apiCode=25，接入点 25-3） · 免费 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## TL;DR
- 这是一个**免费**接口，但调用仍需在请求里带上你的 AppKey 鉴权。
- 只需要传一个参数 `id`（18 位身份证号），返回 `address`(籍贯)、`birthday`(生日)、`sex`(性别)。
- 复制下面任一段代码，把 `YOUR_APPKEY` 换成你自己的，即可跑通。
## Why
在用户注册、实名核验、风控初审等场景，你常常需要"凭一个身份证号，知道它是哪里的、哪天生的、男还是女"。与其自己维护一张地区码对照表，不如直接调一个稳定、免费、官方自营的接口——传入号码，拿回结构化结果。
本接口由万维易源（ShowAPI）官方自营（服务商：昆明秀派科技有限公司），免费提供，适合作为你业务链路里的"轻量查证"一环。
## What
| 项 | 值 |
|----|----|
| 接口 / 接入点 | 身份证归属地查询 · 接入点 `25-3` |
| 接口地址 | `https://route.showapi.com/25-3?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 鉴权 | 查询参数 `appKey`（必带，免费接口也需要） |
| 计费 | 免费服务 |
| 返回格式 | JSON |
| 集成能力 | MCP、OpenAPI 3.0（见系列第 10、11 篇） |
**请求参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | String | 是 | 18 位身份证号，示例 `522423199105047376` |
| `content-type`（Header） | String | 否 | POST 表单建议 `application/x-www-form-urlencoded` |
## How
### 步骤 1：获取 AppKey
登录 ShowAPI 控制台 → [我的 AppKey](https://www.showapi.com/console#/myApp)，复制任意一个 AppKey。
### 步骤 2：第一次调用（任选一种）
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/25-3"
def query_idcard(id_number: str) -> dict:
resp = requests.post(URL, params={"appKey": APP_KEY},
data={"id": id_number}, timeout=10)
resp.raise_for_status()
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"接口错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务错误: {body.get('retMsg')}")
return body["retData"]
if __name__ == "__main__":
ret = query_idcard("522423199105047376")
print(ret)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/25-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "id=522423199105047376"
```
**Node.js（fetch）**
```js
const APP_KEY = "YOUR_APPKEY";
const URL = "https://route.showapi.com/25-3";
async function queryIdCard(idNumber) {
const resp = await fetch(`${URL}?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ id: idNumber }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
const body = data.showapi_res_body;
if (body.ret_code !== 0) throw new Error(body.retMsg);
return body.retData;
}
queryIdCard("522423199105047376").then(console.log).catch(console.error);
```
### 步骤 3：看返回
返回体里 `showapi_res_body.retData` 就是你要的三项。字段含义见 [身份证归属地查询：返回字段全解](https://www.showapi.com/guides/idcard-attribution-fields-25)。
## 返回示例
以下为**官方文档返回示例**（非实时调用结果），展示结构：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"errNum": 0,
"retData": {
"address": "四川省达州市通川区",
"birthday": "1983-04-25",
"sex": "F"
},
"retMsg": "success",
"ret_code": 0
}
}
```
> 说明：实际返回值的籍贯/生日/性别取决于你传入的身份证号；不同号码对应不同结果。
## 进阶 / 边界
- **免费但仍需 AppKey**：路由必须带 `?appKey=`，否则无法鉴权。
- **单接入点、单号查询**：一次调用返回一个身份证的结果；批量请见[批量核验](https://www.showapi.com/guides/idcard-attribution-batch-25)。
- **接口不校验真伪**：它只按号码反推户籍地区/生日/性别，不判断该身份证是否真实存在。
## FAQ
**Q：调用这个接口要花钱吗？**
不需要。身份证归属地查询是免费服务，但请求中仍需携带有效的 AppKey 完成鉴权。
**Q：GET 和 POST 都可以吗？**
可以。文档标注请求方式为 POST/GET，两种方式均可，参数都通过 `id` 传递、鉴权通过 `appKey` 查询参数。
**Q：返回的 sex 是什么含义？**
`sex` 为 `M` 表示男性，`F` 表示女性。
**Q：为什么我传的号码和返回示例里的籍贯对不上？**
返回示例是官方给出的独立样例值，实际结果由你传入的具体身份证号决定，不同号码自然对应不同的籍贯/生日/性别。
**Q：AppKey 泄露了怎么办？**
在 [AppKey 管理](https://www.showapi.com/console#/myApp) 重置或删除对应密钥，并避免在客户端代码里硬编码。
## 相关能力 / 下一步阅读
- [身份证归属地查询：返回字段全解（retData / address / birthday / sex 与系统级结构）](https://www.showapi.com/guides/idcard-attribution-fields-25)
- [身份证归属地查询：用户注册实名核验的集成设计（前端 + 后端）](https://www.showapi.com/guides/idcard-attribution-verify-25)
- [身份证归属地查询：错误处理与排错（showapi_res_code / ret_code 通用处理）](https://www.showapi.com/guides/idcard-attribution-errors-25)
- **本系列共 12 篇**：查看[身份证归属地查询指南总目录](https://www.showapi.com/guides/idcard-attribution-guides-25)
