域名注册时间与到期时间查询免费 API 接口完整教程

在做域名监测、网站资产盘点、SEO 分析或是抢注提醒时，快速拿到一个域名的注册时间 和到期时间 是最高频的需求之一。接口盒子（apihz.cn）提供了一个免费的域名 WHOIS 查询接口 domainzc2.php，底层采用 WHOIS + RDAP 双模式实时向注册机构请求数据，支持大部分域名后缀，返回标准 JSON，方便各种语言直接接入。

本文将基于官方文档，从接口原理、参数说明、返回格式到 PHP / Python 调用示例，给你一份能直接复制使用的完整指南。

📌 接口能查到什么

注册时间（create）：域名首次注册的时间
到期时间（expire）：当前注册周期到期的时间
状态码（code）：200=成功，400=参数/鉴权错误，404=未注册
采用 WHOIS/RDAP 双通道查询，支持大部分主流后缀（如 .com/.cn/.net 等）

💡 关于 WHOIS 与 RDAP：传统 WHOIS 协议运行在 TCP 43 端口，返回纯文本；RDAP（Registration Data Access Protocol）是其现代替代品，基于 HTTPS 返回结构化 JSON，ICANN 已要求所有 gTLD 注册局提供 RDAP 服务。本接口同时启用两种模式，能在 RDAP 不可用时回退到 WHOIS，提高查询成功率。

🔗 接口基本信息

项目	内容
请求地址	`https://cn.apihz.cn/api/wangzhan/domainzc2.php`
请求方式	GET 或 POST
数据格式	JSON
认证方式	用户 ID + 通讯密钥
费用	免费，每日调用无上限
缓存	查询成功后平台保留 5 分钟缓存

📥 请求参数

所有参数均为必填：

参数名	说明
`id`	接口盒子用户中心的数字 ID，例如 `10000000`
`key`	用户中心的通讯秘钥，例如 `15he5h15ty854j5sr152hs2`
`domain`	要查询的域名，必须是主域名且不能带 http ，例如 `erguanmingmin.com`

📤 返回参数

字段	说明
`code`	状态码：`200` 成功 / `400` 错误 / `404` 未注册（代表域名未注册）；部分隐私保护的域名可能无法查询
`msg`	提示信息
`domain`	查询的域名
`create`	注册时间
`expire`	到期时间

✅ 调用示例（GET 请求）

直接在浏览器或 HTTP 客户端请求：

复制代码

纯文本

复制代码

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

成功返回：

复制代码

json

复制代码

{
  "code": 200,
  "domain": "erguanmingmin.com",
  "create": "2020-09-28 18:57:46",
  "expire": "2026-09-28 18:57:46"
}

错误返回（例如密钥错误）：

复制代码

json

复制代码

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

💻 PHP 调用示例

下面给出 GET 方式的完整 PHP 示例，实际项目中推荐用 POST 隐藏凭证。

复制代码

php

复制代码

<?php
/**
 * 域名注册/到期时间查询 - PHP 示例
 */

$apiUrl = 'https://cn.apihz.cn/api/wangzhan/domainzc2.php';

// 1. 替换为你在接口盒子用户中心获取的 ID 和 KEY
$params = [
    'id'     => 'YOUR_USER_ID',      // TODO: 替换为实际 ID
    'key'    => 'YOUR_API_KEY',      // TODO: 替换为实际 KEY
    'domain' => 'erguanmingmin.com'  // 查询的域名，不要带 http
];

// 2. 拼接 GET 请求 URL
$url = $apiUrl . '?' . http_build_query($params);

// 3. 发起请求（生产环境建议用 curl，这里用 file_get_contents 演示）
$response = file_get_contents($url);
if ($response === false) {
    die("请求失败，请检查网络或接口地址");
}

// 4. 解析 JSON
$data = json_decode($response, true);
if ($data === null) {
    die("JSON 解析失败: " . $response);
}

// 5. 根据 code 处理结果
switch ($data['code']) {
    case 200:
        echo "✅ 查询成功\n";
        echo "域名: {$data['domain']}\n";
        echo "注册时间: {$data['create']}\n";
        echo "到期时间: {$data['expire']}\n";

        // 顺手算一下剩余天数
        $expireTime = strtotime($data['expire']);
        $daysLeft   = ceil(($expireTime - time()) / 86400);
        echo "剩余天数: {$daysLeft} 天\n";
        break;

    case 404:
        echo "❌ 该域名未注册\n";
        break;

    case 400:
        echo "❌ 请求错误: {$data['msg']}\n";
        break;

    default:
        echo "未知状态码: {$data['code']}，消息: {$data['msg']}\n";
}

📝 如果你需要用 POST 方式，只需用 cURL 设置 CURLOPT_POSTFIELDS 传入 $params 即可，接口对 GET/POST 处理逻辑一致。

🐍 Python 调用示例

使用 requests 库，GET 和 POST 各给一个版本。

GET 方式

复制代码

python

复制代码

import requests
import json
from datetime import datetime

def query_domain_expire(user_id: str, api_key: str, domain: str) -> dict:
    """
    查询域名的注册时间和到期时间

    :param user_id: 接口盒子用户 ID
    :param api_key: 接口盒子通讯秘钥
    :param domain: 查询的域名（不含 http）
    :return: 解析后的结果字典
    """
    url = "https://cn.apihz.cn/api/wangzhan/domainzc2.php"
    params = {
        "id": user_id,
        "key": api_key,
        "domain": domain
    }

    try:
        resp = requests.get(url, params=params, timeout=10)
        resp.raise_for_status()
    except requests.RequestException as e:
        return {"success": False, "error": f"请求异常: {e}"}

    data = resp.json()

    if data.get("code") == 200:
        create = data.get("create")
        expire = data.get("expire")

        # 计算剩余天数
        try:
            expire_dt = datetime.strptime(expire, "%Y-%m-%d %H:%M:%S")
            days_left = (expire_dt - datetime.now()).days
        except Exception:
            days_left = None

        return {
            "success": True,
            "domain": data.get("domain"),
            "create": create,
            "expire": expire,
            "days_left": days_left
        }
    elif data.get("code") == 404:
        return {"success": False, "error": "该域名未注册"}
    else:
        return {"success": False, "error": data.get("msg", "未知错误")}


if __name__ == "__main__":
    # TODO: 替换为你的 ID 和 KEY
    USER_ID = "YOUR_USER_ID"
    API_KEY = "YOUR_API_KEY"

    result = query_domain_expire(USER_ID, API_KEY, "erguanmingmin.com")
    if result.get("success"):
        print(f"✅ 查询成功")
        print(f"域名: {result['domain']}")
        print(f"注册时间: {result['create']}")
        print(f"到期时间: {result['expire']}")
        print(f"剩余天数: {result['days_left']} 天")
    else:
        print(f"❌ 查询失败: {result['error']}")

POST 方式（推荐，凭证不出现在 URL 中）

复制代码

python

复制代码

import requests

def query_domain_post(user_id: str, api_key: str, domain: str) -> dict:
    url = "https://cn.apihz.cn/api/wangzhan/domainzc2.php"
    payload = {
        "id": user_id,
        "key": api_key,
        "domain": domain
    }

    resp = requests.post(url, data=payload, timeout=10)
    return resp.json()


# 调用
if __name__ == "__main__":
    result = query_domain_post("YOUR_USER_ID", "YOUR_API_KEY", "erguanmingmin.com")
    print(result)