身份证归属地查询接口：从参数传送到数据落地的工程笔记

适用场景在用户准备、风控校验、物流地址填充等真实业务中通过身份证号前6位地址码快速获取省市区归属地是一项高频需求。该接口适用于会员准备预填充用户输入身份证号后自动回显户籍地址减少手动输入。异地登录风险判断对比身份证归属地与当前IP地域若差异过大可触发二次验证。数据统计分析对存量用户按省份做运营活动圈选。物流地址校验辅助判断用户填写的收货地址与户籍是否一致不完全准确但可作为参考。该接口仅解析地址码不校验身份证号真伪适合对实时性要求较高但无需公安核验的场景。接口能力边界QPS限制10次/秒对于多数中小业务足够。若瞬时并发超过10需在客户端或网关做限速。数据缓存策略服务端省份数据从CDN拉取后本地缓存30天网关Redis缓存24小时。同一身份证前缀重复查询时大部分命中缓存响应速度较快。但行政区划调整后最坏延迟30天更新业务需容忍此窗口。输入兼容idcard参数支持6位区划代码、15位或18位身份证号。传入完整号时返回的idcard字段自动脱敏中间部分掩码。输出结构返回包含province、city、district三级对象的JSON每一级有code和name字段。请求参数与鉴权接口为GET请求需要两个参数参数位置必填类型说明idcardQuery是string6位区划代码或15/18位身份证号AuthorizationHeader是stringAPI密钥通常以X-API-Key传递参考文档中使用X-API-Key作为Header名值从API管理平台获取。请务必将密钥存储在环境变量中避免硬编码。curl 请求示例以下命令查询完整身份证号110101199001011234的归属地API自动截取前6位并脱敏回显curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101199001011234如果仅测试6位区划代码可简化为curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101请将$APIZERO_API_KEY替换为实际API密钥。代码接入示例Python 示例requestsimport os import requests API_KEY os.environ.get(APIZERO_API_KEY, ) BASE_URL https://v1.apizero.cn/api/idcard-region def query_idcard_region(idcard: str) - dict: headers {X-API-Key: API_KEY} params {idcard: idcard} resp requests.get(BASE_URL, headersheaders, paramsparams, timeout5) resp.raise_for_status() return resp.json() if __name__ __main__: idcard 110101199001011234 result query_idcard_region(idcard) if result.get(code) 0: data result[data] province data[province][name] city data[city][name] district data[district][name] print(f省份{province}城市{city}区{district}) print(f脱敏身份证{data[idcard]}) else: print(f查询失败{result.get(msg)})Java 示例OkHttpimport okhttp3.OkHttpClient; import okhttp3.Request; import okhttp3.Response; import com.google.gson.JsonObject; import com.google.gson.JsonParser; public class IdcardRegionClient { private static final String API_KEY System.getenv(APIZERO_API_KEY); private static final String BASE_URL https://v1.apizero.cn/api/idcard-region; private static final OkHttpClient client new OkHttpClient(); public static void main(String[] args) throws Exception { String idcard 110101199001011234; String url BASE_URL ?idcard idcard; Request request new Request.Builder() .url(url) .header(X-API-Key, API_KEY) .get() .build(); try (Response response client.newCall(request).execute()) { String body response.body().string(); JsonObject json JsonParser.parseString(body).getAsJsonObject(); if (json.get(code).getAsInt() 0) { JsonObject data json.getAsJsonObject(data); String province data.getAsJsonObject(province).get(name).getAsString(); String city data.getAsJsonObject(city).get(name).getAsString(); String district data.getAsJsonObject(district).get(name).getAsString(); System.out.printf(省份: %s 城市: %s 区: %s%n, province, city, district); } else { System.out.println(错误: json.get(msg).getAsString()); } } } }响应字段解析成功时HTTP 200响应体示例{ code: 0, data: { province: {code: 110000, name: 北京市}, city: {code: 110100, name: 北京市}, district: {code: 110101, name: 东城区}, idcard: 110101************ }, msg: 成功 }字段类型说明codeint业务状态码0成功非0失败msgstring状态描述dataobject数据主体data.provinceobject省份信息含code和namedata.cityobject城市信息直辖市与省份同名data.districtobject区县信息data.idcardstring脱敏后的身份证号输入完整号时掩码仅6位时原样返回注意直辖市如北京、上海的city.name与province.name相同业务中可直接取province。常见错误与排查1. HTTP 401 Unauthorized原因API Key无效或缺失。检查确认Header中X-API-Key的值已正确设置且未过期。2. HTTP 400 Bad Request原因idcard参数格式错误如非数字、长度不对。检查确保传入6位数字区划代码或合法的15/18位身份证号末尾可为x/X。3. 业务code非0常见code如10001表示“参数错误”或“无数据”。参考msg字段提示。若idcard前缀对应不存在区划如测测试000000会返回无数据。4. 请求超时网络波动或服务端负载导致。建议设置5秒超时并实现指数退避重试最多2次。工程化注意事项API Key安全通过环境变量或配置中心注入切勿提交到代码库。定期轮换。客户端限流QPS上限10建议实现令牌桶算法避免因突发请求被限。本地缓存服务端已有缓存但客户端可对同一idcard前缀做内存缓存如LRUTTL设为30分钟减少网络开销。注意若行政区划调整本地缓存可能导致数据陈旧需结合业务容忍度。数据更新延迟民政部调整行政区划后接口数据最晚30天更新。若业务对实时性要求极高建议同时维护一份本地区划代码表作为降级方案定期从官方渠道更新。错误处理为网络异常、HTTP非2xx、业务code非0均设计降级策略。例如使用缓存数据兜底或返回默认值。日志与监控记录请求参数脱敏、响应耗时、状态码方便排查。避免记录完整API Key。异步调用对于非主链路业务如用户准备后补充信息可采用消息队列异步查询不阻塞主流程。参考文档API官方文档https://apizero.cn/aidocs/idcard-region原始Markdown文档https://apizero.cn/aidocs/idcard-region/raw.md