开发者 / Agent
API 文档
报告页上看到的一切都能用 JSON 拿到：一次调用返回评分、代理 / VPN / Tor 判定、黑名单与滥用记录、 分场景适用性、逐项扣分依据，以及这份数据的边界。无需 API key。 机器可读的描述在 /openapi.json，给模型看的站点说明在 /llms.txt。
端点
两个接口
- GET /api/lookup?ip={ip}
- 整份报告。
ip支持 IPv4 / IPv6； 加refresh=1忽略缓存与历史库强制重查。 - GET /api/myip?format=text
- 回显调用方的公网 IP。不带
format时返回{ ip }。
配额
谁能调、调多少
- 已收录的 IP：直接返回库中报告，不消耗数据源配额，任何客户端可调。 站内已有近万份报告，热门地址基本都在。
- 未收录的 IP：会真实查询各数据源。脚本与 Agent 每个来源 IP 每天可免验证查询 5 次（全站每日另有总量上限），剩余次数在响应头
x-open-budget-remaining。 额度用完返回 403，code = verification_required， 并附reportUrl：在浏览器打开它完成一次检测，这个 IP 就进库了，之后可直接调用。 - 限流：普通查询 30 次 / 分钟；首次查询新 IP 10 次 / 分钟；refresh 5 次 / 分钟。超出返回 429。
- 缓存：库中报告带
stale标记， 超过陈旧阈值的建议 refresh；IP 的性质本来就很少变，多数情况下直接用即可。
字段
响应里有什么
| ip / version | 规范化后的地址与协议版本（4 / 6） |
|---|---|
| queriedAt | 报告生成时间。source 为 store 时是当初检测的时间，配合 stale 判断要不要 refresh |
| source | fresh 实时查询 · cache 进程缓存 · store 历史库 |
| usageType | residential · mobile · business · hosting · education · government · unknown |
| nativeType | native 原生 · broadcast 广播（注册地与使用地不一致）· unknown |
| flags | isProxy / isVpn / isTor / isHosting / isMobile / isRelay / isBogon / isSearchEngineBot |
| flagAgreement | 每个判定位有几家数据源一致确认。单源判定在评分里按半数计权 |
| vpnOperator | 已知商业 VPN 的运营商：name、anonymity、popularity、protocols、logging、freeAccess。没有则为 null |
| risk.purity | 纯净度 0-100，越高越干净 |
| risk.level / label / verdict | 六档：pristine 极佳 · clean 纯净 · neutral 一般 · suspicious 可疑 · risky 高风险 · dangerous 极高风险 |
| risk.confidence | low / medium / high —— 参与评分的数据源覆盖度。分数与置信度分开看：同样 85 分，两家源和八家源的把握不同 |
| risk.factors[] | 每一分的来源：label、category、points（正数扣分、负数加回）、detail、floor（一票否决的风险下限） |
| scenarios[] | 分场景适用性：ai · social · streaming · gaming · ecommerce · email，各有 score、level、levelLabel 与 reason |
| blocklists[] | 各公开黑名单：listed 命中；benign 命中但不构成风险（如 PBL 住宅段声明）；unavailable 本次不可用、命中与否未知 |
| abuse[] | 滥用举报（score、reports）与攻击行为记录（attacks.byType：撞库、批量注册、漏洞扫描等） |
| exposure / sharing | 网络暴露面（开放端口、已知漏洞）与共享程度（同地址 / 同网段观测到的设备数） |
| sources[] | 每个数据源本次的状态：ok、ms、error、skipped。失败不等于未命中 |
| feedback | 实测反馈：正在用这个 IP 的访客给各场景打的真实使用体验分（1-5，5 最好）。按场景给出 count 与 average，某场景满 3 人才出现。它独立于评分，是评分之外的参照 |
| unknowns[] | 仅凭 IP 无法判断的事项，见下文 |
| reportUrl | 这份报告的网页地址，引用结论时请附上 |
边界
这份数据看不到什么
所有结论基于查询时刻的公开与合作数据源，不构成账号安全或平台准入的保证
平台内部的风控标签
各平台有自己的 IP 信誉库与封禁记录，不对外公开。公开数据源没命中，不等于平台那边没有记录。
是否真正独享
共享程度只是同网段观测到的设备数，看不出同一出口此刻还有谁在用、在做什么。
这个 IP 关联过哪些账号
账号与 IP 的关联关系只存在于各平台内部，前人在这个 IP 上被封过的账号我们看不到。
设备、浏览器与操作行为
风控看的是 IP + 设备指纹 + 行为节奏的组合。IP 再干净，指纹与行为异常照样会被拦。
账号资料与 IP 是否自洽
注册国家、手机号、支付方式、语言时区与 IP 归属地不一致时，平台会额外核验，这与 IP 纯净度无关。
示例
三种调用方式
curl
curl -s "https://ipure.dev/api/lookup?ip=8.8.8.8" | jq '.risk.purity, .risk.verdict, [.scenarios[] | {id, levelLabel}]'Python
import requests
r = requests.get("https://ipure.dev/api/lookup", params={"ip": "8.8.8.8"}, timeout=30)
r.raise_for_status()
report = r.json()
print(report["risk"]["purity"], report["risk"]["verdict"])
for s in report["scenarios"]:
print(s["label"], s["score"], s["levelLabel"], "—", s["reason"])
print("无法判断:", [u["label"] for u in report["unknowns"]])TypeScript
const res = await fetch("https://ipure.dev/api/lookup?ip=8.8.8.8");
if (!res.ok) throw new Error(`IPure ${res.status}`);
const report = await res.json();
const ai = report.scenarios.find((s: { id: string }) => s.id === "ai");
console.log(report.risk.purity, ai?.levelLabel, report.vpnOperator?.name ?? "非已知商业 VPN");给 Agent
何时调用，何时不调
适合调用
用户问「这个 IP 干不干净」「能不能拿去登 ChatGPT / 注册 X / 开亚马逊店 / 看 Netflix」「是不是 VPN 或机房 IP」 「为什么老被风控」；需要在执行网络任务前判断当前出口 IP 是否合适；要在多个候选 IP 之间比较。
不该调用
DNS 配置与网站部署；网络连通性故障排查；需要目标平台内部风控数据才能回答的问题。 引用结论时请连同 unknowns 一起给出，不要把「未发现风险」说成「安全」。