域名注册状态查询免费API接口详细教程

在互联网和数字化时代，域名作为企业和个人的网络门牌，其注册状态是至关重要的信息。无论是进行域名投资、品牌保护还是新项目启动，快速、批量地查询域名是否已被注册都是一项基本需求。本文将详细介绍由"接口盒子"提供的一个完全免费API的域名注册状态查询API接口，并附上完整的PHP和Python调用示例，帮助开发者快速集成此功能。

一、接口简介

这个免费API接口的核心功能是查询指定域名的注册状态，即判断该域名是否已被他人注册。其技术原理是通过查询域名的WHOIS信息来进行判断。WHOIS是一个用来查询域名注册信息的公开数据库，包含了域名的注册人、注册商、注册日期、过期日期等详细信息。

• 接口地址 : https://cn.apihz.cn/api/wangzhan/domainzc.php
• 请求方式 : 支持 POST 和 GET 两种方式，方便不同场景下的调用。
• 数据格式: 返回数据为标准的JSON格式，易于解析和处理。

二、接口认证与参数说明

要使用该接口，您需要在"接口盒子"用户中心获取您的认证信息。这是为了保证接口的公平使用，防止滥用。

1. 请求参数

所有参数都是必需的。

参数名称	参数	是否必填	说明
用户ID	`id`	是	您在"接口盒子"用户中心的数字ID。例如：`id=10000000`
用户KEY	`key`	是	用户中心的通讯秘钥，用于身份验证。例如：`key=15he5h15ty854j5sr152hs2`
查询域名	`domain`	是	要查询的域名。请注意：免费用户仅支持查询 `.com`和 `.cn`后缀的域名。如需查询更多后缀（如 `.net`, `.cc`, `.xyz`等），需要成为彩钻或炫钻会员。例如：`domain=apihz.cn`

2. 返回参数

接口调用后，会返回一个JSON对象，包含以下字段：

参数名称	参数	说明
状态码	`code`	`200`表示请求成功，`400`表示请求错误（如参数缺失、认证失败等）。
信息提示	`msg`	对状态码的详细文字说明，例如"通讯秘钥错误"。
查询域名	`domain`	返回您所查询的域名。
注册状态	`type`	这是核心字段。`0`表示域名未注册；`1`表示域名已注册。
WHOIS信息	`whois`	只有当域名已注册（`type=1`）时，才会返回完整的WHOIS详细信息。

三、调用示例与代码实现

官方提供了一个公共的ID和KEY用于测试，但因其调用频次限制为所有用户共享，强烈建议您注册账号并使用自己的ID和KEY，以独享调用频次。

GET请求示例URL：

https://cn.apihz.cn/api/wangzhan/domainzc.php?id=88888888&key=88888888&domain=apihz.cn

下面我们分别用PHP和Python来实现对该接口的调用。

PHP调用示例

PHP可以使用 file_get_contents或 cURL 两种方式。这里展示更通用、功能更强大的cURL方法。

复制代码

php

复制

复制代码

<?php
// 配置您的认证信息和要查询的域名
$api_url = "https://cn.apihz.cn/api/wangzhan/domainzc.php";
$your_id = "你的用户ID"; // 请替换为你的实际ID
$your_key = "你的用户KEY"; // 请替换为你的实际KEY
$your_domain = "example.com"; // 请替换为你要查询的域名

// 构建请求URL (GET方式)
$request_url = $api_url . "?id=" . urlencode($your_id) . "&key=" . urlencode($your_key) . "&domain=" . urlencode($your_domain);

// 初始化cURL会话
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $request_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 将响应结果返回，而不是直接输出
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 简便起见，忽略SSL证书验证（生产环境建议设为true）
curl_setopt($ch, CURLOPT_TIMEOUT, 30); // 设置超时时间

// 执行请求并获取响应
$response = curl_exec($ch);

// 检查是否有cURL错误
if (curl_errno($ch)) {
    die('cURL请求发生错误: ' . curl_error($ch));
}

// 关闭cURL资源
curl_close($ch);

// 解析JSON响应
$data = json_decode($response, true);

// 处理返回数据
if ($data['code'] == 200) {
    echo "查询域名: " . $data['domain'] . "\n";
    echo "注册状态: " . ($data['type'] == 1 ? "已注册" : "未注册") . "\n";
    
    if ($data['type'] == 1) {
        echo "WHOIS信息: \n" . $data['whois'] . "\n";
    }
} else {
    echo "查询失败，错误信息: " . $data['msg'] . "\n";
}
?>

Python调用示例

Python可以使用内置的 urllib或更流行的第三方库 requests。这里使用 requests库，因为它代码更简洁。

首先，确保已安装 requests库：pip install requests

复制代码

python

下载

复制

运行

复制代码

import requests
import json

# 配置您的认证信息和要查询的域名
api_url = "https://cn.apihz.cn/api/wangzhan/domainzc.php"
your_id = "你的用户ID"  # 请替换为你的实际ID
your_key = "你的用户KEY"  # 请替换为你的实际KEY
your_domain = "example.com"  # 请替换为你要查询的域名

# 构建请求参数
params = {
    "id": your_id,
    "key": your_key,
    "domain": your_domain
}

try:
    # 发送GET请求
    response = requests.get(api_url, params=params, timeout=30)
    # 确保请求成功（状态码为200）
    response.raise_for_status()
    
    # 解析返回的JSON数据
    data = response.json()
    
    # 处理返回数据
    if data['code'] == 200:
        print(f"查询域名: {data['domain']}")
        status = "已注册" if data['type'] == 1 else "未注册"
        print(f"注册状态: {status}")
        
        if data['type'] == 1:
            print(f"WHOIS信息: \n{data['whois']}")
    else:
        print(f"查询失败，错误信息: {data['msg']}")

except requests.exceptions.RequestException as e:
    print(f"请求过程中发生错误: {e}")
except json.JSONDecodeError as e:
    print(f"解析JSON响应时发生错误: {e}")

四、返回数据示例

1. 域名未注册（成功）

复制代码

json

复制

复制代码

{
    "code": 200,
    "domain": "this-domain-probably-not-registered-123456.cn",
    "type": 0
}

2. 域名已注册（成功）

复制代码

json

复制

复制代码

{
    "code": 200,
    "domain": "apihz.cn",
    "type": 1,
    "whois": "Domain Name: apihz.cn\nROID: 20240319s10001s56425741-cn\nDomain Status: clientUpdateProhibited\n...（完整的WHOIS信息）..."
}

3. 请求错误（失败）

复制代码

json

复制

复制代码

{
    "code": 400,
    "msg": "通讯秘钥错误。"
}

五、重要注意事项

1. 获取个人ID和KEY ：示例中的 id=88888888&key=88888888是公共测试账号，频次限制低。请务必在"接口盒子"官网注册并登录用户中心，获取您自己的ID和KEY，以确保服务的稳定性和独享调用频次。
1. 域名后缀限制 ：免费版仅支持 .com和 .cn域名。在查询前，请确认域名后缀是否在支持范围内。
1. 错误处理 ：在实际应用中，务必添加完善的错误处理逻辑（如代码示例中的 try...except和 if判断），以应对网络问题、认证失败、参数错误等异常情况。
1. 频率限制：虽然接口免费，但可能会有每分钟的调用次数限制。请查阅官方文档或用户中心了解具体的限制规则。

六、总结

"接口盒子"提供的这个免费域名状态查询API接口，以其简洁的参数、清晰的返回值和完全免费的特性，为开发者和小型项目提供了一个非常便利的工具。通过本文提供的PHP和Python代码示例，您可以轻松地将域名查询功能集成到您的网站、应用程序或脚本中，高效地完成域名监控、批量查询等任务。