身份证归属地查询接口：从鉴权到缓存机制的工程化接入指南
1. 适用场景
在用户准备、实名认证、风控审核、数据治理等业务中，常常需要根据身份证号快速获知持卡人的户籍所在省、市、区。例如：
- 用户准备环节：校验用户填写的户籍地是否与身份证号前6位匹配，用于辅助防刷。
- 风控规则引擎：通过归属地分析用户地域分布，识别异常聚集或跨域行为。
- 数据清洗：对存量身份证号进行属地标注，用于报表统计或字段补全。
- 服务区域限制：某些业务仅对特定省份开放，需要实时校验身份证属地。
上述场景并不要求验证身份证真伪（需调用实名校验接口），仅需前6位区划代码即可获得省/市/区三级归属。本文介绍的接口正为此类需求设计。
2. 接口能力边界
在集成前必须明确以下几点：
- 输入：身份证号前6位（即区划代码），或15/18位完整身份证号（自动提取前6位）。
- 输出：省、市、区的代码和中文名称，同时将传入的身份证号脱敏回显（中间部分用*代替）。
- 不提供：身份证号真实性校验、照片比对、年龄性别解析。这些属于其他接口范畴。
- 性能：单接口QPS上限为10次/秒，适合中小规模查询，大流量场景需做请求聚合或缓存。
- 数据源：省份区划数据从CDN拉取并本地缓存30天；网关层Redis缓存24小时。这意味着首次启动或缓存过期后第一次查询可能延迟稍高，后续毫秒级返回。
3. 鉴权方式与请求参数
3.1 鉴权
接口使用API Key进行身份认证。调用时需在请求头中携带密钥。根据官方示例，支持以下两种传递方式（以文档为准）：
- 使用
Authorization头：-H "Authorization: YOUR_API_KEY" - 使用
X-API-Key头：-H "X-API-Key: YOUR_API_KEY"
生产环境中建议将API Key存储在环境变量或密钥管理服务中，避免硬编码。
3.2 请求参数
| 参数名 | 必须 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
idcard | 是 | string | 6位区划代码，或15/18位身份证号码 | 110101或110101199001011234 |
请求方法为GET，终端地址：
https://v1.apizero.cn/api/idcard-region?idcard=1101014. 接入示例
4.1 curl 命令行
以下是一个完整的curl调用，假设API Key已通过环境变量IDCARD_API_KEY设置：
export IDCARD_API_KEY="your_api_key_here" curl -sS -X GET \ -H "Authorization: $IDCARD_API_KEY" \ "https://v1.apizero.cn/api/idcard-region?idcard=110101"若成功，返回的JSON如下（已格式化）：
{ "code": 0, "msg": "成功", "data": { "province": { "code": "110000", "name": "北京市" }, "city": { "code": "110100", "name": "北京市" }, "district": { "code": "110101", "name": "东城区" }, "idcard": "110101************" } }4.2 Python 代码示例
使用requests库实现上述调用，并处理基本异常：
import os import requests import json def query_idcard_region(idcard: str) -> dict: api_key = os.environ.get("IDCARD_API_KEY") if not api_key: raise ValueError("环境变量 IDCARD_API_KEY 未设置") url = "https://v1.apizero.cn/api/idcard-region" headers = {"Authorization": api_key} params = {"idcard": idcard} resp = requests.get(url, headers=headers, params=params, timeout=10) if resp.status_code != 200: raise Exception(f"HTTP错误: {resp.status_code}, 响应: {resp.text}") result = resp.json() if result.get("code") != 0: raise Exception(f"API错误: {result.get('msg')}") return result["data"] # 使用示例 if __name__ == "__main__": try: data = query_idcard_region("110101") print(json.dumps(data, ensure_ascii=False, indent=2)) except Exception as e: print(f"查询失败: {e}")5. 返回值深度解读
每次成功响应均包含以下固定结构：
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码，0表示成功，非0表示错误 |
msg | string | 对应状态的文字描述 |
data | object | 主要数据对象 |
data.province | object | 省级信息：code（6位代码），name（中文名称） |
data.city | object | 市级信息：code，name |
data.district | object | 区级信息：code，name |
data.idcard | string | 脱敏后的身份证号，中间8位用*代替 |
注意：直辖市（如北京、上海）的 city 和 province 名称相同；区级代码精确到区（如东城区 110101）。如果传入的是完整身份证号，
data.idcard会保留前6位和后4位，其余隐藏。
6. 常见错误与排查
| HTTP状态码 | 含义 | 排查建议 |
|---|---|---|
| 400 | Bad Request | 检查idcard参数格式：必须为6位数字或15/18位身份证号，不能包含空格或非数字字符 |
| 401 | Unauthorized | API Key 缺失或错误。确认Authorization或X-API-Key头已正确传递，且密钥有效 |
| 403 | Forbidden | 可能因QPS超限（每秒超过10次）或IP被临时封禁。降低请求频率，或联系服务提供方解封 |
| 500 | Internal Server Error | 服务端异常，建议等待后重试，若持续失败则反馈技术支持 |
| 200但code非0 | 业务错误 | 例如idcard前6位不在区划表中（如无归属地），此时msg会提示“未找到对应信息” |
7. 工程化注意事项
7.1 两级缓存机制详解
该接口内部使用了双层缓存来提升响应速度：
- CDN层缓存：省市区划的静态数据（JSON文件）从CDN拉取，客户端（SDK或服务）本地缓存30天。这减少了每次请求都回源的开销。
- 网关Redis缓存：API网关将查询结果缓存24小时，相同idcard的请求在缓存有效期内直接返回，不穿透后端。
工程启示：
- 如果你的服务也会重复查询相同的区划代码，可以自己在本地再加一层内存缓存（如LRU Cache），设置TTL为1小时，进一步降低对API的依赖。
- 当CDN缓存过期时，第一个请求的延迟可能上升到几百毫秒（取决于网络），因此冷启动时需预留超时时间（建议5秒）。
- 注意：缓存可能导致数据更新延迟（区划代码偶有调整），如需实时性，可主动清除本地缓存在业务低峰期重新拉取。
7.2 密钥安全管理
- 不要将API Key硬编码在代码仓库中。使用环境变量、配置中心或密钥管理服务（如Vault）。
- 定期轮换密钥，并在灰度环境中验证新密钥后再全量切换。
- 如果客户端是移动端或浏览器端，建议通过后端代理转发，避免直接暴露API Key。
7.3 高可用与重试策略
- 对于非5xx错误（如400、401），不应重试，应记录日志并终止。
- 对于5xx错误或网络超时，可实施指数退避重试，初始间隔1秒，最大重试3次。
- 当遇到QPS限制（403）时，应加入请求队列或采用令牌桶限流，而不是暴力重试。
7.4 脱敏数据的处理
接口返回的idcard字段已内置脱敏，前端可直接展示用于确认，无需再次处理。但注意：如果业务需要显示完整身份证号，则必须另外调用专门的脱敏接口或自行处理，但此接口不会返回完整号。
7.5 数据一致性
由于区划代码偶尔会因行政区划调整而变更（如撤县设区），建议定期（如每月）从官方来源同步最新区划表，并与接口返回的code做交叉验证。如果发现接口返回的name与你本地数据库不一致，应以接口返回为准（因为接口数据来自最新CDN文件）。
8. 参考文档
- 身份证归属地查询接口文档页
- 原始Markdown文档