API Docs

• 返回访客公网 IP（Public Egress IP）。
• 响应格式为纯文本（text/plain），不包含 JSON 包装。
• 支持 IPv4 IPv6。
• Dual Stack 指同一入口可同时响应 IPv4 与 IPv6，请求最终返回值取决于客户端实际连通通道。

• Returns the visitor public IP address.
• Response format is plain text (text/plain) without JSON envelope.
• Supports IPv4 and IPv6.
• Dual Stack means one endpoint serves both IPv4 and IPv6; output depends on the client's active network path.

• https://ipx.ee (IPv4 + IPv6 Dual Stack)
• https://ipx.ee (IPv4 only)
• https://ipx.ee (IPv6 only)

curl 示例

curl ipx.ee
curl -4 ipx.ee
curl -6 ipx.ee
curl -4 ipx.ee
curl -6 ipx.ee

Linux shell 示例（变量赋值）

#!/bin/sh
ip="$(curl -fsS https://ipx.ee)"
echo "Current public IP: ${ip}"

Node.js

const res = await fetch('https://ipx.ee');
const ip = (await res.text()).trim();
console.log(ip);

Python

import requests
ip = requests.get('https://ipx.ee', timeout=5).text.strip()
print(ip)

PHP

<?php
$ip = trim(file_get_contents('https://ipx.ee'));
echo $ip;

• 返回值是访问者当前公网出口 IP，不是内网地址。
• 若客户端启用 VPN Proxy，返回对应出口节点 IP。
• 双栈环境中，结果取决于客户端实际请求走的 IPv4 或 IPv6 通道。
• 不建议对结果做长期缓存，建议按业务实时获取。

• DDNS 自动更新
• 服务器公网 IP 检测
• IPv6 连通性测试
• 自动防火墙白名单
• CI CD 出口确认

• 输出结构化 JSON，适合前端脚本直接消费。
• 成功响应仅包含一个字段：ip。
• 支持 callback 参数返回 JSONP。
• 返回值为访问者当前公网出口 IP。

• https://ipx.ee/api/jsonip (JSON)
• https://ipx.ee/api/jsonip?callback=getip (JSONP)

• 成功 JSON 响应固定为 {\"ip\":\"...\"}，不附加其它元字段。
• 未传 callback 时返回 application/json。
• 传 callback 时返回 application/javascript。
• callback 仅允许合法函数名。

• 用于获取 IP 地理位置与网络归属信息。
• 响应格式为 JSON（application/json）。
• 输出结构固定为 5 个顶层字段：ip、geo、network、flags、meta。
• 支持 IPv4 IPv6 Domain。
• 传入域名时，服务会先执行 DNS 解析，再返回解析到的 IP 信息。

GET https://ipx.ee/api/geoip/{target}

• {target} 支持 IPv4、IPv6 或域名 Domain。
• IPv4 示例：8.8.8.8
• IPv6 示例：2001:4860:4860::8888
• Domain 示例：example.com

• ip：目标 IP（由上游 query 映射而来）。
• geo：地理信息分组，包含 continent/country/country_code/region/region_name/city/zip/latitude/longitude/timezone。
• network：网络信息分组，包含 reverse/isp/org/as_name/asn/as_org。
• flags：属性标记分组，包含 hosting/proxy/mobile。
• meta：请求元信息分组，包含 source/requested_at/cached/cache_group/cache_saved_at/ok。
• 当 meta.ok=false 时，返回 meta.error.code 与 meta.error.message。

• 地理位置为 IP 归属地推断，不是精确定位。
• 域名查询会先进行 DNS 解析。
• 建议缓存 GeoIP 数据 7-30 天。
• 返回 Content-Type: application/json。
• 上游 status 字段不会透出，错误统一在 meta.error 返回。

• 访客地理展示
• 统计分析
• 基础风控
• 日志增强

为保证服务稳定性与公平使用，IP 与 GeoIP REST API 实施频率限制。

To ensure service stability and fair usage, rate limits are enforced on IP and GeoIP REST APIs.

• Plain Text IP: 60 requests / minute / IP
• GeoIP API: 30 requests / minute / IP

限流基于客户端公网 IP 计算。

Limits are enforced per client public IP.

当请求超过限制时，服务返回 HTTP 429 Too Many Requests。

HTTP 429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down."
  }
}

• X-RateLimit-Limit：当前窗口允许的请求总量。
• X-RateLimit-Remaining：当前窗口剩余可用请求数。
• X-RateLimit-Reset：限流窗口重置时间戳（或秒数）。

• 建议缓存结果，尤其是 GeoIP 数据。
• 禁止滥用、扫描与高频非正常请求。
• 违规访问可能触发临时或长期封禁。

错误返回采用 HTTP 状态码 + JSON 错误对象。

Error responses use HTTP status codes plus JSON error object.

400 示例

400 Example

{
  "error": {
    "code": "INVALID_TARGET",
    "message": "Target must be a valid IPv4, IPv6, or domain."
  }
}

429 示例

429 Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down."
  }
}

• Plain Text 接口发生错误时可仅返回 HTTP 状态码与纯文本。
• GeoIP 接口错误返回 JSON 错误对象。
• 错误响应不暴露内部实现细节。

• 检测入口：https://ipx.ee/outbound
• 覆盖项：主要出口 IPv4/IPv6、DNS 解析出口、WebRTC 候选、站点解析分布。
• 地图视图：将检测到的有效 IP 显示为地理分布点。

• Scope includes primary IPv4/IPv6 egress, DNS resolver egress, WebRTC candidates, and site resolution distribution.
• Detected routable IPs are visualized on the map.

1. 点击“开始检测”，系统并发执行 IPv4/IPv6、DNS 与 WebRTC 探测。
2. 收集到的 IP 会进入 GeoIP 归属解析与地图标注流程。
3. 表格按“出口相关结果 / 站点解析结果 / WebRTC 明细”分组呈现。

1. Click Start to run IPv4/IPv6, DNS, and WebRTC probes in parallel.
2. Detected IPs are enriched with geolocation and plotted on map.
3. Results are grouped into egress table, site DNS table, and WebRTC details.

• “主要出口 IPv4/IPv6”：当前浏览通道直接可见的公网出口。
• “DNS出口”：通过 DNS 相关探测得到的解析路径出口，不一定等于主要出口。
• “WebRTC”：浏览器 ICE 候选中的公网地址，用于辅助判断是否存在泄露风险。
• “站点解析”：目标网站 DNS 解析到的 IP 分布，用于判断地域与网络归属。

• 不同网络与浏览器策略会导致结果差异，建议多次检测交叉比对。
• WebRTC 结果受浏览器权限、扩展与策略影响，不保证每次都返回候选。
• DNS 出口结果可能呈现多地域节点，这是公共解析基础设施的正常表现。

• 页面入口：https://ipx.ee/lookup
• 查询模式：DNS Lookup、Reverse DNS Lookup、rDNS 网段扫描、IP 反查域名、rDNS 反查、CNAME 反查。
• 输出分为：页面结果视图 + 可选 JSON 接口输出（会员可见按钮）。

• 域名输入会自动归一化为小写；支持中文域名（自动转 Punycode）。
• 网段扫描仅支持 IPv4 CIDR，且存在最大范围限制（/20 或 /22）。
• rDNS/CNAME 模式支持左侧、中间、右侧匹配。

GET /lookup/{query}?dns_type=dns_lookup&output=json

GET /lookup/{query}?dns_type=rdns_pattern&dns_match=right&output=json

• 统一返回结构：ok / query / summary / data / meta。
• 空输入通常返回 400 INVALID_INPUT；查询失败返回 422 QUERY_FAILED。

• IP 反查域名与 rDNS 结果基于 PTR/本地索引，不等同于全量被动 DNS 数据。
• 如需更高覆盖率，建议持续运行网段扫描并定时导入被动 DNS 数据源。
• DNS 结果会受权威记录 TTL 与上游网络策略影响。

• 页面入口：https://ipx.ee/whois
• 支持域名、IP、ASN 的实时 RDAP 查询。
• 提供最近查询记录、状态徽章、Raw JSON 展示与复制下载能力。

• Domain：例如 example.com
• IPv4/IPv6：例如 8.8.8.8、2001:4860:4860::8888
• ASN：例如 AS15169（大小写不敏感，系统会规范化）。

Example query URL: https://ipx.ee/whois?whois_q=example.com

• 注册商/联系人/Whois 服务器/创建与更新和到期时间。
• 状态码（如 clientTransferProhibited）与 Nameservers。
• RDAP 对象类型、Handle、关联链接与原始 JSON。
• 年份徽章（注册年限）与目标类型徽章（Domain/IP/ASN）。

• Whois/RDAP 数据来自注册机构及镜像节点，更新时间可能存在延迟。
• 同一目标在不同区域节点可能返回字段差异，属正常现象。
• 建议结合历史记录与业务日志进行归属稳定性判断。

1. 先显示 Layer 1 主要字段（单列）。
2. 再显示“查看详细信息”折叠区（单列）。
3. 最后显示“高级信息”区；非会员展示锁定卡片与登录入口。

1. Show Layer 1 primary fields first (single column).
2. Then expandable details block (single column).
3. Advanced block stays last; guests see lock prompt and sign-in action.

• 字段为空统一显示 -（不渲染 null/undefined）。
• 会员字段对非会员不输出真实值，仅显示锁定说明。
• 后台可按 guest/member 分别开关字段，前端实时读取配置。

纯免费 API，无任何限制。适合开发测试、低频查询。

端点

• GET /api/v1/ - 查询访客 IP
• GET /api/v1/ip/{ip} - 查询指定 IP
• GET /api/v1/domain/{domain} - 查询域名

示例

curl https://ipx.ee/api/v1/ip/8.8.8.8

数据字段说明

响应示例（中国 IP）

{
  "ok": true,
  "ip": "223.5.5.5",
  "hostname": "public1.alidns.com",
  "ip_type": "IPv4",
  "geo": {
    "continent": "亚洲",
    "continent_code": "AS",
    "country": "中国",
    "country_code": "CN",
    "region": "浙江",
    "region_code": "ZJ",
    "city": "杭州",
    "district": "",
    "zip": "310000",
    "latitude": 30.287459,
    "longitude": 120.153576,
    "timezone": "Asia/Shanghai"
  },
  "network": {
    "asn": 45102,
    "asn_org": "Alibaba",
    "isp": "阿里"
  },
  "risk": {
    "is_mobile": false,
    "is_proxy": false,
    "is_datacenter": true
  },
  "meta": {
    "version": "v1",
    "source": "ipx.ee",
    "is_china_ip": true
  }
}

响应示例（国际 IP）

{
  "ok": true,
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "ip_type": "IPv4",
  "geo": {
    "continent": "North America",
    "continent_code": "NA",
    "country": "United States",
    "country_code": "US",
    "region": "Virginia",
    "city": "Ashburn",
    "zip": "20149",
    "latitude": 39.03,
    "longitude": -77.5,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 15169,
    "asn_org": "Google LLC",
    "isp": "Google LLC"
  },
  "risk": {
    "is_mobile": false,
    "is_proxy": false,
    "is_datacenter": true
  },
  "meta": {
    "version": "v1",
    "source": "ipx.ee",
    "is_china_ip": false
  }
}

高质量 API，使用付费数据源，必须携带 Token。

认证方式

Authorization: Bearer YOUR_TOKEN
# 或
X-API-Key: YOUR_TOKEN

Token 配额

响应头信息

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 2026-03-01T00:00:00+00:00
X-Token-Type: standard

端点

• GET /api/v2/ - 查询访客 IP
• GET /api/v2/ip/{ip} - 查询指定 IP
• GET /api/v2/domain/{domain} - 查询域名

示例

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://ipx.ee/api/v2/ip/8.8.8.8

数据字段说明

响应示例（中国 IP - 阿里云 DNS）

{
  "ok": true,
  "ip": "223.5.5.5",
  "hostname": "public1.alidns.com",
  "ip_type": "IPv4",
  "geo": {
    "continent": "亚洲",
    "continent_code": "AS",
    "country": "中国",
    "country_code": "CN",
    "region": "浙江",
    "region_code": "ZJ",
    "city": "杭州",
    "zip": "310000",
    "latitude": 30.287459,
    "longitude": 120.153576,
    "timezone": "Asia/Shanghai",
    "local_time": "2026-02-19T05:52:19+08:00"
  },
  "network": {
    "asn": 45102,
    "asn_organization": "Alibaba",
    "asn_domain": "alibabacloud.com",
    "asn_type": "business",
    "route": "223.5.5.0/24",
    "rir": "APNIC",
    "assigned_org": "Aliyun Computing Co., LTD"
  },
  "risk": {
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_mobile": false,
    "is_satellite": false,
    "is_bogon": false,
    "is_crawler": false,
    "is_abuser": false,
    "abuse_score": 0
  },
  "contacts": {
    "abuse_email": "didong.jc@alibaba-inc.com",
    "abuse_phone": "+86-000000000"
  },
  "meta": {
    "version": "v2",
    "source": "ipx.ee",
    "tier": "vip",
    "is_china_ip": true
  }
}

响应示例（国际 IP - Cloudflare）

{
  "ok": true,
  "ip": "1.1.1.1",
  "hostname": "one.one.one.one",
  "ip_type": "IPv4",
  "geo": {
    "continent": "Oceania",
    "continent_code": "OC",
    "country": "Australia",
    "country_code": "AU",
    "region": "Queensland",
    "region_code": "QLD",
    "city": "Brisbane",
    "zip": "4000",
    "latitude": -27.4679,
    "longitude": 153.0281,
    "timezone": "Australia/Brisbane",
    "local_time": "2026-02-19T07:52:02+10:00",
    "accuracy_radius": 50
  },
  "network": {
    "asn": 13335,
    "asn_organization": "Cloudflare",
    "asn_domain": "cloudflare.com",
    "asn_type": "business",
    "route": "1.1.1.0/24",
    "rir": "ARIN",
    "assigned_org": "APNIC Research and Development"
  },
  "risk": {
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_mobile": false,
    "is_satellite": false,
    "is_bogon": false,
    "is_crawler": false,
    "is_abuser": false,
    "abuse_score": null
  },
  "contacts": {
    "abuse_email": "helpdesk@apnic.net",
    "abuse_phone": "+61-7-38583100"
  },
  "meta": {
    "version": "v2",
    "source": "ipx.ee",
    "tier": "vip",
    "is_china_ip": false
  }
}

额度耗尽响应 (429)

{
  "ok": false,
  "error": "monthly quota exceeded. limit: 100, reset at: 2026-03-01...",
  "quota": {
    "limit": 100,
    "remaining": 0,
    "reset_at": "2026-03-01T00:00:00+00:00"
  }
}

数据合并策略

何时使用 V1？

• [适用] 开发测试阶段
• [适用] 低频查询（< 100次/月）
• [适用] 基础地理位置需求
• [适用] 预算有限的项目
• [适用] 中国 IP 需要详细地理信息（省市区、邮编、区号）

何时使用 V2？

• [适用] 生产环境
• [适用] 需要高精度数据
• [适用] 需要风险检测（VPN/代理/Tor/爬虫识别）
• [适用] 需要 ASN 详细信息（创建/更新时间、RIR）
• [适用] 需要 Abuse 联系方式
• [适用] 需要 IP 段路由信息

获取 Token

1. 注册 ipx.ee 账号
2. 进入「控制台」→「API Token」
3. 生成 Token（免费用户默认 100 次/月）
4. 观看广告可增加额度（+50 次）

输出格式统一说明

• V1 和 V2 均使用统一的嵌套格式输出
• 所有响应均包含 geo、network、risk 对象
• V2 额外包含 contacts 对象（Abuse 联系信息）
• JSON 中不暴露原始数据源名称（ip2region/ipapi/ipinfo 等）
• 统一标识为 meta.source: "ipx.ee" 和版本号

• 支持 Umami Cloud 和自托管版本。
• 自动获取过去 30 天的访问统计数据。
• 包含访客数、浏览量、会话数、跳出率等指标。
• 显示访客地区分布 Top 5。

• Supports both Umami Cloud and self-hosted versions.
• Automatically fetches statistics for the past 30 days.
• Includes visitors, pageviews, sessions, bounce rate metrics.
• Displays top 5 visitor countries/regions.

Umami 提供两种身份验证方式，取决于您使用的是 Umami Cloud 还是自托管版本。

Umami provides two authentication methods depending on whether you use Umami Cloud or self-hosted.

Authorization Header

Authorization: Bearer <token>

对于 Umami Cloud 用户，只需生成 API Key 即可。

1. 登录 Umami Cloud
2. 进入 Settings → API Keys
3. 点击 "Create API Key"
4. 复制生成的 API Key（格式：um_xxxxxxxxxxxxxxxx）

以下身份验证方法仅适用于自托管的 Umami。对于 Umami Cloud，您只需生成一个 API 密钥即可。

The following authentication methods only apply to self-hosted Umami. For Umami Cloud, you only need to generate an API key.

POST /api/auth/login

首先，您需要获取一个令牌才能发起 API 请求。向 /api/auth/login 端点发送 POST 请求：

Request

POST /api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response

{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
  "user": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "username": "admin",
    "role": "admin",
    "createdAt": "2000-00-00T00:00:00.000Z",
    "isAdmin": true
  }
}

保存令牌值，并在所有数据请求中添加 Authorization 请求头，值为 Bearer <token>。

curl 示例

curl https://{yourserver}/api/websites \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token>"

POST /api/auth/verify

您可以验证该令牌是否仍然有效。

Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "admin",
  "role": "admin",
  "createdAt": "2000-00-00T00:00:00.000Z",
  "isAdmin": true,
  "teams": []
}

Website ID 是 UUID 格式的字符串，用于标识您的网站。

1. 登录 Umami 后台
2. 点击您要查看的网站
3. 进入网站设置（Settings/设置）
4. 复制 Website ID（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

常用 API 端点

GET /api/websites/{id}/stats?startAt={ts}&endAt={ts}
→ 获取网站统计数据

GET /api/websites/{id}/pageviews?startAt={ts}&endAt={ts}&unit=day
→ 获取页面浏览量时间序列

GET /api/websites/{id}/metrics?startAt={ts}&endAt={ts}&type=country
→ 获取地区分布数据