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

2026/7/17 10:01:10

适用场景

在用户准备、风控校验、物流地址填充等真实业务中，通过身份证号前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。
异步调用：对于非主链路业务（如用户准备后补充信息），可采用消息队列异步查询，不阻塞主流程。