گیم روت
API و توسعه‌دهندگان

شروع سریع API

API عمومی گیم روت همان داده‌هایی را که در صفحه هر سرور می‌بینید، به شکل JSON در اختیار برنامه شما می‌گذارد: وضعیت آنلاین، تعداد بازیکنان، نمودار تاریخچه، رکوردها، نشان‌ها و اخبار. صاحبان سرور می‌توانند با کلید مخصوص سرورشان خبر منتشر کنند یا اطلاعات صفحه را تغییر دهند.

نشانی پایه#

همه مسیرها زیر این نشانی هستند و فقط با HTTPS کار می‌کنند:

متن
https://gameroute.ir/api/v1

پاسخ‌ها همیشه JSON با کدگذاری UTF-8 هستند و زمان‌ها به قالب ISO 8601 و منطقه زمانی UTC برمی‌گردند. سند کامل OpenAPI 3.1 در /api/v1/openapi.json منتشر می‌شود و مرجع API مستقیماً از همین سند ساخته شده است.

۱. اولین درخواست، بدون کلید#

مسیرهای خواندنی بدون کلید هم جواب می‌دهند، فقط با سقف کمتر (۳۰ درخواست در دقیقه برای هر IP). برای امتحان کافی است:

Shell
curl "https://gameroute.ir/api/v1/servers?game=minecraft&pageSize=3"

نامک (slug) هر سرور همان بخش آخر نشانی صفحه آن است؛ مثلاً برای gameroute.ir/servers/iran-craft نامک iran-craft است. به جای نامک، شناسه سرور (id) را هم می‌توانید بفرستید.

۲. ساخت کلید#

  1. وارد پنل کاربری شوید.
  2. برای خواندن داده‌ها به بخش توسعه‌دهندگان و API بروید و یک کلید حساب بسازید.
  3. اگر می‌خواهید خبر منتشر کنید یا اطلاعات سرور را تغییر دهید، به جای آن از صفحه مدیریت سرور، بخش API، وبهوک و ابزارک کلید سرور بسازید.

کلید فقط یک بار نمایش داده می‌شود و شکلی شبیه gr_live_ و ۴۰ کاراکتر حرف و عدد دارد. آن را در یک متغیر محیطی نگه دارید:

Shell
export GAMEROUTE_API_KEY="gr_live_..."

۳. درخواست با کلید#

کلید را در سرآیند Authorization بفرستید:

Shell
curl "https://gameroute.ir/api/v1/servers/iran-craft/status" \
  -H "Authorization: Bearer $GAMEROUTE_API_KEY"

پاسخ:

JSON
{
  "serverId": "cm2x7v1q30000abcd",
  "slug": "iran-craft",
  "online": true,
  "players": 128,
  "maxPlayers": 300,
  "rttMs": 34,
  "version": "1.21.1",
  "map": null,
  "gamemode": "Survival",
  "queriedAt": "2026-10-31T09:41:00.000Z",
  "stale": false
}

۴. همین درخواست در زبان‌های دیگر#

JavaScript
// Node.js 18+ (fetch داخلی)
const res = await fetch('https://gameroute.ir/api/v1/servers/iran-craft/status', {
  headers: { Authorization: `Bearer ${process.env.GAMEROUTE_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const status = await res.json();
console.log(status.online ? `${status.players}/${status.maxPlayers}` : 'offline');
Python
import os
import requests

res = requests.get(
    "https://gameroute.ir/api/v1/servers/iran-craft/status",
    headers={"Authorization": f"Bearer {os.environ['GAMEROUTE_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
status = res.json()
print(status["players"], "/", status["maxPlayers"])
PHP
<?php
$ch = curl_init('https://gameroute.ir/api/v1/servers/iran-craft/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GAMEROUTE_API_KEY')],
    CURLOPT_TIMEOUT => 10,
]);
$status = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $status['players'] . '/' . $status['maxPlayers'];

۵. قدم بعدی#

می‌خواهید…بخوانید
بدانید کلید چطور کار می‌کند و چه دسترسی‌هایی دارداحراز هویت و کلیدها
سقف درخواست و سرآیندهای آن را بشناسیدسقف درخواست
خطاها را درست مدیریت کنیدخطاها
فهرست سرورها را صفحه‌به‌صفحه بخوانیدصفحه‌بندی و سرورها
وضعیت، نمودار و رکوردها را نشان دهیدوضعیت زنده و آمار
از ربات یا سایت خودتان خبر منتشر کنیداخبار
با تغییر وضعیت سرور در دیسکورد پیام بگیریدوبهوک‌ها
بدون کدنویسی بنر وضعیت بگذاریدابزارک‌ها