适用场景在实名认证、户籍管理、金融风控等业务中经常需要验证用户提供的身份证号是否对应合法的签发机关。例如用户提交身份证号后系统可通过前 6 位行政区划代码获取对应的公安局名称从而辅助判断身份证真伪。该 API 专为此类场景设计覆盖全国 3000 区划代码且数据为本地静态构建非实时请求上游响应稳定、延迟可控。接口能力边界查询参数仅需身份证号的前 6 位或直接传入完整 18 位身份证号接口自动截取即可返回签发机关名称。数据覆盖涵盖全国所有区县级行政区划含直辖市、地级市、县、区、旗等不含港澳台地区。QPS 限制10 次/秒。若短时间超出限制服务端会返回 429 状态码建议客户端搭配指数退避重试。数据时效签发机关数据随行政区划调整不定期更新但非实时上游因此查询结果反映的是数据发布时的最新状态。如遇行政区划变更例如撤县设区数据可能存在短暂滞后。建议定期如每月刷新本地缓存。不承诺不可用于签发机关的唯一性判断一个区划可能对应多个分局但接口仅返回一个主要机构不可替代公安数据库进行最终核验。请求参数与鉴权Query 参数参数名类型是否必填说明示例值idstring是6 位行政区划代码或完整的 18 位身份证号接口自动取前 6 位110101Header 鉴权参数名类型是否必填说明Authorization或X-API-Keystring是API 密钥用于身份认证。两种方式任选其一建议统一使用Authorization。注意具体支持的 Header 名称以 API 文档最新说明为准。本文示例中使用X-API-Key演示实际使用时请替换为你的密钥。curl 请求示例以下是一个可直接复制的 curl 命令假设已将 API Key 保存在环境变量APIZERO_API_KEY中export APIZERO_API_KEYyour_api_key_here curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/idcard-organ?id110101若想测试完整身份证号自动截取可将id参数设为110101199001011234结果相同。返回 JSON 示例{ code: 0, data: { code: 110101, organization: 北京市公安局东城分局 }, msg: 成功 }代码接入以 Python 为例在工程化项目中通常需要对 API 封装为可重用的函数并加入异常处理、超时控制、重试等机制。下面展示一个基于requests库的 Python 实现import requests import time from requests.exceptions import RequestException def query_idcard_organ(id_code: str, api_key: str, timeout: int 3, max_retries: int 2) - dict: 查询身份证签发机关 :param id_code: 6 位区划代码或完整身份证号 :param api_key: API 密钥 :param timeout: 超时秒数 :param max_retries: 最大重试次数针对 429/5xx :return: 解析后的 data 字段含 code, organization url https://v1.apizero.cn/api/idcard-organ headers {X-API-Key: api_key} params {id: id_code} for attempt in range(1, max_retries 2): try: resp requests.get(url, headersheaders, paramsparams, timeouttimeout) resp.raise_for_status() # 触发 HTTPError json_data resp.json() if json_data.get(code) 0: return json_data[data] else: # 业务错误如参数无效 raise ValueError(f业务错误: {json_data.get(msg)}) except RequestException as e: # 网络或 HTTP 错误 if attempt max_retries: sleep_time 0.5 * (2 ** (attempt - 1)) # 线性/指数退避 time.sleep(sleep_time) continue else: raise except ValueError: raise使用方法api_key your_api_key_here result query_idcard_organ(110101, api_key) print(result[organization]) # 输出北京市公安局东城分局返回值解读接口返回格式固定顶层包含code、msg、data。字段类型说明codeint业务状态码0表示成功非0表示错误具体含义见下文错误部分msgstring状态描述如“成功”“参数错误”等data.codestring传入的 6 位区划代码原样返回data.organizationstring对应的签发机关全称如“北京市公安局东城分局”注意若传入的区划代码不存在例如999999data字段仍会返回code和organization: null且msg可能为“无匹配数据”。可通过organization是否为null判断是否有效。常见错误与处理HTTP 状态码业务 code含义处理建议2000成功正常解析2001001参数缺失或格式错误检查id参数长度是否为 6 且为数字2001002无对应数据区划代码不存在提示用户检查身份证号前 6 位2001003鉴权失败检查 API Key 是否有效或 Header 名是否正确401-未授权或无权限核对 API Key 并确认是否已激活429-请求频率超限客户端降速建议使用令牌桶或固定间隔控制 QPS ≤ 105xx-服务端临时错误应重试最多 3 次间隔递增避免无限积压工程化注意事项缓存设计因签发机关数据变化频率较低数月才可能有一次区划调整建议客户端建立本地缓存如 Redis以区划代码为 key设置 TTL 为 1 周1 个月。大幅降低 API 调用量也提升响应速度。前端校验在用户输入阶段即可检查身份证号前 6 位是否为合法数字截取后传给后端后端在调用 API 前同样做格式校验长度 6全数字。避免无效请求浪费配额。降级策略若 API 长时间不可用需要降级显示为“暂无法查询签发机关”并记录日志待恢复后异步补查。日志与监控对每次调用记录参数、耗时、返回码和 organization。统计“无匹配数据”比例是否异常升高可能暗示身份证号造假或行政区划已调整主动告警。并发控制QPS 上限为 10多线程调用时建议使用令牌桶Token Bucket算法限流避免被限速后大量重试导致雪崩。可使用 Semaphore 配合 sleep 精确控制调用间隔。参数编码若id中包含特殊字符通常不会务必进行 URL 编码。身份证号全数字一般无需编码但建议通过 requests 库的params参数传递由库自动处理。HTTP 长连接生产环境建议使用连接池如requests.Session或urllib3.PoolManager复用 TCP 连接以减少握手延迟。数据同步若业务对签发机关准确性极高可考虑额外接入行政区划更新订阅或定期如每月从 API 全量爬取所有区划代码对应的签发机关写入本地数据库进行离线校验而 API 仅作为兜底或增量更新来源。参考文档接口文档https://apizero.cn/aidocs/idcard-organ原始 Markdown 文档https://apizero.cn/aidocs/idcard-organ/raw.md
