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是string6位区划代码或15/18位身份证号码110101或110101199001011234请求方法为GET终端地址https://v1.apizero.cn/api/idcard-region?idcard1101014. 接入示例4.1 curl 命令行以下是一个完整的curl调用假设API Key已通过环境变量IDCARD_API_KEY设置export IDCARD_API_KEYyour_api_key_here curl -sS -X GET \ -H Authorization: $IDCARD_API_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101若成功返回的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, headersheaders, paramsparams, timeout10) if resp.status_code ! 200: raise Exception(fHTTP错误: {resp.status_code}, 响应: {resp.text}) result resp.json() if result.get(code) ! 0: raise Exception(fAPI错误: {result.get(msg)}) return result[data] # 使用示例 if __name__ __main__: try: data query_idcard_region(110101) print(json.dumps(data, ensure_asciiFalse, indent2)) except Exception as e: print(f查询失败: {e})5. 返回值深度解读每次成功响应均包含以下固定结构字段类型说明codeint状态码0表示成功非0表示错误msgstring对应状态的文字描述dataobject主要数据对象data.provinceobject省级信息code6位代码name中文名称data.cityobject市级信息codenamedata.districtobject区级信息codenamedata.idcardstring脱敏后的身份证号中间8位用*代替注意直辖市如北京、上海的 city 和 province 名称相同区级代码精确到区如东城区 110101。如果传入的是完整身份证号data.idcard会保留前6位和后4位其余隐藏。6. 常见错误与排查HTTP状态码含义排查建议400Bad Request检查idcard参数格式必须为6位数字或15/18位身份证号不能包含空格或非数字字符401UnauthorizedAPI Key 缺失或错误。确认Authorization或X-API-Key头已正确传递且密钥有效403Forbidden可能因QPS超限每秒超过10次或IP被临时封禁。降低请求频率或联系服务提供方解封500Internal 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文档
原理与佳点集改进实践)
