API 文档

IPTrace 的公开 REST 接口：IP 归属地与风险、BGP / ASN 拓扑、Whois、DNS、TCP 探测与 MMDB 数据集下载。所有接口的基址是 https://iptrace.net，响应统一是 UTF-8 JSON。

OpenAPI 描述文件 在控制台获取 API Key
接口目录
免鉴权快查 /api/ip /json /ip IP 查询 /api/ip/{target} /api/ip/{target}/sources /api/ip/batch Whois 与 DNS /api/whois/{target} /api/dns/{domain} /api/dns/{domain}/{type} 网络探测 /api/tcping/{target} BGP / ASN 数据 /api/as-profile/{asn} /api/as-topo/{asn} /api/prefix-upstreams /api/peeringdb/search /api/rdns /api/nodes 全球 DNS (DoH) /dns_global/api/regions /dns_global/api/query 账户 /api/user/me /api/user/usage 数据集下载 /api/datasets/{dataset}/info /api/datasets/{dataset}

基础信息

认证方式

方式 示例 说明
Authorization Authorization: Bearer YOUR_API_KEY 推荐。请求头方式，不会出现在访问日志与 Referer 里。
?token= ?token=YOUR_API_KEY 已弃用，仅为兼容旧客户端保留：Key 会写进服务器日志和浏览器历史，请尽快改用请求头。
匿名 — 不带 Key 也能调用标注「可选 API Key」的接口，按来源 IP 计入匿名限额：30 次/分钟、1000 次/天，批量上限 5，不扣点数。

注意：CORS 预检响应里虽然列出了 X-API-Key，但服务端目前不读这个请求头，请使用上面两种方式之一。

限流规则

套餐 每分钟请求 每日请求 批量上限 每月赠送点数 月费
匿名 30 1000 5 — —
免费版 (free) 120 10,000 10 1,000 免费
专业版 (pro) 600 100,000 100 50,000 $9.99
企业版 (enterprise) 3,000 不限 500 500,000 $49.99

每个响应都带 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset（Reset 是 Unix 时间戳）。超限返回 HTTP 429：每分钟限流与数据集配额会附 Retry-After（秒），每日配额用尽时不带 Retry-After，需要等到次日 00:00（服务器时区）。失败的调用不计入每日配额、也不扣点数。

计费点数

带 API Key 调用时按下表扣点数；匿名调用不扣点数（但受匿名限额约束）。点数不足返回 HTTP 402。

接口 点数
/api/ip/{target} 1
/api/ip/{target}/sources 2
/api/ip/batch 5
/api/whois/{target} 1
/api/dns/{domain} 1
/api/dns/{domain}/{type} 1
/api/tcping/{target} 1 × count（count 默认 4，钳制在 1–10）；走节点探测（country/node）时固定按 4 次计，即 4 点。
/api/user/me —
/api/user/usage —
/api/datasets/{dataset} 不扣点数，但每个数据集独立计 5 次/小时、30 次/天；中断的下载同样计数。

错误码

业务错误统一放在 body 的 code / msg 里，HTTP 状态多数仍是 200；只有基础设施级别的失败（401 / 402 / 429）才改 HTTP 状态。判断成功请一律看 code === 0。

HTTP 状态 业务码 说明
200 0 成功
200 400 参数错误：目标非法、缺少必填参数、批量超过 batch_limit 等
200 401 未认证：该接口必须带有效 API Key（注意 HTTP 状态仍是 200，错误在 body 的 code 里）
200 403 权限不足：套餐不够（数据集下载）或目标是私有/保留地址（tcping）
200 404 目标不存在或无法解析
402 402 点数不足，body 里 credits_required 给出本次需要的点数
429 429 触发限流（每分钟 / 每日 / 数据集配额）。每分钟限流与数据集配额带 Retry-After；每日配额用尽时不带 Retry-After，请等到次日 00:00（服务器时区）
504 504 检测节点未在规定时间内响应（仅节点探测）

免鉴权快查

这三个接口返回「调用方自己」的出口 IP 信息，不需要 API Key，按来源 IP 限流 60 次/分钟，已开启 CORS（Access-Control-Allow-Origin: *），可以直接在浏览器或 shell 里用。

GET /api/ip
无需 API Key

本机 IP 完整信息

返回结构与 GET /api/ip/{target} 完全一致（{code, data}），target 为调用方出口 IP。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
lang query string — zh 或 en，控制国家/地区/ISP 的语言，默认 zh

请求示例

curl 'https://iptrace.net/api/ip?lang=en'

响应示例

{
  "code": 0,
  "data": {
    "ip": "1.1.1.1",
    "version": 4,
    "country": "Australia",
    "country_code": "AU",
    "region": "New South Wales",
    "city": "Sydney",
    "latitude": -33.8688,
    "longitude": 151.209,
    "timezone": "Australia/Brisbane",
    "asn": 13335,
    "org": "CloudFlare Inc",
    "isp": "APNIC and CloudFlare DNS Resolver Project",
    "ip_type": "",
    "rdns": "",
    "as_domain": "cloudflare.com",
    "continent": "",
    "continent_code": "",
    "bgp": {
      "prefix": "1.1.1.0/24",
      "as": 13335,
      "as_name": "CLOUDFLARENET",
      "as_cc": "US",
      "allocation": "1.1.1.0/24",
      "allocation_cc": "AU",
      "rpki_status": "valid",
      "peers": [],
      "ix": []
    },
    "is_proxy": false,
    "proxy_type": "",
    "usage_type": "",
    "proxy_domain": "",
    "proxy_isp": "",
    "threat": "",
    "fraud_score": "",
    "last_seen": "",
    "provider": "",
    "location": "Australia New South Wales Sydney APNIC and CloudFlare DNS Resolver Project",
    "is_cloud_idc": true,
    "cloud_provider": "Cloud/IDC"
  }
}

响应字段

字段 类型 说明
code integer 0 表示成功，非 0 为业务错误码
data.ip string 查询到的 IP
data.version integer 4 或 6
data.country string 国家名（按 lang 本地化）
data.country_code string ISO 3166-1 alpha-2
data.region string 一级行政区
data.city string 城市
data.latitude / longitude number|null 经纬度
data.timezone string IANA 时区
data.asn integer|null 自治域号
data.org string ASN 注册机构
data.isp string ISP 名称
data.as_domain string AS 的主域名
data.continent / continent_code string 所属大洲
data.ip_type string IP 用途标签（识别为代理时才填）
data.rdns string 反向 DNS；本接口固定返回空串（解析耗时长，请用 /api/rdns）
data.location string 拼好的位置字符串，可直接展示
data.is_reserved boolean 保留/特殊用途地址时为 true，此时其余字段为空
data.bgp.prefix string|null 该 IP 所在的 BGP 通告前缀
data.bgp.as integer|null 起源 AS
data.bgp.as_name string|null 起源 AS 名称
data.bgp.as_cc string|null 起源 AS 注册国家
data.bgp.allocation string|null RIR 分配的母块
data.bgp.allocation_cc string|null 母块注册国家
data.bgp.rpki_status string|null RPKI 校验结果：valid / invalid / unknown
data.bgp.peers array 对等 AS 列表
data.bgp.ix array 所在 IX 列表
data.bgp.line string 线路识别结果（如 CN2 GIA），识别不到时不返回该键
data.is_proxy boolean 是否命中代理/VPN 库
data.proxy_type string 代理类型：VPN / TOR / DCH / PUB / WEB / SES …
data.usage_type string 用途分类：COM / ORG / ISP / MOB / DCH …
data.proxy_domain string 代理服务对应域名
data.proxy_isp string 代理服务对应 ISP
data.threat string 威胁标签
data.fraud_score string 欺诈评分
data.last_seen string 代理库最后观测时间
data.provider string 代理服务提供商
data.is_cloud_idc boolean 是否为云厂商/IDC 地址
data.cloud_provider string 云厂商名称
GET /json
无需 API Key

本机 IP 精简地理信息

扁平结构、无 code 包装，方便 shell/脚本直接取值。等价写法：GET /?format=json。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
lang query string — zh 或 en，控制国家/地区/ISP 的语言，默认 zh

请求示例

curl 'https://iptrace.net/json'

响应示例

{
  "ip": "203.0.113.45",
  "country": "美国",
  "country_code": "US",
  "region": "California",
  "city": "San Francisco",
  "isp": "Cloudflare",
  "asn": 13335,
  "org": "CloudFlare Inc",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles"
}

响应字段

字段 类型 说明
ip string 出口 IP
country string 国家名（按 lang 本地化）
country_code string ISO 3166-1 alpha-2 国家代码
region string 一级行政区
city string 城市
isp string ISP 名称
asn integer|null 自治域号
org string ASN 注册机构名
latitude number|null 纬度
longitude number|null 经度
timezone string IANA 时区
GET /ip
无需 API Key

纯文本返回本机 IP

text/plain，只有一行 IP 加换行，适合 $(curl -s https://iptrace.net/ip) 这样用。

限流：60 次/分钟（按来源 IP）
点数：—

请求示例

curl -s 'https://iptrace.net/ip'

响应示例

203.0.113.45

IP 查询

合并 8 个地理库 + IPNetDB BGP 表 + 代理/云识别的结果。匿名可调用（走匿名限额、不扣点数），带 API Key 时按套餐限额并扣除点数。

GET /api/ip/{target}
可选 API Key

单个 IP / 域名查询

target 可以是 IPv4、IPv6 或域名；域名会先解析成 IP 再查。

限流：按套餐（见下方限流表）
点数：1

请求参数

参数 位置 类型 必填 说明
target path string 必填 IPv4 / IPv6 / 域名，例如 1.1.1.1、2606:4700::1111、example.com
lang query string — zh 或 en，控制国家/地区/ISP 的语言，默认 zh

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/ip/1.1.1.1?lang=en'

响应示例

{
  "code": 0,
  "data": {
    "ip": "1.1.1.1",
    "version": 4,
    "country": "Australia",
    "country_code": "AU",
    "region": "New South Wales",
    "city": "Sydney",
    "latitude": -33.8688,
    "longitude": 151.209,
    "timezone": "Australia/Brisbane",
    "asn": 13335,
    "org": "CloudFlare Inc",
    "isp": "APNIC and CloudFlare DNS Resolver Project",
    "ip_type": "",
    "rdns": "",
    "as_domain": "cloudflare.com",
    "continent": "",
    "continent_code": "",
    "bgp": {
      "prefix": "1.1.1.0/24",
      "as": 13335,
      "as_name": "CLOUDFLARENET",
      "as_cc": "US",
      "allocation": "1.1.1.0/24",
      "allocation_cc": "AU",
      "rpki_status": "valid",
      "peers": [],
      "ix": []
    },
    "is_proxy": false,
    "proxy_type": "",
    "usage_type": "",
    "proxy_domain": "",
    "proxy_isp": "",
    "threat": "",
    "fraud_score": "",
    "last_seen": "",
    "provider": "",
    "location": "Australia New South Wales Sydney APNIC and CloudFlare DNS Resolver Project",
    "is_cloud_idc": true,
    "cloud_provider": "Cloud/IDC"
  }
}

响应字段

字段 类型 说明
code integer 0 表示成功，非 0 为业务错误码
data.ip string 查询到的 IP
data.version integer 4 或 6
data.country string 国家名（按 lang 本地化）
data.country_code string ISO 3166-1 alpha-2
data.region string 一级行政区
data.city string 城市
data.latitude / longitude number|null 经纬度
data.timezone string IANA 时区
data.asn integer|null 自治域号
data.org string ASN 注册机构
data.isp string ISP 名称
data.as_domain string AS 的主域名
data.continent / continent_code string 所属大洲
data.ip_type string IP 用途标签（识别为代理时才填）
data.rdns string 反向 DNS；本接口固定返回空串（解析耗时长，请用 /api/rdns）
data.location string 拼好的位置字符串，可直接展示
data.is_reserved boolean 保留/特殊用途地址时为 true，此时其余字段为空
data.bgp.prefix string|null 该 IP 所在的 BGP 通告前缀
data.bgp.as integer|null 起源 AS
data.bgp.as_name string|null 起源 AS 名称
data.bgp.as_cc string|null 起源 AS 注册国家
data.bgp.allocation string|null RIR 分配的母块
data.bgp.allocation_cc string|null 母块注册国家
data.bgp.rpki_status string|null RPKI 校验结果：valid / invalid / unknown
data.bgp.peers array 对等 AS 列表
data.bgp.ix array 所在 IX 列表
data.bgp.line string 线路识别结果（如 CN2 GIA），识别不到时不返回该键
data.is_proxy boolean 是否命中代理/VPN 库
data.proxy_type string 代理类型：VPN / TOR / DCH / PUB / WEB / SES …
data.usage_type string 用途分类：COM / ORG / ISP / MOB / DCH …
data.proxy_domain string 代理服务对应域名
data.proxy_isp string 代理服务对应 ISP
data.threat string 威胁标签
data.fraud_score string 欺诈评分
data.last_seen string 代理库最后观测时间
data.provider string 代理服务提供商
data.is_cloud_idc boolean 是否为云厂商/IDC 地址
data.cloud_provider string 云厂商名称
GET /api/ip/{target}/sources
可选 API Key

多数据源对比

不做合并，原样返回每个地理库对该 IP 的判断，便于比较各库差异。

限流：按套餐（见下方限流表）
点数：2

请求参数

参数 位置 类型 必填 说明
target path string 必填 IPv4 / IPv6 / 域名

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/ip/1.1.1.1/sources'

响应示例

{
  "code": 0,
  "data": {
    "ip": "1.1.1.1",
    "sources": [
      {"source": "IPTrace", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": "APNIC and CloudFlare DNS Resolver Project"},
      {"source": "MaxMind", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": ""},
      {"source": "DB-IP", "country": "Australia", "region": "New South Wales", "city": "Sydney", "lat": -33.8688, "lng": 151.209, "isp": ""},
      {"source": "IP2Location", "country": "Australia", "region": "Queensland", "city": "Brisbane", "lat": -27.467541, "lng": 153.028091, "isp": "APNIC and CloudFlare DNS Resolver Project"},
      {"source": "IPinfo", "country": "Australia", "region": "", "city": "", "lat": null, "lng": null, "isp": "Cloudflare, Inc. (cloudflare.com)"}
    ]
  }
}

响应字段

字段 类型 说明
data.ip string 解析后的 IP
data.sources[].source string 数据源名称（IPTrace / MaxMind / DB-IP / IP2Location / CZ88 / IPIP / Ip2region / IPinfo）
data.sources[].country string 该库给出的国家
data.sources[].region string 该库给出的一级行政区
data.sources[].city string 该库给出的城市
data.sources[].lat number|null 纬度
data.sources[].lng number|null 经度
data.sources[].isp string 该库给出的 ISP
POST /api/ip/batch
可选 API Key

批量 IP 查询

一次最多查 batch_limit 个目标（匿名 5 个，其余见套餐表）。整批只扣一次点数。单个目标非法时该条返回 error 字段，不影响其它条目。

限流：按套餐（见下方限流表）
点数：5

请求参数

参数 位置 类型 必填 说明
ips body string[] 必填 JSON body：{"ips":["1.1.1.1","example.com"]}

请求示例

curl -X POST 'https://iptrace.net/api/ip/batch' \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"ips":["1.1.1.1","192.0.2.999"]}'

响应示例

{
  "code": 0,
  "data": [
    {
      "ip": "1.1.1.1",
      "version": 4,
      "country": "澳大利亚",
      "country_code": "AU",
      "city": "Brisbane",
      "asn": 13335,
      "isp": "Cloudflare",
      "bgp": {"prefix": "1.1.1.0/24", "as": 13335, "as_name": "CLOUDFLARENET", "rpki_status": "valid"},
      "is_proxy": false,
      "is_cloud_idc": true,
      "cloud_provider": "Cloud/IDC",
      "location": "澳大利亚 Queensland Brisbane Cloudflare"
    },
    {"ip": "192.0.2.999", "error": "无效的IP地址或域名"}
  ]
}

响应字段

字段 类型 说明
data[] object 每个目标一条，字段同 /api/ip/{target} 的 data
data[].error string 仅失败条目有：无效的IP地址或域名 / 无法解析目标地址

示例里的成功条目做了字段裁剪，实际返回的是 /api/ip/{target} 的完整字段集。

Whois 与 DNS

域名 / IP / ASN 注册信息与权威 DNS 记录查询。

GET /api/whois/{target}
可选 API Key

Whois / RDAP 查询

target 支持域名、IP、CIDR 前缀与 ASxxxx。优先走 RDAP，失败时回落到传统 whois。

限流：按套餐（见下方限流表）
点数：1

请求参数

参数 位置 类型 必填 说明
target path string 必填 域名 / IP / CIDR / ASxxxx，例如 cloudflare.com、1.1.1.1、AS13335

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/whois/cloudflare.com'

响应示例

{
  "code": 0,
  "data": {
    "target": "cloudflare.com",
    "raw": "Domain Name: CLOUDFLARE.COM\nRegistry Domain ID: 1542998887_DOMAIN_COM-VRSN\nRegistrar WHOIS Server: whois.cloudflare.com\n...",
    "registrar": "Cloudflare, Inc.",
    "creation_date": "2009-02-17T22:07:54Z",
    "expiry_date": "2033-02-17T22:07:54Z",
    "updated_date": "2024-01-15T01:58:26Z",
    "nameservers": ["ns3.cloudflare.com", "ns4.cloudflare.com", "ns5.cloudflare.com"],
    "status": ["clientdeleteprohibited", "clienttransferprohibited"],
    "registrant": "DATA REDACTED",
    "dnssec": "signedDelegation",
    "is_asn": false,
    "available": false
  }
}

响应字段

字段 类型 说明
data.target string 回显查询目标
data.raw string 原始 whois/RDAP 文本
data.registrar string 注册商
data.creation_date string 注册时间（ISO 8601）
data.expiry_date string 到期时间（ISO 8601）
data.updated_date string 最后更新时间
data.nameservers string[] NS 列表
data.status string[] EPP 状态码
data.registrant string 注册人（多数已被隐私保护）
data.dnssec string DNSSEC 状态
data.is_asn boolean 目标是否为 ASN
data.available boolean 域名是否未注册
GET /api/dns/{domain}
可选 API Key

查询全部 DNS 记录

一次返回 A / AAAA / NS / MX / TXT / SOA / CNAME 等全部可解析记录。

限流：按套餐（见下方限流表）
点数：1

请求参数

参数 位置 类型 必填 说明
domain path string 必填 域名，只允许 a-z A-Z 0-9 . -

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/dns/example.com'

响应示例

{
  "code": 0,
  "data": {
    "domain": "example.com",
    "records": [
      {"type": "A", "name": "example.com", "ttl": 8, "value": "104.20.23.154"},
      {"type": "AAAA", "name": "example.com", "ttl": 68, "value": "2606:4700:10::ac42:93f3"},
      {"type": "NS", "name": "example.com", "ttl": 55249, "value": "hera.ns.cloudflare.com"},
      {"type": "TXT", "name": "example.com", "ttl": 157, "value": "v=spf1 -all"},
      {"type": "SOA", "name": "example.com", "ttl": 1784, "value": "elliott.ns.cloudflare.com dns.cloudflare.com", "serial": 2413856909, "refresh": 10000, "retry": 2400, "expire": 604800, "minimum_ttl": 1800}
    ]
  }
}

响应字段

字段 类型 说明
data.domain string 回显域名
data.records[].type string 记录类型
data.records[].name string 记录名
data.records[].ttl integer TTL（秒）
data.records[].value string 记录值
data.records[].priority integer 仅 MX/SRV
data.records[].serial|refresh|retry|expire|minimum_ttl integer 仅 SOA
GET /api/dns/{domain}/{type}
可选 API Key

查询指定类型 DNS 记录

支持的类型：A、AAAA、CNAME、MX、NS、TXT、SOA、SRV、PTR（大小写不敏感）。类型非法返回 code 400。

限流：按套餐（见下方限流表）
点数：1

请求参数

参数 位置 类型 必填 说明
domain path string 必填 域名
type path string 必填 A / AAAA / CNAME / MX / NS / TXT / SOA / SRV / PTR

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/dns/google.com/MX'

响应示例

{
  "code": 0,
  "data": {
    "records": [
      {"type": "MX", "name": "google.com", "ttl": 176, "value": "smtp.google.com", "priority": 10}
    ],
    "query": "google.com",
    "type": "MX",
    "server": ""
  }
}

响应字段

字段 类型 说明
data.records[] object 记录数组，字段同上；无记录时为空数组
data.query string 回显域名
data.type string 回显记录类型
data.server string 使用的解析服务器（默认为空 = 系统解析器）

网络探测

从本站服务器或全球检测节点发起的主动探测，必须带 API Key。

GET /api/tcping/{target}
需要 API Key

TCP 端口连通性与延迟

同步返回，最多 10 次尝试，每次之间间隔 100ms。target 可写成 host、host:port 或 [ipv6]:port；也可用 ?port= 指定端口。禁止探测私有/保留地址（返回 code 403）。

限流：按套餐（见下方限流表）
点数：1 × count（count 默认 4，钳制在 1–10）；走节点探测（country/node）时固定按 4 次计，即 4 点。

请求参数

参数 位置 类型 必填 说明
target path string 必填 host、host:port 或 [ipv6]:port
port query integer — 端口 1–65535，target 里没带端口时使用；默认 80
count query integer — 探测次数，1–10，默认 4
timeout query integer — 单次超时毫秒数，100–5000，默认 3000
country query string — ISO 3166-1 alpha-2，从该国家的检测节点发起
node query string — 指定节点 code，优先于 country

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/tcping/1.1.1.1:443?count=4'

响应示例

{
  "code": 0,
  "data": {
    "target": "1.1.1.1:443",
    "host": "1.1.1.1",
    "ip": "1.1.1.1",
    "port": 443,
    "sent": 4,
    "recv": 4,
    "loss": 0,
    "min": 1.412,
    "max": 2.038,
    "avg": 1.664,
    "rtts": [2.038, 1.55, 1.412, 1.656],
    "timeout_ms": 3000,
    "source": {"type": "origin"}
  }
}

响应字段

字段 类型 说明
data.target string 回显原始 target
data.host string 解析出的主机名部分
data.ip string 实际探测的 IP
data.port integer 实际探测的端口
data.sent integer 发出的连接次数
data.recv integer 成功建连次数
data.loss number 失败率（%）
data.min|max|avg number|null 最小 / 最大 / 平均 RTT（毫秒）
data.rtts array 每次 RTT，失败为 null
data.timeout_ms integer 使用的超时值（仅本站直连）
data.source.type string origin（本站）或 node（检测节点）
data.source.code|name|country_code|city string 节点探测时的节点信息

指定 country 或 node 时，若该国家没有在线节点会返回 code 404 并附 available_countries 列表；节点 14 秒内无响应返回 code 504。

BGP / ASN 数据

这一组接口不需要 API Key、不扣点数，只按来源 IP 限流 60 次/分钟。除 /api/rdns 外均开启 CORS。

GET /api/as-profile/{asn}
无需 API Key

AS 网络概况

返回该 AS 的注册信息与它所通告的全部前缀。ASN 不存在时返回 code 404。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
asn path integer 必填 自治域号，纯数字（不带 AS 前缀）

请求示例

curl 'https://iptrace.net/api/as-profile/13335'

响应示例

{
  "code": 0,
  "data": {
    "asn": 13335,
    "name": "CLOUDFLARENET",
    "entity": "Cloudflare, Inc.",
    "cc": "US",
    "registry": "arin",
    "status": "assigned",
    "in_use": true,
    "private": false,
    "ipv4_prefix_count": 2367,
    "ipv6_prefix_count": 2898,
    "ipv4_prefixes": ["1.1.1.0/24", "104.16.0.0/13", "162.158.0.0/15"],
    "ipv6_prefixes": ["2606:4700::/32", "2a06:98c0::/29"]
  }
}

响应字段

字段 类型 说明
data.asn integer 自治域号
data.name string AS 名称
data.entity string 注册机构
data.cc string 注册国家代码
data.registry string RIR（arin/ripe/apnic/lacnic/afrinic）
data.status string 分配状态
data.in_use boolean 是否有在用前缀
data.private boolean 是否私有 ASN
data.ipv4_prefix_count integer IPv4 前缀数
data.ipv6_prefix_count integer IPv6 前缀数
data.ipv4_prefixes string[] IPv4 前缀列表
data.ipv6_prefixes string[] IPv6 前缀列表
GET /api/as-topo/{asn}
无需 API Key

AS 上下游拓扑

按观测强度（power）排序的上游 / 下游 / 对等 AS 列表。数据不可用时返回 code 404。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
asn path integer 必填 自治域号

请求示例

curl 'https://iptrace.net/api/as-topo/13335'

响应示例

{
  "code": 0,
  "data": {
    "asn": 13335,
    "upstreams": [
      {"asn": 1299, "power": 8260, "name": "Arelion (Twelve99)"},
      {"asn": 3257, "power": 5773, "name": "GTT Communications (AS3257)"},
      {"asn": 3356, "power": 5473, "name": "Lumen AS3356"}
    ],
    "downstreams": [],
    "peers": []
  }
}

响应字段

字段 类型 说明
data.asn integer 被查询的 ASN
data.upstreams[] object 上游 AS：{asn, power, name}
data.downstreams[] object 下游 AS：{asn, power, name}
data.peers[] object 对等 AS：{asn, power, name}
GET /api/prefix-upstreams
无需 API Key

前缀级上游 AS

按具体前缀（而不是整个 AS）统计上游，count 是观测到该上游的路径条数。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
prefix query string 必填 CIDR 前缀，例如 1.1.1.0/24

请求示例

curl 'https://iptrace.net/api/prefix-upstreams?prefix=1.1.1.0/24'

响应示例

{
  "code": 0,
  "data": {
    "prefix": "1.1.1.0/24",
    "origin_as": 13335,
    "upstreams": [
      {"asn": 24482, "count": 11},
      {"asn": 199524, "count": 8},
      {"asn": 1299, "count": 7}
    ]
  }
}

响应字段

字段 类型 说明
data.prefix string 回显前缀
data.origin_as integer 起源 AS
data.upstreams[].asn integer 上游 ASN
data.upstreams[].count integer 观测到的路径条数
GET /api/rdns
无需 API Key

批量反向 DNS（PTR）

一次最多 40 个公网 IP。为了不让同步解析拖住进程，单次最多真正发起 6 个未缓存查询、总预算 3 秒，没轮到的放进 pending，下一轮再问（那时通常已命中缓存）。私有/保留地址会被直接丢弃。

限流：60 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
ips query string 必填 逗号分隔的 IP 列表，最多 40 个

请求示例

curl 'https://iptrace.net/api/rdns?ips=1.1.1.1,8.8.8.8'

响应示例

{
  "resolved": {"1.1.1.1": "one.one.one.one", "8.8.8.8": "dns.google"},
  "pending": []
}

响应字段

字段 类型 说明
resolved object IP → PTR 主机名；空串表示确认没有 PTR，不必再问
pending string[] 本次没来得及解析的 IP，稍后再请求一次

这个接口没有挂 CORS 中间件，浏览器跨站 fetch 会被拦；服务端调用不受影响。返回体也没有 code 包装。

GET /api/nodes
无需 API Key

在线检测节点列表

列出当前在线的检测节点，可用来给 /api/tcping 的 node 参数取值。

限流：60 次/分钟（按来源 IP）
点数：—

请求示例

curl 'https://iptrace.net/api/nodes'

响应示例

{
  "code": 0,
  "data": [
    {
      "id": 30,
      "name": "示例节点",
      "name_en": "Sample Node",
      "code": "sample-node-01",
      "isp": "ct",
      "region": "华中",
      "country": "中国",
      "country_code": "CN",
      "province": "湖北",
      "city": "襄阳市",
      "ipv6": 0,
      "agent_version": "1.0.2",
      "status": 1,
      "last_seen": "2026-09-11 02:55:43"
    }
  ]
}

响应字段

字段 类型 说明
data[].code string 节点唯一标识，用于 /api/tcping?node=
data[].name / name_en string 节点名称（中 / 英）
data[].country / country_code / province / city string 节点位置
data[].isp string 运营商代码
data[].ipv6 integer 是否支持 IPv6 探测（1/0）
data[].status integer 1 = 在线
data[].last_seen string 最后心跳时间

全球 DNS (DoH)

带 EDNS Client Subnet 的 DoH 查询，用来看同一个域名在不同地区解析出的结果。免鉴权，按来源 IP 限流 120 次/分钟。

GET /dns_global/api/regions
无需 API Key

可选地区列表

返回可用于 region 参数的地区数组（裸数组，没有 code 包装）。

限流：120 次/分钟（按来源 IP）
点数：—

请求示例

curl 'https://iptrace.net/dns_global/api/regions'

响应示例

[
  {"code": 0, "label": "中国 - 电信", "flag": "cn", "subnet": "218.30.118.0/24"},
  {"code": 1, "label": "中国 - 联通", "flag": "cn", "subnet": "221.12.1.0/24"},
  {"code": 3, "label": "中国 - 香港", "flag": "hk", "subnet": "203.218.0.0/24"}
]

响应字段

字段 类型 说明
[].code integer region 参数的取值
[].label string 地区名（按当前语言）
[].flag string 国家代码，用于国旗
[].subnet string 实际发送的 EDNS Client Subnet
GET /dns_global/api/query
无需 API Key

按地区查询 DNS

A / AAAA 结果会额外附带 IP 的归属地信息。返回体是裸对象，没有 code 包装；出错时带 error 字段。

限流：120 次/分钟（按来源 IP）
点数：—

请求参数

参数 位置 类型 必填 说明
domain query string 必填 域名
type query string — 记录类型，默认 A；不认识的类型会退回 A
provider query integer — 解析器序号 0–13：0=google 1=cloudflare 2=alidns 3=dnspod 4=adguard 5=nextdns 6=dns.sb 7=360 8=wikimedia 9=iij 10=cleanbrowsing 11=controld 12=surfshark 13=stormycloud；默认 0
region query integer — 地区序号，取自 /dns_global/api/regions

请求示例

curl 'https://iptrace.net/dns_global/api/query?domain=example.com&type=A&provider=1&region=0'

响应示例

{
  "records": [
    {"name": "example.com", "type": "A", "ttl": 36, "value": "104.20.23.154", "geo": "美国 California San Francisco Cloudflare", "isp": "Cloudflare", "asn": 13335, "org": "CloudFlare Inc"}
  ],
  "rcode": "NOERROR",
  "time_ms": 1,
  "resolver": "cloudflare",
  "edns_client_subnet": "218.30.118.0/24",
  "colo": "CDG",
  "country": "FR",
  "location": "Lauterbourg, Grand Est, FR",
  "source": "worker",
  "region": 0,
  "regionLabel": "中国 - 电信",
  "subnet": "218.30.118.0/24"
}

响应字段

字段 类型 说明
records[] object {name, type, ttl, value}，A/AAAA 额外含 geo / isp / asn / org
rcode string DNS 响应码，如 NOERROR / NXDOMAIN
time_ms integer 解析耗时（毫秒）
resolver string 实际使用的解析器
edns_client_subnet string 发送的 ECS
colo / country / location string 解析器落地机房信息（走 Worker 时才有）
source string worker 或 doh，表示走的哪条链路
region / regionLabel / subnet mixed 回显请求的地区
error string 仅失败时出现

账户

查询自己的套餐与用量，必须带 API Key。这两个接口本身也占用限流额度。

GET /api/user/me
需要 API Key

当前账户信息

返回 API Key 对应的账户与生效中的限额。

限流：按套餐（见下方限流表）
点数：—

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/user/me'

响应示例

{
  "code": 0,
  "data": {
    "id": 1024,
    "email": "[email protected]",
    "nickname": "example",
    "plan": "专业版",
    "rate_limit": 600,
    "daily_limit": 100000,
    "batch_limit": 100
  }
}

响应字段

字段 类型 说明
data.id integer 用户 ID
data.email string 邮箱
data.nickname string 昵称
data.plan string 套餐名称
data.rate_limit integer 每分钟请求上限
data.daily_limit integer 每日请求上限，0 = 不限
data.batch_limit integer 单次批量查询上限
GET /api/user/usage
需要 API Key

用量统计

今日调用数、近 30 天合计与逐日明细（daily 固定 30 条，无调用的日期补 0）。

限流：按套餐（见下方限流表）
点数：—

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     'https://iptrace.net/api/user/usage'

响应示例

{
  "code": 0,
  "data": {
    "today": 128,
    "month_total": 4213,
    "daily_limit": 100000,
    "daily": [
      {"date": "2026-08-13", "count": 96},
      {"date": "2026-08-14", "count": 210},
      {"date": "2026-09-11", "count": 128}
    ]
  }
}

响应字段

字段 类型 说明
data.today integer 今日成功调用数
data.month_total integer 近 30 天合计
data.daily_limit integer 每日上限，0 = 不限
data.daily[] object {date, count}，共 30 条，按日期升序

统计口径是「成功调用」：ApiAuth 判定失败（HTTP ≥ 400，或 JSON body 里 code ≠ 0）的请求既不计数也不扣点数，并会把已占用的日配额退还。

数据集下载

三个 MMDB 数据库文件。/info 免鉴权、免费；下载本体仅企业版可用，且每个数据集独立计数：5 次/小时、30 次/天。下载不扣点数。

GET /api/datasets/{dataset}/info
无需 API Key

数据集元信息

dataset 取 mmdb（地理库，约 120 MB）、asn（约 10 MB）或 isp（约 140 MB）。先比对 sha256 再决定要不要重新下载，可以省掉整天的配额。

限流：按套餐（见下方限流表）
点数：免费

请求参数

参数 位置 类型 必填 说明
dataset path string 必填 mmdb / asn / isp

请求示例

curl 'https://iptrace.net/api/datasets/mmdb/info'

响应示例

{
  "code": 0,
  "data": {
    "filename": "merged_geoip2_ccpa.mmdb",
    "format": "mmdb",
    "size": 126352313,
    "mtime": 1778358197,
    "mtime_iso": "2026-05-09T20:23:17Z",
    "sha256": "fa22f93e2ce790b5da8a626c7fd3ac0c45c064a7da73b22b1a1e1018195a89ab",
    "build_epoch": 1778357692,
    "build_iso": "2026-05-09T20:14:52Z",
    "node_count": 11780233,
    "ip_version": 6,
    "languages": ["de", "en", "es", "fr", "ja", "pt-BR", "ru", "zh-CN"]
  }
}

响应字段

字段 类型 说明
data.filename string 文件名
data.format string 固定为 mmdb
data.size integer 字节数
data.mtime / mtime_iso mixed 文件修改时间
data.sha256 string 文件 SHA-256
data.build_epoch / build_iso mixed MMDB 构建时间
data.node_count integer MMDB 节点数
data.ip_version integer 4 或 6
data.languages string[] 内置语言
GET /api/datasets/{dataset}
需要 API Key仅企业版

下载数据集（企业版）

成功时直接返回二进制文件流（application/octet-stream），不是 JSON。非企业版返回 code 403；超限返回 HTTP 429。

限流：5 次/小时 + 30 次/天（按数据集独立计数）
点数：不扣点数，但每个数据集独立计 5 次/小时、30 次/天；中断的下载同样计数。

请求参数

参数 位置 类型 必填 说明
dataset path string 必填 mmdb / asn / isp

请求示例

curl -H 'Authorization: Bearer YOUR_API_KEY' \
     -o merged_geoip2_ccpa.mmdb \
     'https://iptrace.net/api/datasets/mmdb'

响应示例

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="merged_geoip2_ccpa.mmdb"
X-Dataset-Hourly-Limit: 5
X-Dataset-Hourly-Used: 1
X-Dataset-Daily-Limit: 30
X-Dataset-Daily-Used: 1

<binary mmdb>

响应字段

字段 类型 说明
X-Dataset-Hourly-Limit / X-Dataset-Hourly-Used header 本小时配额与已用次数
X-Dataset-Daily-Limit / X-Dataset-Daily-Used header 当天配额与已用次数
Content-Disposition header attachment; filename="…mmdb"

超限时返回 HTTP 429 + Retry-After，body 为 {"code":429,"msg":"…","limit":N,"reset_at":…,"reset_iso":"…"}。

返回顶部