API 使用说明 | IP查询工具

URL 直接查询

拼接 URL 即可直接查询指定 IP, 支持 IPv4 与 IPv6:

IPv4 示例: https://ip.czl.net/8.8.8.8

IPv6 示例: https://ip.czl.net/2001:4860:4860::8888

该方式返回网页, 适合书签收藏或分享; 程序化取数据请用下方 /api 接口。

纯文本查本机 IP

GET/me纯文本返回调用方出口 IP, 适合 curl / 脚本

响应为 text/plain, 仅含 IP 地址 (末尾带换行), 不走统一 JSON 结构。返回 IPv4 还是 IPv6 取决于请求使用的协议栈, 可用 curl -4 / curl -6 指定。

$ curl https://ip.czl.net/me
203.0.113.7

$ curl -6 https://ip.czl.net/me
2001:db8::1

统一响应格式

所有 /api 接口返回统一结构, 以 code 判定成败 (200 为成功), 不要仅凭 HTTP 状态码判断:

{
  "code": 200,
  "data": { /* 各接口的业务数据, 见下文 */ },
  "msg": "success"
}

失败时 code 为对应 HTTP 状态码 (如 400 / 404 / 429 / 500), data 为 null, msg 为中文错误说明。接口支持 CORS 跨域, 可在前端直接调用。

查询 IP 信息

GET/api/query查询调用方自身出口 IP

POST/api/query查询指定 IP (body 省略或 ip 为空时回退为调用方 IP)

请求体 (POST)

{ "ip": "8.8.8.8" }

响应示例

{
  "code": 200,
  "data": {
    "ip": "8.8.8.8",
    "ipVersion": "IPv4",
    "country": "美国",
    "countryCode": "US",
    "province": "加利福尼亚州",
    "city": "山景城",
    "isp": "Google LLC",
    "as": { "number": 15169, "name": "GOOGLE", "info": "Google LLC" },
    "addr": "美国 加利福尼亚州 山景城",
    "regions": ["美国", "加利福尼亚州", "山景城"],
    "location": { "latitude": 37.4056, "longitude": -122.0775, "accuracy_radius": 1000 },
    "timezone": "America/Los_Angeles",
    "postal": "94043",
    "registered_country": { "code": "US", "name": "美国" },
    "accuracy": "medium",
    "source": "MaxMind"
  },
  "msg": "success"
}

主要字段

字段	说明
ip / ipVersion	IP 地址与版本 (IPv4 / IPv6)
country / countryCode	国家名与 ISO 国家码
province / city / district	省 / 市 / 区县 (及对应 *Code, 按数据可得性出现)
isp / net	运营商与网络类型
as	自治系统对象: number (ASN 号) / name / info
addr / regions / regions_short	拼接后的完整地址串与省市区数组
location	经纬度对象: latitude / longitude / accuracy_radius
timezone / postal	时区与邮编
registered_country	IP 注册国家对象: code / name
accuracy / source	精度 (high/medium/low) 与数据来源 (MaxMind/GeoCN)
proxyDetection / meituan / ncgy	代理检测 / 详细地址补全 / ip.nc.gy 补充, 按是否补全出现 (可选嵌套对象)

可选字段在无数据时省略, 消费方按开放式对象处理, 缺字段不应报错。

BGP 邻居查询

GET/api/bgp/:asn查某 ASN 的上下游邻居 (数据源 RIPEstat)

路径参数 asn 为 1 ~ 4294967295 的整数, 例如 /api/bgp/13335。

响应示例

{
  "code": 200,
  "data": {
    "centerAsn": 13335,
    "centerName": "CLOUDFLARENET",
    "upstreams":   [{ "asn": 174, "type": "left",  "power": 120, "v4Peer": 300, "v6Peer": 120 }],
    "downstreams": [{ "asn": 999, "type": "right", "power": 10,  "v4Peer": 40,  "v6Peer": 15  }],
    "uncertain":   [],
    "allPeers":    [ /* 上述全部邻居的合集 */ ]
  },
  "msg": "success"
}

字段	说明
centerAsn / centerName	被查 ASN 号与持有者名称
upstreams / downstreams / uncertain	上游 / 下游 / 不确定邻居数组
allPeers	全部邻居合集
邻居.type	left = 上游, right = 下游, uncertain = 不确定
邻居.power / v4Peer / v6Peer	观测路径数, 观测到该邻居的 IPv4 / IPv6 RIS 节点数

代理检测

GET/api/proxy-detection

POST/api/proxy-detectionbody 需 { "enableProxyDetection": true }

检测调用方自身是否使用代理 / VPN。

响应示例

{
  "code": 200,
  "data": {
    "isUsingProxy": false,
    "proxyType": "",
    "confidence": 0,
    "headerIP": "1.2.3.4",
    "domesticIP": null,
    "foreignIP": null,
    "errors": [],
    "detectionTime": 1721200000
  },
  "msg": "success"
}

字段	说明
isUsingProxy	是否判定为使用代理
proxyType / confidence	代理类型与置信度 (0 ~ 1)
headerIP / domesticIP / foreignIP	请求头 IP 与国内/国外解析出的 IP (可能为 null)
errors / detectionTime	检测过程错误列表与检测时间戳

详细地址补全

POST/api/meituan中国大陆街道级地址

以 IP 的经纬度为输入, 经美团逆地理接口补全区域名与详细地址, 属按需调用, 不会出现在 /api/query 的默认响应里。

仅支持中国大陆公网 IP。境外 IP、私有地址、缺少经纬度、美团未收录该坐标, 均返回 400; 上游不可用返回 503。

请求体

{ "ip": "114.114.114.114" }

响应

结构与 /api/query 完全一致, 额外带 meituan 对象, 并把 accuracy 提升为 high; source 仍是原始数据源。

字段	说明
meituan.areaName / detail	区域名 (如王府井/东单) 与详细地址
meituan.openCityName / cityPinyin	开放城市名与城市拼音
meituan.dpCityId / area / parentArea	美团城市 ID / 区域编号 / 父区域
meituan.isForeign	美团侧的境外判定

限速说明

按客户端 IP 独立计算, 每个接口按分钟窗口限流:

字段	说明
/api/query	180 次 / 分钟
/api/bgp/*	20 次 / 分钟
/api/proxy-detection	10 次 / 分钟
/me 及其他接口	100 次 / 分钟

响应头

字段	说明
X-RateLimit-Limit	窗口内限制总数
X-RateLimit-Remaining	剩余可用次数
X-RateLimit-Reset	限制重置时间
Retry-After	超限时返回, 建议等待的秒数

超限响应 (429)

{
  "code": 429,
  "data": null,
  "msg": "请求过于频繁，请稍后重试",
  "retryAfter": 46
}

• 批量查询请自行做本地缓存 / 去重 / 节流, 不要逐条裸打

• 命中 429 遵循 Retry-After 退避重试, 不立即重打

• 可通过 X-RateLimit-Remaining 实时监控剩余次数

数据来源

整合多个数据源, 通过智能合并算法提供尽可能准确的 IP 地理位置信息。

MaxMind — 主数据源

GeoLite2-City: 城市级定位 (国家、省份、城市、经纬度、时区)
GeoLite2-ASN: 自治系统号与 ISP 信息

GeoCN — 中国区增强

中国大陆 IP 提供更精准的省 / 市 / 区县级定位
含 86 个中国 ASN → 运营商映射 (电信、联通、移动等)

OpenProxyDB ↗ — 代理与特征识别

代理 / VPN / Tor / Hosting / CDN / 校园网 / 匿名网络检测
由 NetworkCats 社区维护, 部分 GeoIP 数据基于 DB-IP

回退机制

本地 MMDB 无结果时, 依次尝试: MMDB 本地库 → MaxMind Web API → IPInfo.io API。以 MaxMind 为基础, GeoCN 对中国 IP 增强补充; 基于准确度与来源计算智能缓存 TTL (5 分钟 ~ 3.6 小时)。

问题反馈

使用中遇到问题或有改进建议, 欢迎反馈:

前往论坛留言反馈 ↗

反馈错误时请提供具体 IP 地址或操作步骤, 便于定位。