API 文档

授权与 Token

请联系站点管理员申请 Token。Token 由管理员在服务端签发、配置并安全交付，没有公开自助签发接口。管理员撤销后重启应用生效。

每次请求设置 Authorization: Bearer YOUR_TOKEN，将 YOUR_TOKEN 替换为管理员交付的真实 Token。不要将 Token 写入前端代码、公开仓库或日志；只通过 HTTPS 使用。

参数

• GET /query：必填 ip，IPv4 或 IPv6 字面地址，不接受域名。
• GET /ping：必填 ip，仅公网 IPv4。
• GET /tcping：必填 ip（公网 IPv4）与 port（整数 1–65535）。
• Ping / TCPing 可选 count：整数 1–4，默认 4；可选 timeout：每次等待毫秒数，整数 1–1000，默认 1000。ICMP 受系统命令影响，实际等待粒度可能向上取整到秒。

调用示例

以下为可运行的请求格式，不是预先测得的结果。请先替换 YOUR_TOKEN。

curl --fail-with-body -H 'Authorization: Bearer YOUR_TOKEN' 'https://geo.zeroroute.net/query?ip=8.8.8.8'

curl --fail-with-body -H 'Authorization: Bearer YOUR_TOKEN' 'https://geo.zeroroute.net/ping?ip=1.1.1.1&count=1&timeout=1000'

curl --fail-with-body -H 'Authorization: Bearer YOUR_TOKEN' 'https://geo.zeroroute.net/tcping?ip=1.1.1.1&port=443&count=1&timeout=1000'

响应字段

• IP 查询固定返回：countryCode（字符串，国家代码）、countryName（字符串，中文国家名）、subdivisionName（字符串，中文地区名，可能回退到城市名）、asnNumber（整数 ASN）、asnName（字符串，ASN 组织名）。无记录或无中文名称的字段为 null，并非错误。
• 探测返回 type（ping 或 tcping）、ip（字符串）、sent / received（发送/成功次数，整数）、lossRate（失败比例，0–1），以及 minMs / avgMs / maxMs（毫秒数）。全部失败时三项延迟均为 null；TCPing 另返回整数 port。
• HTTP 200 只表示测试已执行，不保证目标连通。探测结果仅反映服务端到目标的链路。

错误与限制

API 错误格式：{"error":"说明"}。400 参数缺失、格式或范围错误；401 Token 缺失或无效；403 目标被网络策略拒绝；404 路径不存在或探测已关闭；405 方法不允许；414 URL 过长；503 探测并发已满、系统无 ping 命令或 ICMP 权限不足；500 内部错误。请按 HTTP 状态处理，不依赖错误文案。

禁止探测私网、回环、链路本地、保留地址；部署策略可以进一步限制公网地址。API 并发受服务端配置约束，不要无限重试。网页另有每应用实例匿名限频（429，多实例额度会累加）、请求体限制（413）、格式限制（415）和读取超时（408）；网页校验失败返回 HTML。