本文详细解析接口盒子（apihz.cn）提供的免费Minecraft服务器信息查询API，包含完整参数说明、返回结果解析及PHP/Python调用示例。
API核心功能
通过指定Minecraft服务器地址，实时查询：
- 服务器版本/在线玩家数
- MOTD描述信息/网络延迟
- 插件模组列表/玩家示例
- 地图名称/游戏模式
- 网络协议/核心类型
- 服务器图标（Base64编码）
请求参数说明
| id | 是 | 10000000 | 用户中心数字ID |
| key | 是 | 15he5h15ty854j5sr152hs2 | 用户中心通讯密钥 |
| host | 是 | mc2.rhymc.com | 服务器域名/IP |
| port | 否 | 25565 | 端口号（默认25565） |
| xy | 否 | 0 | 查询协议： 0=自动协议(默认) 1=现代协议 2=旧版协议 3=UDP协议 4=兼容协议 |
返回结果解析
json
复制
{
"code": 200, // 状态码（200成功/400错误）
"msg": "查询成功", // 操作提示
"address": "亚洲-中国-江苏省", // IP归属地
"data": {
"hostname": "43.248.139.152", // 服务器IP
"port": 26549, // 服务器端口
"status": true, // 查询状态
"version": "Spigot 1.12.2", // 服务器版本
"protocol": 340, // 网络协议版本
"players": 9, // 在线玩家数
"max_players": 2025, // 最大玩家数
"motd": "世纪监狱服务器", // 清理后的描述
"motd_raw": "§c§l世纪§3§l监狱", // 原始带格式描述
"favicon": "BASE64_DATA", // 服务器图标
"ping": 212, // 网络延迟(ms)
"query_method": "现代协议", // 使用的协议
"players_sample": [{ // 示例玩家列表
"name": "§b状态:正常",
"id": "2730fa19-39ec-3df4"
}],
"map": "未知", // 地图名称
"game_mode": "未知" // 游戏模式
}
}
重要说明：示例ID/KEY共享调用频次限制，需注册账号获取专属凭证
调用示例代码
PHP 示例
php
复制
<?php
$api_url = "https://cn.apihz.cn/api/fun/mcserver.php";
$params = [
'id' => 'YOUR_USER_ID', // 替换为实际ID
'key' => 'YOUR_API_KEY', // 替换为实际KEY
'host' => 'mc.hypixel.net', // 目标服务器
'port' => 25565, // 服务器端口
'xy' => 0 // 自动协议
];
// 构建请求URL
$request_url = $api_url . '?' . http_build_query($params);
// 发送GET请求
$response = file_get_contents($request_url);
// 解析结果
$result = json_decode($response, true);
if ($result['code'] == 200) {
echo "服务器版本: " . $result['data']['version'] . "\\n";
echo "在线玩家: " . $result['data']['players'] . "/" . $result['data']['max_players'];
} else {
echo "查询失败: " . $result['msg'];
}
?>
Python 示例
python
运行
复制
import requests
api_url = "https://cn.apihz.cn/api/fun/mcserver.php"
params = {
"id": "YOUR_USER_ID", # 替换为实际ID
"key": "YOUR_API_KEY", # 替换为实际KEY
"host": "mc.hypixel.net", # 目标服务器
"port": 25565, # 服务器端口
"xy": 0 # 自动协议
}
try:
# 发送GET请求
response = requests.get(api_url, params=params)
data = response.json()
if data["code"] == 200:
print(f"服务器状态: {data['data']['status']}")
print(f"MOTD描述: {data['data']['motd']}")
print(f"网络延迟: {data['data']['ping']}ms")
else:
print(f"错误: {data['msg']}")
except Exception as e:
print(f"请求异常: {str(e)}")
常见问题处理
查询失败（code=400）：
- 检查ID/KEY是否正确
- 尝试更换xy参数协议类型
- 服务器可能禁止查询（非API问题）
数据延迟：
- 成功结果缓存1分钟
- 单次查询超时时间为2秒
高级用法：
- 结合Ping接口测试多地区延迟
- 解析data.debug_log获取详细查询日志
官方文档：Minecraft(我的世界)服务器信息查询 – 接口盒子 – 免费API-免费接口-站长工具-www.apihz.cn
通过此免费API可快速集成Minecraft服务器监控功能到您的应用或网站，实时掌握服务器运行状态。建议合理控制调用频率，避免触发平台限制。
