适用场景从手动查站到自动化检测在网站上线、CDN加速、SSL证书部署或合规审计时确认一个域名的ICP备案状态是必不可少的环节。传统做法是访问工信部网站手动输入遇到海量域名时效率极低。开发者需要一种能够嵌入脚本、CI/CD流水线的编程化查询手段。典型场景包括自动化域名体检在内部运维平台中批量检测成千上万个域名是否已备案并将结果推送告警。CDN/安全网关前置检查在添加域名到分发节点前自动校验备案状态避免因未备案而被云厂商拦截。开发者本地调试在开发阶段随手验证一个新域名的备案情况无需打开浏览器。ICP备案查询API正为此类场景设计它接受域名或完整URL返回结构化备案信息无需处理验证码或反爬逻辑。接口能力边界在接入之前需要明确该API的几个关键特性特性说明自动域名清洗传入https://www.example.com/path?arg1或example.com:8080API会自动剥离协议、路径、端口、WWW前缀提取干净的主域名。缓存策略已备案域名24小时缓存变更频率低未备案域名1小时缓存避免新备案被长期误判。日常使用无需频繁调用。QPS限制5/s即每秒最多5次请求。对于批量任务需要控制并发。字段完整性is_filed布尔值区分是否已备案。已备案时返回6个字段备案号、网站名、主办单位、单位性质、审核时间、域名未备案或境外域名时这几个字段为空但is_filedfalse便于条件分支处理。鉴权方式支持匿名调用每日有次数限制以文档为准与Bearer Token鉴权。注意本API不提供“备案中”状态的中间态查询仅返回当前工信部数据中已存在或不存在的结果。请求参数与鉴权接口概览请求方法GET地址https://v1.apizero.cn/api/icp文档详见“参考文档”小节Query参数参数名必填类型示例说明domain是stringbaidu.com支持完整的URL、短域名、带端口/路径等API会清洗。Header参数参数名必填类型示例说明Authorization否stringBearer sk_live_xxxx鉴权Token匿名调用时可省略若传入则使用该Token。另外历史材料中提供的curl示例使用了X-API-Key头。实际测试中发现两种方式均可正常工作但推荐使用Authorization: Bearer ...作为标准做法。具体以文档为准。curl请求示例以下为两个可直接复制的命令替换$API_KEY为你的实际Key或匿名调用省略-H行。示例1匿名调用无需Keycurl -sS -X GET https://v1.apizero.cn/api/icp?domainbaidu.com示例2携带Bearer Tokencurl -sS -X GET \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ https://v1.apizero.cn/api/icp?domainbaidu.com示例3传入完整URL测试自动清洗curl -sS -X GET \ -H Authorization: Bearer $API_KEY \ https://v1.apizero.cn/api/icp?domainhttps://www.miit.gov.cn/abc?q1观察返回中的domain字段应被清洗为miit.gov.cn。代码接入Python与Node.js示例Python 3import requests import json API_URL https://v1.apizero.cn/api/icp API_KEY sk_live_your_key_here # 匿名调用时可设置为None def query_icp(domain: str): headers {} if API_KEY: headers[Authorization] fBearer {API_KEY} params {domain: domain} resp requests.get(API_URL, headersheaders, paramsparams, timeout10) resp.raise_for_status() data resp.json() if data.get(code) ! 0: raise Exception(fAPI error: {data.get(msg)}) return data[data] # 使用 result query_icp(example.com) print(json.dumps(result, ensure_asciiFalse, indent2))Node.js (axios)const axios require(axios); const API_URL https://v1.apizero.cn/api/icp; const API_KEY sk_live_your_key_here; // 可选 async function queryIcp(domain) { const headers {}; if (API_KEY) { headers[Authorization] Bearer ${API_KEY}; } const resp await axios.get(API_URL, { params: { domain }, headers, timeout: 10000 }); if (resp.data.code ! 0) { throw new Error(API error: ${resp.data.msg}); } return resp.data.data; } queryIcp(baidu.com).then(console.log).catch(console.error);返回值解读成功响应已备案{ code: 0, data: { audit_time: 2019-05-16 16:06:21, company_name: 北京百度网讯科技有限公司, company_type: 企业, domain: baidu.com, icp_code: 京ICP证030173号-1, is_filed: true, site_name: 百度一下你就知道 }, msg: 成功, request_id: abc123def456 }字段说明字段类型含义codeint0表示正常非0见错误处理msgstring中文描述request_idstring唯一请求ID便于排错data.is_filedboolean是否已备案true/falsedata.domainstring清洗后的域名data.icp_codestring备案号如“京ICP证030173号-1”data.site_namestring网站名称data.company_namestring主办单位名称data.company_typestring主办单位性质企业/个人/事业单位等data.audit_timestring审核通过时间格式YYYY-MM-DD HH:mm:ss未备案或境外域名{ code: 0, data: { audit_time: , company_name: , company_type: , domain: example-not-exist.com, icp_code: , is_filed: false, site_name: }, msg: 成功, request_id: xyz789 }is_filedfalse且其余字段均为空字符串。这不是错误开发时可通过if !result[is_filed]分支处理。常见错误与处理HTTP状态码codemsg原因与处理2001001参数错误domain参数为空或格式异常。检查请求参数。2001002域名清洗后为空传入的字符串无法提取有效域名例如纯IP、纯路径等。401-未授权鉴权失败Token不正确、过期或超出匿名次数。检查Authorization头。429-请求过于频繁超过QPS限制需要添加重试退避逻辑。500-服务端错误内部异常可等待后重试。最佳实践不要仅靠HTTP状态码判断应同时解析JSON中的code字段。另外对于未备案情况code0is_filedfalse应视为正常返回而非异常。工程化注意事项1. 批量查询的限速控制由于单接口QPS为5若需批量查询数百个域名建议通过队列或asyncio控制并发数不超过5。示例import time from concurrent.futures import ThreadPoolExecutor, as_completed def batch_query(domains, max_workers5): results {} with ThreadPoolExecutor(max_workersmax_workers) as executor: futures {executor.submit(query_icp, d): d for d in domains} for future in as_completed(futures): dom futures[future] try: results[dom] future.result() except Exception as e: results[dom] {error: str(e)} return results2. 缓存策略利用已备案结果有24小时缓存短时间内重复查询同一个已备案域名不会产生新请求。未备案域名缓存1小时。若你刚完成ICP备案提交至少等待1小时后再查询否则可能仍是未备案状态。在本地应用中也可增加一层内存缓存比如TTL 30分钟减少API调用。3. 错误重试与退避针对429和5xx错误实现指数退避重试如第一次等待1秒第二次2秒第三次4秒最大3次。注意不要对1001或1002重试因为那是参数问题。4. 域名清洗的验证如果你的输入本身已经是顶级域名如baidu.com清洗后不变。但如果从用户输入收集建议先自己做简单的合法性校验正则匹配域名格式再传给API避免空请求。参考文档ICP备案查询API文档原始接口描述Markdown本文中所有请求示例均基于真实API地址Key需替换为你自己的凭据。实际频率限制和缓存行为以最新文档为准。