适用场景在需要验证身份证真伪或辅助判断户籍信息的系统中签发机关通常是地方公安局名称是一项重要线索。例如用户准备时的身份辅助核验系统通过身份证号前 6 位快速获取签发机关与用户填写的签发机关进行比对辅助判断身份证是否合规。后台管理系统的数据补全已有身份证号但缺失签发机关字段可通过接口批量补全。合规审计场景在金融、政务等对客户身份信息要求严格的业务中签发机关可作为校验链的一环。该接口仅依赖身份证号前 6 位行政区划代码数据来源为本地静态数据不依赖外部实时请求因此响应速度极快且不会因上游变动产生延迟。接口能力边界在接入前需要明确以下约束查询依据只使用身份证号前 6 位行政区划代码忽略剩余位。因此同一个区划代码对应的签发机关是固定的无法区分同一区划下的不同户籍细分例如分局 vs 派出所。覆盖范围全国 3000 区划代码基本覆盖县级及以上行政区划。若传入的代码不在本地数据中例如测测试非法代码000000接口会返回空数据或错误码。QPS 限制默认 10 次/秒适合中小规模查询。若业务 QPS 超过此值需在客户端实现限流或请求队列。返回数据每个区划代码对应一个签发机关全称如“北京市公安局东城分局”数据公开且稳定不会频繁变更。请求参数与鉴权请求方式GET https://v1.apizero.cn/api/idcard-organQuery 参数参数是否必填类型说明示例值id是string6 位行政区划代码或完整身份证号接口自动截取前 6 位110101提示若传入完整身份证号18 位接口内部只提取前 6 位进行匹配后续位仅用于校验格式是否合规不影响查询结果。Header 鉴权参数是否必填类型说明Authorization是string格式Bearer API Key或X-API-Key: API Key实际请求时两种鉴权方式均可。以下示例使用X-API-Key方式curl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY \ https://v1.apizero.cn/api/idcard-organ?id110101请将YOUR_API_KEY替换为你自己的密钥。密钥通常可在 API 管理后台申请获取。代码接入示例1. curl 请求可复制# 1. 设置 API Key修改为你的真实密钥 API_KEY你的API密钥 # 2. 查询北京市东城区代码 110101 curl -sS \ -X GET \ -H X-API-Key: $API_KEY \ https://v1.apizero.cn/api/idcard-organ?id110101 # 预期返回JSON # { # code: 0, # data: { # code: 110101, # organization: 北京市公安局东城分局 # }, # msg: 成功 # }2. Python 示例requests 库import requests API_URL https://v1.apizero.cn/api/idcard-organ API_KEY 你的API密钥 # 请替换 def query_organ(id_code): headers { X-API-Key: API_KEY } params { id: id_code } resp requests.get(API_URL, headersheaders, paramsparams) if resp.status_code 200: data resp.json() if data[code] 0: return data[data] else: raise Exception(fAPI error: {data[msg]}) else: raise Exception(fHTTP {resp.status_code}) # 示例查询深圳市南山区代码 440305 result query_organ(440305) print(result) # 输出类似{code: 440305, organization: 深圳市公安局南山分局}3. Node.js 示例axiosconst axios require(axios); const API_URL https://v1.apizero.cn/api/idcard-organ; const API_KEY 你的API密钥; async function queryOrgan(idCode) { try { const response await axios.get(API_URL, { headers: { X-API-Key: API_KEY }, params: { id: idCode } }); if (response.data.code 0) { return response.data.data; } else { throw new Error(response.data.msg); } } catch (error) { console.error(查询失败:, error.message); return null; } } // 调用 queryOrgan(110101).then(data console.log(data));返回值解读成功时的响应 JSON 结构如下{ code: 0, data: { code: 110101, organization: 北京市公安局东城分局 }, msg: 成功 }字段说明字段类型说明codenumber状态码0 表示成功非 0 表示错误data.codestring传入的 6 位行政区划代码原样返回data.organizationstring对应的签发机关全称msgstring状态说明文字错误码示例HTTP 状态码codemsg原因与处理2001001参数错误id 不能为空检查 id 参数是否缺失2001002参数错误id 格式不正确id 必须为 6 位数字或 18 位身份证号且仅包含数字2001003未找到该区划代码输入的区划代码未被收录或属于不存在的代码4012001授权失败请检查 API Key鉴权头缺失或密钥无效请检查 Authorization 或 X-API-Key4293001请求过于频繁请稍后重试超过 QPS 限制10次/秒建议加入重试逻辑实际 HTTP 状态码不一定等于 200建议以code字段判断业务结果。常见错误排查1. 请求返回 401 Unauthorized检查是否在 Header 中正确传入了X-API-Key或Authorization。API Key 可能已过期或权限不足重新申请或检查文档。2. 返回code: 1002格式错误确认id参数值为纯数字字符串且长度为 6 或 18。若使用完整身份证号注意最后一位可能是 X大写应保留 X不要转小写。3. 返回code: 1003未找到检查输入的前 6 位是否为合法的行政区划代码。例如110000北京市级可能不在区县列表中接口仅收录县级及以上具体签发机关。部分代码可能因行政区划调整而失效建议定期同步最新的区划表以官方民政部发布为准。4. 超时或连接失败确认网络环境可以访问v1.apizero.cn可能需要配置代理或白名单。设置合理的超时时间建议 5 秒以上避免因网络抖动导致失败。工程化注意事项缓存策略由于签发机关数据以区划代码为 key、数据变更频率极低建议对查询结果做本地缓存。例如import functools functools.lru_cache(maxsize1024) def get_organ_cached(id_code): return query_organ(id_code)这样同一个区划代码仅首次查询走网络后续直接从内存返回可大幅降低 QPS 占用。限流与重试QPS 上限为 10 次/秒若并发超过此值会收到 429。建议实现令牌桶或信号量控制。重试策略推荐指数退避例如初始等待 1 秒最多重试 3 次。区分错误类型仅对 429 和网络超时重试对 401、参数错误不重试。数据一致性与更新接口使用的本地数据基于最新行政区划表构建但撤县设区等调整发生后可能存在滞后。若业务要求极高准确率可搭配其他官方数据源交叉验证。安全性API Key 禁止硬编码在前端代码中应存放于后端环境变量或密钥管理服务。不要在日志中打印完整 API Key仅输出后几位用于调试。参考文档接口官方文档https://apizero.cn/aidocs/idcard-organ原始 Markdown 文档https://apizero.cn/aidocs/idcard-organ/raw.md
