开发者预览

IP Lens HTTP API

用于获取当前访客连接信息和进行轻量诊断的小型 JSON 端点。

获取当前 IP

GET /api/ip

返回到达服务器的地址、IP 版本、协议和 HTTPS 状态。添加 ?enrich=1 可请求大致的网络元数据。

curl "/api/ip"

查询 IP 地址

GET /api/ip-lookup?ip=8.8.8.8

仅接受公网 IPv4 或 IPv6 地址，并验证输入。每个调用方每分钟最多可发出 30 次请求。

查看网络迹象

GET /api/network-risk

返回缓存的网络元数据，以及对 VPN、代理或托管网络的保守判断。结果包含置信度，但不得视为证据。

健康检查与网络测速

GET /api/health 检查数据库和存储。GET /api/ping 用于延迟和抖动的抽样测量。

GET /api/speed?bytes=N 返回带有准确 Content-Length 的 application/octet-stream 二进制数据。数值会转换为整数并限制在 64 KB–8 MB（65,536–8,388,608 字节）之间；缺少值或值非数字时默认为 262,144 字节。每个滚动的 10 分钟窗口最多允许 60 次请求。快速连接上的一次完整测试最多可使用三个下载样本。

POST /api/speed-upload 仅接受 application/octet-stream，上限为 4 MB（4,194,304 字节），按有限大小的块读取，并返回 JSON {"ok":true,"bytes":N}。每个滚动的 10 分钟窗口最多允许 10 次请求。下载和上传使用由调用方 IP 派生的独立 HMAC 密钥。

方法错误返回 HTTP 405，不支持的上传内容类型返回 415，上传过大返回 413，超出请求限制返回 429。响应使用 Cache-Control: private, no-store, max-age=0 和 X-Content-Type-Options: nosniff。

每次由用户启动的自适应测试最多传输约 15.25 MiB，不含报头和 ping 响应。结果衡量到 IP Lens 服务器的路径，可能低于 ISP 宣传的速度，并非套餐速度认证。传输数据仅作临时处理；应用不会将数据或结果保存到数据库、访问分析、缓存或应用管理的日志中。仅为防止滥用而保存会到期的 HMAC 请求限制记录。

私有汇总统计

GET /api/stats/summary?days=30

使用 config.php 中的管理员用户名和密码进行 HTTP Basic Auth 身份验证。结果包括总浏览量、真人访客日数、浏览页面数、机器人浏览量及比例、机器人系列/类别，以及按日和按 URL 区分真人与机器人的统计。热门国家、浏览器、操作系统、设备、语言和来源仅统计真人流量。最近活动仅包含脱敏的访客/设备信息或规范化的机器人身份信息，不包含访问页面路径、完整 IP、完整 User-Agent 或访客密钥。

大致位置的天气

GET /api/weather?lang=zh

在服务器端启用并配置 WeatherAPI.com 后，返回 IP 大致位置的当前天气。

JavaScript 示例

fetch('/api/ip-lookup?ip=8.8.8.8')
  .then(function (response) { return response.json(); })
  .then(function (data) { console.log(data.ip, data.network); });