跳到主要内容

API 参考

WHOIS

WHOIS：查询域名注册信息；查询顶级域名覆盖范围。已发布端点、请求参数、JSON 响应与身份认证说明。

发布版本 1.0.0 · 本参考文档对应此处展示的发布版本；当前已发布配置请以 Console 为准。

阅读快速开始 ↗认证方式 ↗了解 API ↗
技术限制
ⓘ以下限制适用于本产品；如端点另有标注，以该端点的限制为准。
请求超时
3 s
请求体上限
1 MiB
响应体上限
1 MiB

查询域名注册信息

GET/whois/v1/domains/{domain}

获取规范化域名的权威注册信息。已注册与确认未注册的域名均返回成功响应。 注册局未公开的可选字段可能省略；可通过 quality.warnings 查看缺失或遮蔽原因。

1 Credits / 每个成功查询的域名了解计费机制 ↗

参数

参数位置类型必填说明
domainpathstring是域名（支持Unicode和Punycode，不含协议或路径）

成功响应200

JSON 模型
{
  "code": 0,
  "data": {
    "domain": {
      "input": "example.com",
      "queried": "example.com",
      "unicode": "example.com"
    },
    "quality": {
      "completeness": "partial",
      "support_level": "standard",
      "warnings": [
        "CONTACT_REDACTED"
      ]
    },
    "record": {
      "contacts": [
        {
          "address": {
            "country": "US",
            "locality": "Example City",
            "postal_code": "12345",
            "region": "Example Region",
            "street": [
              "123 Example Street"
            ]
          },
          "emails": [
            "[email protected]"
          ],
          "handle": "contact-example",
          "name": "Example Contact",
          "organization": "Example Organization",
          "phones": [
            "+1.2025550100"
          ],
          "roles": [
            "registrant"
          ]
        }
      ],
      "dates": {
        "expires_at": "2027-01-01T00:00:00Z",
        "registered_at": "2020-01-01T00:00:00Z",
        "updated_at": "2026-10-20T00:00:00Z"
      },
      "handle": "EXAMPLE-123",
      "nameservers": [
        {
          "ldh_name": "ns1.example.test",
          "unicode_name": "ns1.example.test"
        }
      ],
      "notices": [
        {
          "description": [
            "Example registry terms apply."
          ],
          "links": [
            "https://registry.example.test/terms"
          ],
          "title": "Terms of use"
        }
      ],
      "redactions": [
        {
          "field": "contacts.emails",
          "reason": "Contact details withheld by registry policy"
        }
      ],
      "registrar": {
        "handle": "registrar-example",
        "iana_id": "9999",
        "name": "Example Registrar"
      },
      "secure_dns": {
        "delegation_signed": true
      },
      "statuses": [
        "active"
      ]
    },
    "registration": {
      "registered": true
    },
    "source": {
      "cache_expires_at": "2026-10-21T08:00:00Z",
      "cache_hit": false,
      "fetched_at": "2026-10-20T08:00:00Z",
      "parser_version": "rdap-v1",
      "protocol": "rdap",
      "server": "https://rdap.example.test",
      "source_version": "2026-10-20"
    }
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
domainobject否输入域名与规范化后的域名。
qualityobject否记录完整度与稳定告警码。
recordobject否公开的注册信息；部分字段可能省略。
registrationobject否权威服务确认的注册结论。
sourceobject否权威数据来源与缓存新鲜度。

查询顶级域名覆盖范围

GET/whois/v1/tlds

调用查询接口前，可查看顶级域名的支持等级、查询协议与当前可用性。此接口不会发起上游查询。

免费了解计费机制 ↗

参数

此操作未声明参数。

成功响应200

JSON 模型
{
  "code": 0,
  "data": {
    "generated_at": "2026-10-20T08:00:00Z",
    "items": [
      {
        "availability": "available",
        "last_verified_at": "2026-10-20T08:00:00Z",
        "protocols": [
          "rdap"
        ],
        "support_level": "standard",
        "tld": "com",
        "unicode_tld": "com",
        "unsupported_reason": "No supported authoritative lookup service"
      }
    ],
    "source_version": "2026-10-20"
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
generated_atstring否已加载覆盖快照的 UTC 时间。
itemsobject[]否各顶级域名的支持与不支持能力。
source_versionstring否已发布的数据源配置版本。

创建批量查询任务

POST/whois/v1/batches

一次提交最多 10000 个域名输入。HTTP 202 表示任务已受理，不代表处理完成。 1. 保存响应中的 data.job_id。 2. 轮询 GET /whois/v1/batches/{job_id}；创建响应通过 Retry-After 建议等待 3 秒。 3. 通过 GET /whois/v1/batches/{job_id}/results 读取结果；has_more 为 true 时，携带 next_cursor 继续分页。 调用 POST /whois/v1/batches/{job_id}:cancel 可停止新任务。任务进入终态后，结果保留 7 天。

1 Credits / 每个成功查询的域名了解计费机制 ↗

HTTP 202 只预留 Credits。任务结算时对成功处理项扣费，未使用的预留会释放。

参数

此操作未声明参数。

请求体

JSON 模型
{
  "domains": [
    "example.com",
    "example.net"
  ]
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

请求字段

名称类型必填说明
domainsstring[]是包含 1 至 10000 个域名输入；相同规范化域名共用处理结果。

成功响应202

JSON 模型
{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
active_item_countinteger否当前正在执行的条目数。
completed_item_countinteger否已进入终态的唯一条目数。
expires_atstring否结果到期的 UTC 时间；任务进入终态后提供。
failed_item_countinteger否失败条目数。
input_countinteger否提交的输入条目数。
job_idstring否用于状态和结果接口的批量任务标识。
processing_item_countinteger否尚未完成的唯一条目数；包含排队中的任务。
progressinteger否已完成唯一条目的百分比；取值为 0 至 100。
results_urlstring否分页读取批量结果的 Gateway 相对路径。
statusstring否当前任务生命周期状态。
success_item_countinteger否已有确定注册结论的条目数。
unique_item_countinteger否待处理的去重规范化域名数。
valid_input_countinteger否去重前的有效输入条目数。

查询批量任务进度

GET/whois/v1/batches/{job_id}

使用创建响应中的 job_id 查询任务进度。任务完成、取消、失败或过期后停止轮询。 通过 data.results_url 读取结果。轮询和读取结果免费；批量任务结算时仅对成功查询的域名扣费。

免费了解计费机制 ↗

参数

参数位置类型必填说明
job_idpathstring是批量任务标识

成功响应200

JSON 模型
{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
active_item_countinteger否当前正在执行的条目数。
completed_item_countinteger否已进入终态的唯一条目数。
expires_atstring否结果到期的 UTC 时间；任务进入终态后提供。
failed_item_countinteger否失败条目数。
input_countinteger否提交的输入条目数。
job_idstring否用于状态和结果接口的批量任务标识。
processing_item_countinteger否尚未完成的唯一条目数；包含排队中的任务。
progressinteger否已完成唯一条目的百分比；取值为 0 至 100。
results_urlstring否分页读取批量结果的 Gateway 相对路径。
statusstring否当前任务生命周期状态。
success_item_countinteger否已有确定注册结论的条目数。
unique_item_countinteger否待处理的去重规范化域名数。
valid_input_countinteger否去重前的有效输入条目数。

分页读取批量查询结果

GET/whois/v1/batches/{job_id}/results

结果按原始输入顺序返回。has_more 为 true 时，将 next_cursor 原样作为 cursor 查询参数继续读取。 页面请求成功不代表每个条目均成功；请检查各条目的 status、state 和 error_code。

免费了解计费机制 ↗

参数

参数位置类型必填说明
job_idpathstring是批量任务标识
cursorquerystring否上一页结果中的不透明next_cursor游标
limitqueryinteger否每页结果数（1至500，默认100）

成功响应200

JSON 模型
{
  "code": 0,
  "data": {
    "has_more": false,
    "next_cursor": "<NEXT_CURSOR>",
    "results": [
      {
        "error_code": 0,
        "input_domain": "example.com",
        "normalized_domain": "example.com",
        "position": 0,
        "positions": [
          0
        ],
        "result": {
          "domain": {
            "input": "example.com",
            "queried": "example.com",
            "unicode": "example.com"
          },
          "quality": {
            "completeness": "partial",
            "support_level": "standard",
            "warnings": [
              "CONTACT_REDACTED"
            ]
          },
          "record": {
            "contacts": [
              {
                "address": {
                  "country": "US",
                  "locality": "Example City",
                  "postal_code": "12345",
                  "region": "Example Region",
                  "street": [
                    "123 Example Street"
                  ]
                },
                "emails": [
                  "[email protected]"
                ],
                "handle": "contact-example",
                "name": "Example Contact",
                "organization": "Example Organization",
                "phones": [
                  "+1.2025550100"
                ],
                "roles": [
                  "registrant"
                ]
              }
            ],
            "dates": {
              "expires_at": "2027-01-01T00:00:00Z",
              "registered_at": "2020-01-01T00:00:00Z",
              "updated_at": "2026-10-20T00:00:00Z"
            },
            "handle": "EXAMPLE-123",
            "nameservers": [
              {
                "ldh_name": "ns1.example.test",
                "unicode_name": "ns1.example.test"
              }
            ],
            "notices": [
              {
                "description": [
                  "Example registry terms apply."
                ],
                "links": [
                  "https://registry.example.test/terms"
                ],
                "title": "Terms of use"
              }
            ],
            "redactions": [
              {
                "field": "contacts.emails",
                "reason": "Contact details withheld by registry policy"
              }
            ],
            "registrar": {
              "handle": "registrar-example",
              "iana_id": "9999",
              "name": "Example Registrar"
            },
            "secure_dns": {
              "delegation_signed": true
            },
            "statuses": [
              "active"
            ]
          },
          "registration": {
            "registered": true
          },
          "source": {
            "cache_expires_at": "2026-10-21T08:00:00Z",
            "cache_hit": false,
            "fetched_at": "2026-10-20T08:00:00Z",
            "parser_version": "rdap-v1",
            "protocol": "rdap",
            "server": "https://rdap.example.test",
            "source_version": "2026-10-20"
          }
        },
        "state": "registered",
        "status": "succeeded"
      }
    ]
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
has_moreboolean否是否还有下一页结果。
next_cursorstring否读取下一页的不透明游标；最后一页省略。
resultsobject[]否按原始输入顺序排列的本页结果。

取消批量查询任务

POST/whois/v1/batches/{job_id}:cancel

停止为此任务调度新条目。已完成结果继续保留，正在执行的条目可能继续完成。重复取消是安全的。

免费了解计费机制 ↗

参数

参数位置类型必填说明
job_idpathstring是批量任务标识

成功响应200

JSON 模型
{
  "code": 0,
  "data": {
    "active_item_count": 0,
    "completed_item_count": 0,
    "expires_at": "2026-10-27T08:00:00Z",
    "failed_item_count": 0,
    "input_count": 2,
    "job_id": "job_0123456789abcdef0123456789abcdef",
    "processing_item_count": 2,
    "progress": 0,
    "results_url": "/whois/v1/batches/job_0123456789abcdef0123456789abcdef/results",
    "status": "queued",
    "success_item_count": 0,
    "unique_item_count": 2,
    "valid_input_count": 2
  },
  "error": ""
}

根据已发布 Schema 生成的 JSON 结构示意，字段值仅为示例，并非实时结果。

data 中的字段

名称类型必填说明
active_item_countinteger否当前正在执行的条目数。
completed_item_countinteger否已进入终态的唯一条目数。
expires_atstring否结果到期的 UTC 时间；任务进入终态后提供。
failed_item_countinteger否失败条目数。
input_countinteger否提交的输入条目数。
job_idstring否用于状态和结果接口的批量任务标识。
processing_item_countinteger否尚未完成的唯一条目数；包含排队中的任务。
progressinteger否已完成唯一条目的百分比；取值为 0 至 100。
results_urlstring否分页读取批量结果的 Gateway 相对路径。
statusstring否当前任务生命周期状态。
success_item_countinteger否已有确定注册结论的条目数。
unique_item_countinteger否待处理的去重规范化域名数。
valid_input_countinteger否去重前的有效输入条目数。