وضعیت زنده و آمار | داکیومنت گیم روت

گیم روت هر سرور تأییدشده را حدوداً هر یک دقیقه بررسی (query) می‌کند. سرورهایی که پشت سر هم جواب نمی‌دهند با فاصله بیشتری بررسی می‌شوند (حداکثر هر ۱۰ دقیقه). این مسیرها نتیجه همین بررسی‌ها را برمی‌گردانند.

مسیر	کاربرد
`GET /servers/{server}/status`	وضعیت لحظه‌ای
`GET /servers/{server}/players`	فهرست بازیکنان آنلاین
`GET /servers/{server}/stats?range=`	نمودار تاریخچه بازیکنان
`GET /servers/{server}/records`	رکوردها
`GET /servers/{server}/badges`	نشان‌ها

وضعیت لحظه‌ای#

Shell

curl https://gameroute.ir/api/v1/servers/iran-craft/status

فیلد	توضیح
`online`	سرور در آخرین بررسی جواب داد
`players`، `maxPlayers`	بازیکنان آنلاین و ظرفیت
`rttMs`	زمان رفت‌وبرگشت از سرورهای گیم روت تا سرور بازی به میلی‌ثانیه؛ این پینگ بازیکنان نیست
`version`، `map`، `gamemode`	اگر سرور گزارش کند، وگرنه `null`
`queriedAt`	زمان آخرین بررسی
`stale`	اگر آخرین بررسی قدیمی‌تر از ۳ دقیقه باشد `true` است؛ در این حالت وضعیت را «نامشخص» نشان دهید

بازیکنان آنلاین#

JSON

{
  "online": 3,
  "items": [
    { "name": "Sina", "score": 42, "ping": 51 },
    { "name": "Neda", "score": null, "ping": null }
  ],
  "partial": true,
  "queriedAt": "2026-10-31T09:41:00.000Z"
}

ماینکرفت فقط نمونه‌ای (معمولاً حداکثر ۱۲ نفر) از نام بازیکنان را می‌فرستد؛ وقتی تعداد نام‌ها از online کمتر باشد، partial برابر true است.
بعضی سرورها فهرست بازیکن را خاموش کرده‌اند یا نام‌های ساختگی (مثل وضعیت صف) برمی‌گردانند؛ گیم روت همان چیزی را که سرور گزارش کرده نشان می‌دهد.
score و ping فقط وقتی هستند که بازی آن‌ها را گزارش کند (مثلاً MTA).
فهرست بازیکنان فقط برای سرورهای آنلاین و برای مدت کوتاهی نگه داشته می‌شود و تاریخچه ندارد.

نمودار تاریخچه#

Shell

curl "https://gameroute.ir/api/v1/servers/iran-craft/stats?range=7d"

`range`	دقت نقاط	`resolution`
`24h` (پیش‌فرض)	نتیجه خام هر بررسی (حدود هر دقیقه)	`raw`
`7d`	میانگین هر ساعت	`hour`
`30d`	میانگین هر روز (روز به وقت UTC)	`day`

در هر نقطه players میانگین و max بیشینه بازیکنان در آن بازه است (در 24h هر دو مقدار خود بررسی هستند و max ظرفیت سرور است). بخش summary میانگین کل، بیشترین بازیکن و درصد آنلاین بودن (uptimePct) را در همان بازه می‌دهد.

JSON

{
  "range": "7d",
  "resolution": "hour",
  "points": [
    { "t": "2026-10-30T18:00:00.000Z", "players": 141, "max": 163 },
    { "t": "2026-10-30T19:00:00.000Z", "players": 172, "max": 190 }
  ],
  "summary": { "avgPlayers": 156.5, "peakPlayers": 190, "uptimePct": 99.6 }
}

داده خام بررسی‌ها حدود ۷ روز نگه داشته می‌شود و پس از آن فقط میانگین‌های ساعتی و روزانه می‌ماند. برای سرورهای تازه، نقاط کمتری خواهید داشت.

رکوردها#

JSON

{
  "allTime": { "players": 612, "at": "2026-09-12T18:00:00.000Z" },
  "peak24h": { "players": 190, "at": "2026-10-30T19:12:00.000Z" },
  "peak7d": { "players": 233, "at": "2026-10-27T20:00:00.000Z" },
  "peak30d": { "players": 301, "at": "2026-10-10T00:00:00.000Z" }
}

allTime رکورد همیشگی سرور است که روی صفحه سرور هم نمایش داده می‌شود. اگر در بازه‌ای داده‌ای نباشد، مقدار آن بازه null است. برای peak30d زمان، ابتدای همان روز است. رکوردهایی که با دستکاری آمار ثبت شوند طبق قوانین پاک می‌شوند.

نشان‌ها#

JSON

{
  "items": [
    { "key": "record", "name": "رکورددار", "description": "بیشترین بازیکن همزمان ثبت‌شده", "icon": "record", "color": "#F5C04A", "awardedAt": "2026-10-30T19:33:38.748Z", "detail": "رکورد ۱٬۳۹۴ بازیکن همزمان" }
  ]
}

نشان‌ها به ترتیب اولویت نمایش برمی‌گردند. درباره نحوه گرفتن هر نشان در راهنمای نشان‌ها بخوانید.

نمونه: پیام وضعیت برای ربات دیسکورد#

Python

import os
import requests

def status_line(slug):
    s = requests.get(f"https://gameroute.ir/api/v1/servers/{slug}/status", timeout=10).json()
    if s["stale"]:
        return "وضعیت نامشخص"
    return f"آنلاین: {s['players']}/{s['maxPlayers']}" if s["online"] else "آفلاین"