面向服务器所有者的 MineList API

MineList API 可以让你的服务器查询玩家是否已投票，只发放一次奖励，并读取公开统计数据。所有接口都返回 JSON，使用普通的 HTTPS GET 请求，因此任何编程语言都能调用。

获取 API 密钥

添加你的服务器，认领它，然后打开所有者面板。API 密钥显示在服务器设置页面。请务必保密，因为它代表你的服务器身份。如果泄露，请在面板中重新生成一个，并更新你的插件或脚本。

所有接口的基础地址是 https://minelist.eu。

查询投票

GET /api/v1/vote?key=API_KEY&username=NICK

返回玩家今天是否已投票，以及奖励是否已被领取。

{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}

voted 为 true 表示该游戏名在当前 UTC 日内给你的服务器投过票。
claimed 为 true 表示你已经把这次投票标记为已领取。
next_vote_utc 是玩家可以再次投票的时间。

领取投票

GET /api/v1/vote/claim?key=API_KEY&username=NICK

把今天的投票标记为已领取。请在发放奖励之前调用，这样玩家就不能重复领取。可能的返回结果如下。

返回结果	含义
`{"voted":true,"claimed":true}`	该投票有效，现已标记为已领取。请发放奖励。
`{"voted":true,"claimed":false,"already_claimed":true}`	该投票之前已被领取。不要发放任何奖励。
`{"voted":false,"claimed":false}`	玩家今天还没有投票。

列出本月投票

GET /api/v1/votes?key=API_KEY

返回你的服务器本月收到的所有投票，可用于发放每月投票榜奖励，或在你自己的网站上做排行榜。

公开服务器统计

GET /api/v1/server/<slug>

这个接口不需要密钥。slug 是服务器在 MineList 上地址的最后一段。返回字段示例如下。

字段	说明
`name`	服务器名称
`url`	服务器网站
`ip`	连接地址
`online`	上次检查是否成功
`players`	上次检查时的在线玩家数
`max_players`	玩家名额
`version`	服务器版本
`votes_month`	本月票数
`votes_total`	服务器添加以来的总票数
`uptime_30`	最近 30 天的在线率，单位为百分比
`rating`	平均评分
`last_check`	上次检查时间

curl 示例

下面是用 shell 写出的完整逻辑。任何能发送 HTTP 请求的语言，如 Java、PHP、Python 或 Node.js，做法都一样。

curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"

解析 JSON，如果 claimed 为 true，就执行你的奖励命令，例如 give Steve diamond 3。

NuVotifier 支持

如果你想要即时发放奖励而不用轮询，MineList 可以通过 NuVotifier 把投票推送到你的服务器。两个协议版本都支持。版本 1 使用 RSA 公钥，版本 2 使用令牌。

在你的服务器上安装 NuVotifier 并重启。
在所有者面板中填写主机、端口（默认 8192）以及公钥（v1）或令牌（v2）。
点击 发送测试投票，并检查你的服务器是否记录了这次投票。

如果测试失败，请确认防火墙已开放 Votifier 端口，并且密钥复制时没有多出空格或换行。

实时横幅

每个服务器都有一个 468x60 像素的实时横幅，显示当前状态和在线玩家数。

https://minelist.eu/banner/<slug>.png

HTML 嵌入示例：

<a href="https://minelist.eu/zh/server/your-slug">
  <img src="https://minelist.eu/banner/your-slug.png" width="468" height="60" alt="在 MineList 给我们投票">
</a>

使用建议

公开统计数据请至少缓存一分钟，不要每次页面访问都调用 API。
绝不要把 API 密钥放进客户端代码或公开的代码仓库。
每份奖励只调用一次领取接口。