最小可运行示例：身份证归属地查询接口调用全流程
适用场景在日常业务系统中经常需要根据用户输入的身份证号或其前6位快速获取其户籍所在地的省、市、区三级信息。典型场景包括快递物流平台自动填充收货地址的省市区下拉框用户准备时辅助校验身份信息真实性数据分析任务中对匿名化身份证数据进行地域分类表单填写时提供智能提示减少用户手动输入与调用完整的三级地址库相比通过身份证归属地查询接口可以避免维护本地地区码表且接口会自动处理身份证脱敏回显提升数据安全性。接口能力边界本接口根据身份证号的前6位即地区代码返回对应的省级、地级、县级行政区划名称与代码。能力说明输入支持6位地区代码、15位身份证号、18位身份证号输出字段province省、city市、district区及各自代码、脱敏后的完整身份证号脱敏策略传入18位身份证号时返回将中间8位替换为*如110101************缓存机制省份数据从CDN拉取后本地缓存30天网关Redis缓存24小时减少重复查询QPS限制10次/秒超出会返回限流错误注意接口仅依据身份证号前6位进行地区映射不校验身份证号的合法性如校验位、出生日期等。如需完整校验应配合身份证验证专用接口。请求参数与鉴权Query参数参数名类型必填说明idcardstring是6位地区代码或15/18位身份证号示例110101Header参数参数名类型必填说明Authorizationstring是API鉴权密钥通常为Bearer token格式本接口使用X-API-Key方式传递实际调用时需将X-API-Key替换为你自己的密钥。为安全起见建议通过环境变量传递不要在代码中硬编码。最小可运行示例curl以下命令可直接在终端执行需提前设置环境变量APIZERO_API_KEYcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101如果未设置环境变量可临时替换为实际密钥注意安全curl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY_HERE \ https://v1.apizero.cn/api/idcard-region?idcard110101执行后预期得到如下JSON响应使用110101查询东城区{ code: 0, data: { province: { code: 110000, name: 北京市 }, city: { code: 110100, name: 北京市 }, district: { code: 110101, name: 东城区 }, idcard: 110101************ }, msg: 成功 }若传入完整18位身份证号如110101199001010011返回的idcard字段将脱敏为110101**********11仅保留前6位和后4位。代码接入示例Python对于本地测试或脚本集成可使用requests库编写调用import os import requests API_URL https://v1.apizero.cn/api/idcard-region API_KEY os.environ.get(APIZERO_API_KEY, YOUR_API_KEY) # 优先从环境变量读取 idcard 110101 # 支持6位或完整身份证 headers { X-API-Key: API_KEY } params { idcard: idcard } try: resp requests.get(API_URL, headersheaders, paramsparams, timeout5) resp.raise_for_status() data resp.json() if data.get(code) 0: region data[data] print(f省份: {region[province][name]} ({region[province][code]})) print(f城市: {region[city][name]} ({region[city][code]})) print(f区县: {region[district][name]} ({region[district][code]})) print(f脱敏后身份证: {region[idcard]}) else: print(f业务错误: {data.get(msg)}) except requests.exceptions.RequestException as e: print(f网络或HTTP错误: {e})运行前请确保已安装requests库pip install requests。该示例覆盖了常见错误处理网络异常、业务码非零。返回字段解读响应为JSON对象外层包含三个字段字段类型说明codeint业务状态码0表示成功非零表示错误msgstring状态描述成功时为成功dataobject数据主体成功时存在data对象结构字段类型说明provinceobject省级信息含code6位行政区划代码和namecityobject地级信息同上districtobject区县级信息同上若查询的6位代码只对应到地级该字段可能为nullidcardstring脱敏后的身份证号若传入完整身份证若传入6位代码则原样返回注意直辖市如北京的city和province名称相同均为“北京市”。部分地区的district可能为空如传入仅覆盖到地级市的6位代码。常见错误处理HTTP状态码业务码含义排查方向400-1请求参数错误idcard为空或格式不符合6位/15位/18位规则检查传入的身份证号长度和字符组成401-2鉴权失败X-API-Key缺失或无效重新获取密钥确认Header名称与值正确429-3请求频率超限10 QPS加入本地限流或使用退避重试策略500-9服务器内部错误等待后重试若持续异常请联系技术支持其他4xx-见响应的msg字段按照提示修正请求建议在客户端统一处理当code ! 0时打印msg并记录日志避免直接向用户暴露原始错误。工程化注意事项1. 缓存策略接口服务端已进行多层缓存CDN Redis但客户端也可根据业务需要做本地二级缓存。例如将常用6位地区代码与归属地映射存入内存字典可设置过期时间24小时减少重复网络调用。由于地区代码变更频率极低通常数年一次缓存有效期可设为30天。2. 批量查询优化接口单次只能查询一个身份证号。如果需要批量处理如导入历史数据建议并发控制使用线程池或异步协程并发数不超过QPS限制10个/秒配合令牌桶进行节流。错误重试对429或5xx错误采用指数退避如1s、2s、4s重试3次。3. 参数校验前置在调用接口前客户端应校验idcard参数格式6位地区代码必须全数字长度6。15位身份证前6位为地区其余为出生日期和顺序码。18位身份证前6位为地区后跟8位出生日期、3位顺序码和1位校验码。正则示例Pythonimport re def is_valid_idcard_prefix(s: str) - bool: # 简单检查全数字且长度匹配 return bool(re.fullmatch(r\d{6}|\d{15}|\d{18}, s))4. 密钥安全管理严禁在代码仓库中明文提交X-API-Key。推荐做法使用环境变量如os.getenv(APIZERO_API_KEY)配合.env文件非版本控制和python-dotenv生产环境使用密钥管理服务如Vault、AWS Secrets Manager5. 接口降级方案如果接口临时不可用应用程序应具备降级逻辑显示“地区信息暂不可用”或提示用户手动输入。业务允许时可展示本地缓存的旧数据需注明更新时间。参考文档身份证归属地查询接口文档原始Markdown文档正文至此结束共计约1680字
)
