شروع سریع API
API عمومی گیم روت همان دادههایی را که در صفحه هر سرور میبینید، به شکل JSON در اختیار برنامه شما میگذارد: وضعیت آنلاین، تعداد بازیکنان، نمودار تاریخچه، رکوردها، نشانها و اخبار. صاحبان سرور میتوانند با کلید مخصوص سرورشان خبر منتشر کنند یا اطلاعات صفحه را تغییر دهند.
نشانی پایه#
همه مسیرها زیر این نشانی هستند و فقط با HTTPS کار میکنند:
https://gameroute.ir/api/v1پاسخها همیشه JSON با کدگذاری UTF-8 هستند و زمانها به قالب ISO 8601 و منطقه زمانی UTC برمیگردند. سند کامل OpenAPI 3.1 در /api/v1/openapi.json منتشر میشود و مرجع API مستقیماً از همین سند ساخته شده است.
۱. اولین درخواست، بدون کلید#
مسیرهای خواندنی بدون کلید هم جواب میدهند، فقط با سقف کمتر (۳۰ درخواست در دقیقه برای هر IP). برای امتحان کافی است:
curl "https://gameroute.ir/api/v1/servers?game=minecraft&pageSize=3"نامک (slug) هر سرور همان بخش آخر نشانی صفحه آن است؛ مثلاً برای gameroute.ir/servers/iran-craft نامک iran-craft است. به جای نامک، شناسه سرور (id) را هم میتوانید بفرستید.
۲. ساخت کلید#
- وارد پنل کاربری شوید.
- برای خواندن دادهها به بخش توسعهدهندگان و API بروید و یک کلید حساب بسازید.
- اگر میخواهید خبر منتشر کنید یا اطلاعات سرور را تغییر دهید، به جای آن از صفحه مدیریت سرور، بخش API، وبهوک و ابزارک کلید سرور بسازید.
کلید فقط یک بار نمایش داده میشود و شکلی شبیه gr_live_ و ۴۰ کاراکتر حرف و عدد دارد. آن را در یک متغیر محیطی نگه دارید:
export GAMEROUTE_API_KEY="gr_live_..."۳. درخواست با کلید#
کلید را در سرآیند Authorization بفرستید:
curl "https://gameroute.ir/api/v1/servers/iran-craft/status" \
-H "Authorization: Bearer $GAMEROUTE_API_KEY"پاسخ:
{
"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
}۴. همین درخواست در زبانهای دیگر#
// 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');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
$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'];۵. قدم بعدی#
| میخواهید… | بخوانید |
|---|---|
| بدانید کلید چطور کار میکند و چه دسترسیهایی دارد | احراز هویت و کلیدها |
| سقف درخواست و سرآیندهای آن را بشناسید | سقف درخواست |
| خطاها را درست مدیریت کنید | خطاها |
| فهرست سرورها را صفحهبهصفحه بخوانید | صفحهبندی و سرورها |
| وضعیت، نمودار و رکوردها را نشان دهید | وضعیت زنده و آمار |
| از ربات یا سایت خودتان خبر منتشر کنید | اخبار |
| با تغییر وضعیت سرور در دیسکورد پیام بگیرید | وبهوکها |
| بدون کدنویسی بنر وضعیت بگذارید | ابزارکها |