サーバー運営者向け MineList API

MineList APIを使うと、プレイヤーが投票したかどうかの確認、報酬のちょうど1回だけの付与、公開統計の取得ができます。すべてのエンドポイントはJSONを返し、通常のHTTPS GETリクエストで使えるので、どのプログラミング言語からでも利用できます。

APIキーの取得

サーバーを追加して所有者として認証し、オーナーパネルを開いてください。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 は、そのユーザー名がUTCの今日、サーバーに投票していれば true になります。
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 の例

処理の流れ全体をシェルで書くと次のようになります。Java、PHP、Python、Node.js など、HTTPリクエストを送れる言語なら同じことができます。

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 のポートが開いていること、鍵がスペースや改行なしでコピーされていることを確認してください。

ライブバナー

すべてのサーバーに、現在の状態とプレイヤー数を表示する468×60ピクセルのライブバナーがあります。

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

HTMLの埋め込み例は次のとおりです。

<a href="https://minelist.eu/ja/server/your-slug">
  <img src="https://minelist.eu/banner/your-slug.png" width="468" height="60" alt="MineListで投票してください">
</a>

運用のポイント

ページが表示されるたびにAPIを呼び出さず、公開統計は少なくとも1分間キャッシュしてください。
APIキーをクライアント側のコードや公開リポジトリに入れないでください。
受け取り処理のエンドポイントは、1回の報酬につき1度だけ使ってください。