域名注册查询接口, 也叫作Domain Availability Query API, 主要的作用是让使用者能够实时地对指定域名的详细注册状况进行准确的检测和理解, 具体的状态可能包括该域名处于可用状态、已经被别人注册成功, 或者属于保留类别等多种类型, 它是支撑诸如域名买卖交易工作、网站建设时挑选合适名称的活动, 以及大规模监控任务等一系列相关业务场景的一个非常关键并且不可或缺的基础性能力模块, 因此在正式向系统发起调用操作之前, 开发者必须先完成相应的身份认证流程验证环节, 从而顺利获取到属于自己的唯一API Key密钥凭证。

接口基本信息

请求地址:https://api.domainreg.com/v2/domain/check

请求方式:POST

数据格式:application/json

认证方式:请求头携带 Authorization: Bearer

在限流这一规则里面, 针对单个 Key 来说, 默认的流量是每秒50次, 如果你需要更多的次数, 是可以去提出申请以提升配额的。

请求参数

参数名 类型 必填 说明
domain string 是 待查询域名,如 example.com,单次最多传 50 个(用逗号分隔)
tld string 否 限定后缀查询,如 com、cn;不传则按 domain 自带后缀匹配
whois boolean 否 是否返回 WHOIS 基础信息(注册日期、到期日期),默认 false
lang string 否 返回文案语言,默认 zh-CN域名注册查询 接口,支持 en、ja 等

返回结果

域名注册查询接口调用全指南:参数、返回码与接入步骤详解(图1)

如果操作成功了, 就会返回一个状态码为HTTP 200的结果, 此时响应体的结构会是下面这个样子:

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "domain": "example.com",
      "status": "AVAILABLE",
      "whois": {
        "available": true,
        "regDate": null,
        "expireDate": null
      }
    }
  ]
}

关于status这个取值的意思, 需要给大家做一个说明。

AVAILABLE: 也就是说, 当前的状态是可以让大家去进行注册的。

REGISTERED的意思就是说, 这个域名已经被人给注册了。

RESERVED的含义是, 该域名已经被注册商留在了自己的名下, 所以普通的公众人员是不可能去登记和使用它的。

FORBIDDEN, 这代表该域名是被列在禁止交易的清单里的, 属于不允许进行买卖操作的情况。

调用示例

curl -X POST https://api.domainreg.com/v2/domain/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com,mybrand.cn","whois":true}'

常见错误码与处理

大城新闻网

code 含义 处理建议
0 成功 —
1001 API Key 无效或过期 检查 Key 拼写,确认是否在有效期内
1002 未授权 确认 Header 中 Authorization 格式正确
1003 超过限流阈值 降低调用频率或申请提升配额
2001 参数缺失或格式错误 校验 domain 字段长度及字符合法性
2002 单次批量超限(>50) 拆分请求域名注册查询 接口,每批不超过 50 个域名

接入注意事项

域名注册查询接口调用全指南:参数、返回码与接入步骤详解(图2)

1. 域名格式校验: 在传入参数之前, 你需要确保它完全符合相关的规范, 也就是我们常说的RFC 1035规范。这个域名的长度必须保持在最多不超过63个字符的最短不低于1个字符的这个范围里。

同时, 它还只被允许使用字母、数字以及连字符这三类内容来构成。另外还要特别注意的是, 它的首字符和尾字符绝对不能够是连字符。

2. 幂等性就是当在很短的时间里, 用同一个域名去进行重复的查询操作的时候, 接口会返回从缓存里拿到的结果。这个缓存的有效时间是 TTL60秒。这种处理方式不会影响实际的业务逻辑。

3. 对于HTTPS强制这一情况, 它的意思是目前系统只允许用户使用 HTTPS 协议来进行调用操作, 如果用户使用了 HTTP 协议来发起请求, 那么服务端就会返回一个状态码为 301 的重定向响应。

域名注册查询接口调用全指南:参数、返回码与接入步骤详解(图3)

4. 数据时效: 关于 WHOIS 信息, 它存在最长为 24 小时的同步延迟问题。因此, 注册状态应当以实时的 RDAP 为准。

5. 合规使用这个意思就是说, 单个 IP 地址在每一天的查询次数上限是 10 万次。如果你使用的次数超过了这个限制。那么系统就会触发风控措施并进行暂停操作。这种情况下, 你需要通过提交工单来进行申诉。等到申诉恢复之后, 才能继续使用。

关于以上的这些接口规范方面的事情, 是以注册商的官方API文档里面的内容为准的, 如果是在版本发生更新的时候呢, 则会将本文也同步地进行修订的动作来完成此项工作。

如果想要获得那些最新的字段变更日志的内容的话, 是请查阅该平台的开发者中心所提供的「API 版本记录」页面, 通过访问这个页面就可以找到你想知道的东西。