身份证归属地查询：返回字段全解（retData / address / birthday / sex 与系统级结构）
身份证归属地查询返回字段retDataaddressJSON解析 # 身份证归属地查询：返回字段全解（retData / address / birthday / sex 与系统级结构）
> 接口：身份证归属地查询（apiCode=25，接入点 25-3） · 免费 · 返回格式 JSON · 适用人群：所有开发者 · 阅读时间：约 4 分钟
## TL;DR
- 返回分两层：系统级（`showapi_res_code` 等）包裹业务级（`showapi_res_body`）。
- 你要的数据在 `showapi_res_body.retData`：`address`(籍贯)、`birthday`(生日)、`sex`(性别)。
- 成功判断看 `showapi_res_code == 0` 且 `showapi_res_body.ret_code == 0`。
## Why
读懂返回结构是正确解析、正确判错的前提。本接口返回采用 ShowAPI 通用封装：所有业务数据都包在 `showapi_res_body` 里，系统级字段在外层。分清这两层，才能写出稳健的解析代码。
## What
**请求要点**（回顾）：仅需 `id` 参数、AppKey 鉴权、POST/GET、JSON 返回。详见 [5 分钟接入](https://www.showapi.com/guides/idcard-attribution-quickstart-25)。
## How
### 系统级字段（外层）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | int | 系统级状态码，`0` 表示成功 |
| `showapi_res_error` | String | 系统级错误信息，成功时为空 |
| `showapi_res_id` | String | 本次请求会话 ID（文档示例字段名实际为 `showapi_res_id`，用于排查） |
| `showapi_res_body` | Object | 业务数据容器，下文结构均在此对象内 |
> 注：文档返回示例中会话字段写作 `showapi_res_id`（如 `ce135f6739294c63be0c021b76b6fbff`），解析时按文档示例键名取值。
### 业务级字段（`showapi_res_body` 内）
| 字段 | 类型 | 说明 |
|------|------|------|
| `errNum` | int | 业务错误号，`0` 表示正常 |
| `ret_code` | int | 业务返回码，`0` 表示成功 |
| `retMsg` | String | 业务消息，成功为 `success` |
| `retData` | Object | 身份证数据结构，含以下三项 |
### 业务数据 `retData`
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `address` | String | `四川省达州市通川区` | 籍贯（文档说明文亦称"签发地/归属地"，即身份证前 6 位对应的户口登记地区） |
| `birthday` | String | `1983-04-25` | 出生日期，格式 `YYYY-MM-DD` |
| `sex` | String | `F` | 性别，`M`=男、`F`=女 |
> **文档一致性提示**：字段表中 `retData` 标注为 `Object[]`（数组），但官方返回示例里 `retData` 是**单个 Object**（含 `address/birthday/sex`）。单号查询接入点实际返回单个对象，本文按示例（单对象）描述；若你后续见到数组形态，以实际返回为准。
## 返回示例
```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
}
}
```
**解析要点（Python）**
```python
body = data["showapi_res_body"]
if body["ret_code"] == 0:
rd = body["retData"]
print(rd["address"], rd["birthday"], rd["sex"])
```
## 进阶 / 边界
- **判成功要两层都看**：外层 `showapi_res_code == 0` 且内层 `ret_code == 0` 才算业务成功。
- **错误码枚举**：本接口文档**未列出专用错误码枚举**（仅给出成功态），常见错误处理见 [错误处理与排错](https://www.showapi.com/guides/idcard-attribution-errors-25)。
- **`address` 是"籍贯"而非实时定位**：它由号码前 6 位行政区码反查得到，与持证人当前所在地无关。
## FAQ
**Q：外层 showapi_res_code 和内层 ret_code 有什么区别？**
外层 `showapi_res_code` 是 ShowAPI 平台级状态（如鉴权、网关）；内层 `ret_code` 是本接口业务逻辑状态。两者都为 0 才是完整成功。
**Q：retData 到底是对象还是数组？**
单号查询接入点返回单个对象。文档字段表误标为数组，请以返回示例（单对象）为准。
**Q：sex 只有 M/F 两种吗？**
文档示例与说明中 `sex` 取值为 `M`(男) / `F`(女)。
**Q：birthday 的格式固定吗？**
示例为 `YYYY-MM-DD`（如 `1983-04-25`），按字符串原样使用即可。
**Q：showapi_res_id 有什么用？**
它是本次请求的会话标识，排查问题或向官方反馈时可作为依据提供。
## 相关能力 / 下一步阅读
- [身份证归属地查询：5 分钟接入，从注册到拿到第一条籍贯/生日/性别](https://www.showapi.com/guides/idcard-attribution-quickstart-25)
- [身份证归属地查询：错误处理与排错（showapi_res_code / ret_code 通用处理）](https://www.showapi.com/guides/idcard-attribution-errors-25)
- [身份证归属地查询：用户注册实名核验的集成设计（前端 + 后端）](https://www.showapi.com/guides/idcard-attribution-verify-25)
- **本系列共 12 篇**：查看[身份证归属地查询指南总目录](https://www.showapi.com/guides/idcard-attribution-guides-25)
