ICP备案查询API参数详解与工程实践

适用场景ICP (Internet Content Provider) 备案是中国大陆境内网站运营的法定要求。开发者在以下场景中需要实时或批量查询域名备案状态合规审查在用户准备、广告投放、友链交换前验证目标域名是否已备案。内容聚合平台过滤未备案的第三方链接降低法律风险。运维监控定期扫描自有域名的备案状态防止因主体信息变更或注销导致的备案失效。前端展示在页面底部动态展示备案号需要根据备案状态决定显示内容。接口能力边界本接口sluicp提供基于域名的 ICP 备案信息查询其核心能力与约束如下能力说明域名清洗自动剥离https://、http://、路径、端口、www.例如https://www.baidu.com/abc与baidu.com等价备案判断is_filed布尔字段区分是否已备案未备案/境外/已注销均返回false不会报错缓存策略已备案域名缓存 24 小时备案信息变更极少未备案缓存 1 小时避免新备案被长期误判QPS 限制5 次/秒超过限制返回 429 状态码接口不承诺以下能力实时性不受缓存策略外的保证仅支持中国大陆工信部备案数据境外域名如.com但未在大陆备案返回is_filedfalse不返回 ICP 备案号的详细历史变更记录。请求参数与鉴权Query 参数参数名类型必填说明示例domainstring是要查询的域名支持完整 URL 输入自动清洗。推荐直接传入二级域名如example.combaidu.comdomain参数会自动执行以下清洗去除https://或http://协议前缀去除路径部分如/abc去除端口如:8080去除www.前缀。因此传入https://www.baidu.com/abc、baidu.com:443、m.baidu.com均等价于查询baidu.com。Header 参数鉴权参数名类型必填说明示例Authorizationstring否API Key 鉴权头格式Bearer sk_live_xxx。匿名调用时可省略每日 30 次额度Bearer sk_live_xxxxxxxxxxxxxx注意文档中提及的X-API-Key是早期版本当前推荐使用Authorization: Bearer方式。如果同时传入两种以Authorization为准。curl 接入示例以下 curl 命令演示携带鉴权的完整请求请将$APIZERO_API_KEY替换为实际密钥curl -sS \ -X GET \ -H Authorization: Bearer $APIZERO_API_KEY \ https://v1.apizero.cn/api/icp?domainbaidu.com若不需鉴权每日 30 次匿名额度可省略-H头curl -sS -X GET https://v1.apizero.cn/api/icp?domainbaidu.com代码封装Python对于需要工程集成的场景可使用以下 Python 模板import requests def query_icp(domain: str, api_key: str None) - dict: url https://v1.apizero.cn/api/icp params {domain: domain} headers {} if api_key: headers[Authorization] fBearer {api_key} resp requests.get(url, paramsparams, headersheaders, timeout10) resp.raise_for_status() return resp.json()返回值解读成功响应HTTP 200的 JSON 结构如下{ code: 0, data: { is_filed: true, domain: baidu.com, icp_code: 京ICP证030173号-1, site_name: 百度一下你就知道, company_name: 北京百度网讯科技有限公司, company_type: 企业, audit_time: 2019-05-16 16:06:21 }, msg: 成功, request_id: abc123def456 }字段详解字段类型含义备注codeint业务状态码0表示成功非0表示错误msgstring状态描述可据此判断错误类型request_idstring请求唯一标识用于排查问题时提供给平台dataobject备案数据核心负载对象├──is_filedboolean是否已备案true表示已备案false表示未备案或境外├──domainstring清洗后的域名始终返回标准二级域名如baidu.com├──icp_codestring备案许可证号仅当is_filedtrue时有效否则为空字符串├──site_namestring网站名称同上├──company_namestring主办单位名称个人备案时为主体名称企业备案为公司名├──company_typestring单位性质取值企业、个人、事业单位、政府机关、社会团体等└──audit_timestring审核通过时间格式YYYY-MM-DD HH:mm:ss未备案时的响应{ code: 0, data: { is_filed: false, domain: example-notexist.com, icp_code: , site_name: , company_name: , company_type: , audit_time: }, msg: 成功, request_id: xyz789abc }注意未备案不会返回错误码而是通过is_filedfalse与空字段表达。前端可以直接根据is_filed做条件渲染无需额外判断code。常见错误处理HTTP 状态码business codemsg 含义原因与解决方案400-1参数错误domain为空或格式完全非法如纯数字串。检查输入参数401-2鉴权失败Authorization头格式错误或密钥无效。检查是否以Bearer开头且密钥正确429-3请求过于频繁超过 5 QPS 限制。可增加退避逻辑指数退避或降低并发500-5内部错误服务端瞬时故障。间隔数秒后重试最佳实践建议将code和 HTTP 状态码结合判断。例如若 HTTP 200 但code ! 0仍视为业务错误工程化注意事项1. 缓存策略的自适应由于接口自身已对已备案域名缓存 24 小时未备案缓存 1 小时客户端无需再增加过长缓存层。但若需要秒级更新例如刚下单的域名备案通过可绕过缓存在domain后拼接随机参数需注意是否被清洗掉。实际上接口不提供强制刷新建议采用“先查、缓存、隔段时间再查”的轮询策略间隔至少 30 分钟避免被限流。2. 并发控制QPS 上限为 5若需批量查询例如一次检查 100 个域名应使用asyncio或线程池但限制每秒请求数 ≤ 4使用重试库如tenacity处理429错误。3. 域名清洗的双重保险尽管服务端会清洗domain但客户端最好也做一次基础校验去除空格、转小写、剔除非法字符。避免因 URL 中的#片段导致请求被截断。4. 错误日志与告警记录每次请求的request_id和返回的msg到日志对于连续 3 次500错误触发告警定期检查is_filed从true变false的域名可能是备案注销或信息变更。5. 国际化与境外域名处理该接口仅适合大陆备案查询。对于.com或.net等境外域名只要未在大陆备案is_filed均为false。若需区分“域名是否真实存在”与“备案情况”建议结合 DNS 查询或 WHOIS 接口。参考文档接口原始文档 — 包含最新参数变更和响应示例在线调试页面 — 可直接在浏览器中测试参数效果