Super Whois — API 文档

基础 URL

GEThttps://w.ppee.eu.org/api.php

POSThttps://w.ppee.eu.org/api.php

POST JSON 支持 {"q":"example.com"} 或 {"queries":["example.com","example.org"]}。

认证

该 API 默认可公开访问。认证请求可获得更高但仍有限的配额。

curl -H "Authorization: Bearer YOUR_API_KEY" "https://w.ppee.eu.org/api.php?q=google.com"

请使用 Authorization: Bearer（首选）或 X-API-Key 请求头。本地可直接把 SK 码填入 api_keys.php；生产环境建议使用环境变量。URL 参数中的密钥已弃用。

本地简单设置（编辑 api_keys.php）

$apiKeys = ['paste-your-sk-code-here'];

SUPER_WHOIS_API_KEYS=replace-with-a-long-random-secret

速率限制

未认证客户端每小时每个 IP 有 60 个查询单位；每个唯一查询消耗一个单位，DNS 扩展再消耗一个。

响应头	说明
`RateLimit-Limit`	每个时间窗口的最大查询单位
`RateLimit-Remaining`	当前窗口剩余查询单位
`RateLimit-Reset`	当前时间窗口重置前的秒数
`Retry-After`	触发限流后可再次请求前需等待的秒数

请求参数

参数	必填	说明
`q` / `queries`	必填	查询目标。支持域名（如 `google.com`）、IPv4/IPv6 地址，或 ASN（如 `AS15169`）。逗号或换行分隔多个查询可进入批量模式。 POST JSON 支持 `{"q":"example.com"}` 或 `{"queries":["example.com","example.org"]}`。公开/认证上限：10/50 个查询。输出位置会保留，重复查询只执行一次上游工作。
`key`	可选	已弃用的 URL API Key 参数；请改用 `Authorization` 或 `X-API-Key` 请求头。
`dns`	可选	设为 `true` 时在域名查询结果中附加 DNS 记录（A、AAAA、MX、TXT、NS）
`raw`	可选	单笔查询默认包含原始数据，批量查询默认省略；可明确设为 `true` 或 `false`，原始数据有大小上限。
`pretty`	可选	设为 `true` 输出格式化 JSON；默认返回紧凑 JSON
`lang`	可选	文档语言：`en`（默认）、`zh-cn`（简体）或 `zh-tw`（繁体）

接口与示例

域名查询

GEThttps://w.ppee.eu.org/api.php?q=google.com

IP 查询

GEThttps://w.ppee.eu.org/api.php?q=8.8.8.8

ASN 查询

GEThttps://w.ppee.eu.org/api.php?q=AS15169

域名 + DNS 记录查询

GEThttps://w.ppee.eu.org/api.php?q=google.com&dns=true

批量查询

GEThttps://w.ppee.eu.org/api.php?q=google.com,github.com,cloudflare.com&raw=false

POST{"queries":["google.com","github.com"],"raw":false}

响应字段说明

HTTP 200 表示请求已处理；客户端仍须检查每个项目的 status。为兼容 v2，上游查询失败会以应用层 status=error 表示。

字段	类型	说明
`query`	string	经过处理的查询输入
`query_type`	string	domain \| ipv4 \| ipv6 \| asn
`query_method`	string	RDAP、WHOIS、后备方法或 none
`lookup_domain`	string\|null	域名查询使用 PSL 计算出的可注册域名
`unicode_domain`	string?	输入为 IDN A-label 时的可读 Unicode 域名
`is_subdomain`	boolean?	输入被规范化为可注册 apex 时为 true
`status`	string	registered \| available \| found \| restricted \| error；available 表示权威资料未找到，并非保证可购买
`whois_server`	string\|null	实际提供数据的 RDAP 或 WHOIS 上游服务器
`attempted_servers`	array?	返回结果前尝试过的服务器，用于传输与后备路由诊断
`timestamp`	ISO 8601	本次 API 响应的 UTC 时间
`query_ms`	integer	查询耗时（毫秒）
`cached`	boolean	规范化查询是否来自服务端缓存
`cache_age_s`	integer	缓存值的存在时间（秒）
`stale`	boolean?	临时刷新失败后返回的已注册最近可信缓存
`duration_ms`	number	查询或批量请求耗时（毫秒）
`availability`	string?	权威 RDAP 404 时为 not_found；不代表保证可购买
`upstream_status`	integer?	可用时记录相关上游 HTTP 状态
`dns_records`	object?	dns=true 时返回原始输入主机名的 DNS 数据
`error_code`	string?	稳定的机器可读应用错误码
`request_id`	string	关联 ID，也会通过 X-Request-ID 返回
`api_version`	string	API 版本号
`data`	object	结构化解析字段（仅域名查询且已注册时返回）
`data.creation_date`	ISO 8601	域名注册日期
`data.expiration_date`	ISO 8601	域名到期日期
`data.updated_date`	ISO 8601	最后更新日期
`data.registrar`	string	注册商名称
`data.registrar_iana_id`	string	注册商 IANA 编号
`data.registrant_address` `data.registrant_city` `data.registrant_region` `data.registrant_postal_code`	string?	注册局公开时提供的注册人地址组成部分
`data.nameservers`	array	域名服务器列表（小写、去重；顺序不保证）
`data.status`	array	域名 EPP 状态码
`data.dnssec`	string	signed（已签名）或 unsigned（未签名）
`subdomain_suggestion`	string?	若查询的是子域名，建议查询的顶级域名
`raw`	string?	原始 RDAP/WHOIS 响应（IP 已脱敏）；可用 `raw=false` 省略; 每项最多 131072 字节
`raw_truncated`	boolean?	原始上游数据被大小限制时为 true
`batch/count/succeeded/failed`	批量封装元数据	批量封装摘要；结果保持输入顺序

响应示例 — `api.php?q=google.com`

{ "query": "google.com", "query_type": "domain", "query_method": "rdap", "lookup_domain": "google.com", "whois_server": "rdap.verisign.com", "status": "registered", "cached": false, "cache_age_s": 0, "timestamp": "2026-08-08T10:23:45Z", "query_ms": 180, "api_version": "2.2.2", "data": { "creation_date": "1997-09-15T04:00:00Z", "expiration_date": "2028-09-14T04:00:00Z", "updated_date": "2019-09-09T15:39:04Z", "registrar": "MarkMonitor Inc.", "registrar_iana_id": "292", "registrar_whois": "whois.markmonitor.com", "nameservers": ["ns1.google.com","ns2.google.com","ns3.google.com","ns4.google.com"], "status": ["clientDeleteProhibited","clientTransferProhibited"], "dnssec": "unsigned" }, "request_id": "9c2e7f6f26a9d2c1", "raw": "RDAP 200 from rdap.verisign.com\n--- RDAP JSON ---\n{...}" }

批量响应 — `api.php?q=google.com,github.com`

{ "batch": true, "count": 2, "succeeded": 2, "failed": 0, "duration_ms": 420, "api_version": "2.2.2", "request_id": "9c2e7f6f26a9d2c1", "timestamp": "2026-08-08T10:23:45Z", "results": [ { "query": "google.com", "query_type": "domain", "status": "registered", "..." : "..." }, { "query": "github.com", "query_type": "domain", "status": "registered", "..." : "..." } ] }

错误码

HTTP	含义
`400`	请求错误 — `q` 参数无效或缺失
`401`	未授权 — 需要 API Key 但未提供或无效
`405`	不允许的请求方法
`413`	请求内容或生成的响应超过配置上限
`422`	超过批量查询上限
`429`	请求过频 — 超出速率限制
`503`	限流存储或其他必要运行服务不可用
`500`	服务器错误 — PHP 扩展缺失或配置错误

在线测试

代码示例

JavaScript (fetch)

fetch("https:\/\/w.ppee.eu.org\/api.php?q=google.com") .then(r => r.json()) .then(data => { console.log(data.status); // "registered" console.log(data.data.registrar); // "MarkMonitor Inc." console.log(data.data.expiration_date); // "2028-09-14T04:00:00Z" });

Python (requests)

import requests resp = requests.get("https:\/\/w.ppee.eu.org\/api.php", params={'q': 'google.com'}) data = resp.json() print(data['status']) print(data['data']['registrar'])

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" "https://w.ppee.eu.org/api.php?q=google.com&raw=false" | python3 -m json.tool

批量查询 (cURL)

curl "https://w.ppee.eu.org/api.php?q=google.com,github.com,cloudflare.com&raw=false" | python3 -m json.tool

POST JSON

curl -X POST -H "Content-Type: application/json" -d '{"queries":["google.com","github.com"],"raw":false}' "https://w.ppee.eu.org/api.php"

Super Whois API