身份证归属地查询接口：从参数传送到数据落地的工程笔记
适用场景
在用户准备、风控校验、物流地址填充等真实业务中，通过身份证号前6位（地址码）快速获取省市区归属地是一项高频需求。该接口适用于：
- 会员准备预填充：用户输入身份证号后，自动回显户籍地址，减少手动输入。
- 异地登录风险判断：对比身份证归属地与当前IP地域，若差异过大可触发二次验证。
- 数据统计分析：对存量用户按省份做运营活动圈选。
- 物流地址校验：辅助判断用户填写的收货地址与户籍是否一致（不完全准确，但可作为参考）。
该接口仅解析地址码，不校验身份证号真伪，适合对实时性要求较高但无需公安核验的场景。
接口能力边界
- QPS限制：10次/秒，对于多数中小业务足够。若瞬时并发超过10，需在客户端或网关做限速。
- 数据缓存策略：服务端省份数据从CDN拉取后本地缓存30天，网关Redis缓存24小时。同一身份证前缀重复查询时大部分命中缓存，响应速度较快。但行政区划调整后最坏延迟30天更新，业务需容忍此窗口。
- 输入兼容：idcard参数支持6位区划代码、15位或18位身份证号。传入完整号时返回的
idcard字段自动脱敏（中间部分掩码）。 - 输出结构：返回包含
province、city、district三级对象的JSON，每一级有code和name字段。
请求参数与鉴权
接口为GET请求，需要两个参数：
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| idcard | Query | 是 | string | 6位区划代码或15/18位身份证号 |
| Authorization | Header | 是 | string | API密钥，通常以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?idcard=110101199001011234"如果仅测试6位区划代码，可简化为：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/idcard-region?idcard=110101"请将$APIZERO_API_KEY替换为实际API密钥。
代码接入示例
Python 示例（requests）
import 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, headers=headers, params=params, timeout=5) 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 示例（OkHttp）
import 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": "成功" }| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0成功，非0失败 |
| msg | string | 状态描述 |
| data | object | 数据主体 |
| data.province | object | 省份信息，含code和name |
| data.city | object | 城市信息（直辖市与省份同名） |
| data.district | object | 区县信息 |
| data.idcard | string | 脱敏后的身份证号（输入完整号时掩码，仅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前缀做内存缓存（如LRU），TTL设为30分钟，减少网络开销。注意：若行政区划调整，本地缓存可能导致数据陈旧，需结合业务容忍度。
- 数据更新延迟：民政部调整行政区划后，接口数据最晚30天更新。若业务对实时性要求极高，建议同时维护一份本地区划代码表作为降级方案，定期从官方渠道更新。
- 错误处理：为网络异常、HTTP非2xx、业务code非0均设计降级策略。例如使用缓存数据兜底或返回默认值。
- 日志与监控：记录请求参数（脱敏）、响应耗时、状态码，方便排查。避免记录完整API Key。
- 异步调用：对于非主链路业务（如用户准备后补充信息），可采用消息队列异步查询，不阻塞主流程。
参考文档
- API官方文档：https://apizero.cn/aidocs/idcard-region
- 原始Markdown文档：https://apizero.cn/aidocs/idcard-region/raw.md