DEVELOPER API / 03

让网络数据
可以被复用。

统一查询接口返回规范化字段、来源证据、缓存命中状态、生成时间和 request_id。

GET/api/v1/geoip

查询当前服务端出口 IP 的基础归属信息。

curl http://localhost:8787/api/v1/geoip

{ "data": { "ip": "…", "network": { "asn": "AS…" } }, "meta": { "cache": "MISS" } }

GET/api/v1/geoip/{ip}

查询指定 IPv4 或 IPv6。失败时返回结构化错误，不返回未验证的演示数据。

curl http://localhost:8787/api/v1/geoip/8.8.8.8

{ "data": { "location": { "country": "…" } }, "scores": { "state": "provisional" } }

GET/api/v1/lookup?q=

统一查询 IP、ASN、域名或 CIDR，并由服务端自动判断资源类型。

curl "http://localhost:8787/api/v1/lookup?q=AS15169"

{ "kind": "asn | domain | prefix | ip", "data": { "…": "normalized resource" } }

GET/api/v1/diagnostics/dns?domain=

通过配置的公共 DNS 解析器获取 A 记录，返回 resolver 与延迟信息。

curl "http://localhost:8787/api/v1/diagnostics/dns?domain=claude.ai"

{ "data": { "records": [] }, "meta": { "resolver": "Google Public DNS" } }

GET/api/v1/analytics/summary?days=30

内部统计接口，只返回脱敏后的类型、时间和数量聚合，需要配置 `IPAZ_ANALYTICS_TOKEN`。

curl -H "x-analytics-token: $IPAZ_ANALYTICS_TOKEN"

{ "data": { "total": 0, "distinct_queries": 0 }, "meta": { "mode": "aggregated_masked" } }

RESPONSE CONTRACT

一份稳定的响应协议

页面、CLI、浏览器扩展和后续团队服务都复用同一份 schema。`partial` 表示部分来源成功，`STALE` 表示使用仍在有效窗口内的旧缓存。

data.location国家、城市、坐标、时区

data.networkASN、组织、ISP、前缀

data.privacy代理、VPN、Tor、托管信号

data.scores分项评分与证据状态

meta.sources来源、延迟、字段与错误

meta.request_id排障与日志关联标识