REST API

Tài liệu API

Tích hợp dữ liệu trực tiếp về máy chủ, trình phát, giao diện và cộng đồng Minecraft từ mcstat.org vào các ứng dụng, bot và trang tổng quan của riêng bạn.

URL cơ sở

Tất cả các yêu cầu API đều bắt đầu bằng URL cơ sở này

https://mcstat.org/api/v1

Xem dưới dạng Markdown

Tài liệu Markdown thô cho AI, bot và công cụ

Khóa API

Quản lý và giám sát các khóa API của bạn

Tạo, xoay và xem phân tích cho các khóa API của bạn trong trang tổng quan.

Mở bảng điều khiển khóa API

Sân chơi API

Kiểm tra điểm cuối trực tiếp trong trình duyệt

Kiểm tra bot

Sân chơi này không yêu cầu khóa API; cần xác minh con người để giảm lạm dụng.

Điểm cuối

GET

/api/v1/servers

Tham số truy vấn

page

integer

limit

integer

sort

string

search

string

country

string

version

string

tag

string

mode

string

minPlayers

integer

maxPlayers

integer

minUptime

number

minVotes

integer

minRating

number

onlineOnly

boolean

URL yêu cầu

https://mcstat.org/api/v1/servers

Chạy một yêu cầu để xem phản hồi

Xác thực

Tất cả các điểm cuối API công khai được ghi lại đều yêu cầu khóa API. Gửi khóa của bạn trong tiêu đề X-API-Key.

Tiêu đề yêu cầu

Thêm tiêu đề này để xác thực

X-API-Key: mcs_your_key_here

Hoặc dưới dạng tham số truy vấn

Hoặc chuyển dưới dạng tham số truy vấn

?api_key=mcs_your_key_here

Giới hạn tỷ lệ

Yêu cầu được xác thực bằng khóa API. Khóa bị thiếu hoặc không hợp lệ trả về HTTP 401, khóa bị tắt trả về HTTP 403 và vượt quá giới hạn trả về HTTP 429.

Không có khóa API

Không được phép

Với khóa API

Theo mặc định, 60 yêu cầu mỗi phút, 1.000 mỗi ngày và 30.000 mỗi tháng. Vượt quá giới hạn sẽ trả về HTTP 429 với tiêu đề X-RateLimit-* hiển thị giới hạn của bạn và Retry-After cho bạn biết khi nào cửa sổ đặt lại. Giới hạn cao hơn có thể được cấp cho mỗi khóa theo yêu cầu.

Tiêu đề giới hạn tỷ lệ:Phản hồi 429 mang theo X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month và Retry-After. Phản hồi thành công mang tiêu đề Kiểm soát bộ đệm để bạn có thể lưu kết quả vào bộ đệm phía máy khách một cách an toàn.

Định dạng phản hồi

Mọi phản hồi thành công đều là JSON với một đối tượng boolean và một đối tượng . Lỗi sử dụng cùng một phong bì với : false.

Phản hồi thành công

JSON

{
  "success": true,
  "data": {
    "resource": {
      "id": "...",
      "name": "Example"
    }
  }
}

Phản hồi lỗi

JSON

{
  "success": false,
  "error": "Too many requests"
}

Lỗi

Mã trạng thái HTTP tiêu chuẩn được sử dụng. Các trường hợp phổ biến:

Mã	Ý nghĩa
`400`	Yêu cầu không hợp lệ - tham số không hợp lệ
`401`	Không được phép — khóa API bị thiếu hoặc không hợp lệ
`403`	Bị cấm - Khóa API bị vô hiệu hóa
`404`	Không tìm thấy - tài nguyên không tồn tại
`429`	Quá nhiều yêu cầu - vượt quá giới hạn tốc độ
`500`	Lỗi máy chủ nội bộ - thử lại sau

Điểm cuối máy chủ

Duyệt, lọc và kiểm tra các máy chủ Minecraft được theo dõi bởi mcstat.org.

GET

/api/v1/servers

Liệt kê máy chủ

Danh sách các máy chủ công cộng được phân trang với các bộ lọc phong phú.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`20`	Các mục trên mỗi trang.
`sort`	`string`	Không	`recent`	Sắp xếp thứ tự.
`search`	`string`	Không	`—`	Truy vấn văn bản tự do.
`country`	`string`	Không	`—`	Bộ lọc tên quốc gia ISO.
`version`	`string`	Không	`—`	Bộ lọc phiên bản Minecraft.
`tag`	`string`	Không	`—`	Lọc theo thẻ.
`mode`	`string`	Không	`—`	Bộ lọc chế độ trò chơi.
`minPlayers`	`integer`	Không	`—`	Số lượng người chơi hiện tại tối thiểu.
`maxPlayers`	`integer`	Không	`—`	Số lượng người chơi hiện tại tối đa.
`minUptime`	`number`	Không	`—`	Tỷ lệ phần trăm thời gian hoạt động tối thiểu.
`minVotes`	`integer`	Không	`—`	Tổng số phiếu bầu tối thiểu.
`minRating`	`number`	Không	`—`	Xếp hạng tối thiểu (1–5).
`onlineOnly`	`boolean`	Không	`—`	Chỉ bao gồm các máy chủ báo cáo trực tuyến.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "shortDescription": "Home of over 35 unique games…",
        "ip": "mc.hypixel.net",
        "port": 25565,
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "motd": "Hypixel Network",
        "website": null,
        "discordUrl": null,
        "visibility": "PUBLIC",
        "isOnline": true,
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "version": "Requires MC 1.8 / 1.21",
        "latency": 42,
        "lastPing": "2026-05-24T22:00:00Z",
        "country": "United States",
        "tags": [
          "bedwars",
          "pvp",
          "skyblock"
        ],
        "gameMode": null,
        "uptime": 100,
        "trend": 3.4,
        "totalVotes": 12345,
        "rating": 4.6,
        "createdAt": "2026-04-28T05:44:26Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/servers/{slug}

Chi tiết máy chủ

Hồ sơ máy chủ đầy đủ: lịch sử thống kê, thời gian hoạt động, biểu đồ bình chọn, xếp hạng.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).
`period`	`string`	Không	`24h`	Cửa sổ thời gian: 24h, 7d, 30d, 90d, all-time.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "server": {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "port": 25565,
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motd": "Hypixel Network",
      "motdRaw": "§aHypixel §7Network",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "website": null,
      "discordUrl": null,
      "storeUrl": null,
      "youtubeUrl": null,
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "version": "Requires MC 1.8 / 1.21",
      "protocol": 767,
      "uptime": 100,
      "rating": 4.6,
      "totalVotes": 12345,
      "tags": [
        "bedwars",
        "pvp"
      ],
      "owner": null,
      "latestStats": {
        "onlinePlayers": 48230,
        "tps": 20,
        "timestamp": "2026-05-24T22:00:00Z"
      },
      "statsHistory": [
        {
          "timestamp": "2026-05-24T21:00:00Z",
          "onlinePlayers": 47000
        }
      ],
      "periodStats": {
        "24h": {
          "avgPlayers": 46500,
          "peakPlayers": 49100,
          "minPlayers": 42000,
          "uptimePct": 99.95
        }
      },
      "voteStats": {
        "24h": 412,
        "7d": 2890,
        "30d": 11200,
        "90d": 30150
      },
      "dailyVotes": [
        {
          "day": "2026-05-23",
          "votes": 405
        }
      ]
    }
  }
}

GET

/api/v1/servers/{slug}/voters

Máy chủ cử tri

Những người bỏ phiếu gần đây (được xác thực và ẩn danh) cho máy chủ nhất định.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/voters"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`7`	Các mục trên mỗi trang.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "voters": [
      {
        "id": "TanfrbogDfzGdrgD",
        "minecraftUsername": "Notch",
        "votedAt": "2026-05-24 22:10:06.544",
        "type": "auth",
        "playerId": "xq5-Lw8xk7pEdKyn",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "skinUrl": "http://textures.minecraft.net/texture/cbea0a15a5ce…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "siteUsername": "notch"
      }
    ],
    "total": 12345,
    "page": 1,
    "totalPages": 515,
    "latestVoteAt": "2026-05-24 22:10:06.544"
  }
}

GET

/api/v1/servers/{slug}/reviews

Đánh giá máy chủ

Đánh giá và xếp hạng của người chơi được phân trang cho một máy chủ.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/reviews"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`5`	Các mục trên mỗi trang.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "5g4VgYUiN4n28qcX",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": null,
        "minecraftUsername": "chibibara",
        "rating": 3,
        "content": "Great community!",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z",
        "user": {
          "id": null,
          "username": "chibibara",
          "avatar": null,
          "role": "USER"
        },
        "playerId": "suTEw8opOK2bGP-L",
        "playerMainNickname": "chibibara",
        "playerMinecraftUuid": "019f1b29-fcbe-705b-8efb-8c08b4e0fd9c",
        "playerSkinUrl": null,
        "playerSkinModel": "classic",
        "playerLinkedSkinPngPath": "https://mcstat.org/media/skins/published/default-steve.png"
      }
    ],
    "total": 128,
    "page": 1,
    "totalPages": 26,
    "avgRating": 4.2,
    "latestReviewAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/{slug}/updates

Cập nhật máy chủ

Bài đăng tin tức và cập nhật đã duyệt cho một máy chủ.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/updates"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`3`	Các mục trên mỗi trang.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "updates": [
      {
        "id": "Xk3pQ2mNbV8zR1sd",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": "Nf3kPq8sT2wVxJ7b",
        "title": "Season 5 is live!",
        "content": "New map, new kits, double XP weekend.",
        "status": "APPROVED",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "totalPages": 4,
    "latestUpdateAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/top

Máy chủ hàng đầu

Danh sách xu hướng được tối ưu hóa cho việc sử dụng trang chủ/widget.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/top"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`sort`	`string`	Không	`votes`	Sắp xếp thứ tự.
`limit`	`integer`	Không	`10`	Các mục trên mỗi trang.
`country`	`string`	Không	`—`	Bộ lọc tên quốc gia ISO.
`gameMode`	`string`	Không	`—`	Bộ lọc chế độ trò chơi.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "ip": "mc.hypixel.net",
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "totalVotes": 12345,
        "uptime": 100,
        "trend": 3.4,
        "recentVotes": 412,
        "hotScore": 9821
      }
    ],
    "total": 1240,
    "sort": "hot"
  }
}

GET

/api/v1/servers/countries

Quốc gia máy chủ

Tổng số máy chủ được nhóm theo quốc gia.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/countries"

Tham số truy vấn

Không có tham số

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "United States",
        "serverCount": 2840
      }
    ]
  }
}

GET

/api/v1/servers/versions

Phiên bản máy chủ

Tổng số máy chủ được nhóm theo phiên bản Minecraft.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/versions"

Tham số truy vấn

Không có tham số

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "Paper 1.21.11",
        "serverCount": 980
      }
    ]
  }
}

Điểm cuối của người chơi

Tra cứu hồ sơ người chơi, phiên, cấp độ và lịch sử.

GET

/api/v1/players

Danh sách người chơi

Thư mục trình phát công cộng được phân trang.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`—`	Các mục trên mỗi trang.
`sort`	`string`	Không	`recent`	Sắp xếp thứ tự.
`search`	`string`	Không	`—`	Truy vấn văn bản tự do.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "h6tC6lGfBEDulI8o",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "mainNickname": "Notch",
        "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "country": "United States",
        "tierOverall": "HT1",
        "tierPoints": 9820,
        "tierRank": 12,
        "lastTierSyncAt": "2026-05-24T20:00:00Z",
        "createdAt": "2026-04-01T10:00:00Z",
        "totalPlayTime": 184320,
        "sessionCount": 412
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/players/{id}

Chi tiết người chơi

Hồ sơ, các phiên gần đây, máy chủ đã chơi, K/D, thành tích.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`id`	`string`	Có	`—`	Id người chơi, UUID hoặc biệt hiệu.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "player": {
      "id": "h6tC6lGfBEDulI8o",
      "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
      "mainNickname": "Notch",
      "nicknameHistory": [
        "Notch"
      ],
      "country": null,
      "skinModel": "classic",
      "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
      "linkedSkinId": "Wi_n1dUvFqgJs0aP",
      "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
      "linkedSkin": {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "player-skin-notch",
        "pngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "model": "classic",
        "name": "Notch's Skin"
      },
      "tierOverall": "MCStat Mythic",
      "tierPoints": 9820,
      "tierRank": 12,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-24T22:00:00Z",
      "totalPlayTime": 184320,
      "sessionCount": 412,
      "rankScore": 9820,
      "rank": 12,
      "recentSessions": [
        {
          "id": "oWZiF6jq_UnEs7Y3",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          },
          "joinedAt": "2026-05-24T20:00:00Z",
          "leftAt": "2026-05-24T21:00:00Z",
          "totalPlayTime": 3600
        }
      ],
      "serversPlayed": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
        }
      ],
      "latestStats": {
        "statsJson": {
          "kills": 18230,
          "deaths": 9850,
          "wins": 1240
        },
        "timestamp": "2026-05-24T21:00:00Z",
        "server": {
          "slug": "mchypixelnet",
          "name": "Hypixel Network"
        }
      },
      "statsHistory": [
        {
          "statsJson": {
            "kills": 18000,
            "deaths": 9700
          },
          "timestamp": "2026-05-24T20:00:00Z",
          "serverName": "Hypixel Network"
        }
      ],
      "kdRatio": 1.85,
      "totalKills": 18230,
      "totalDeaths": 9850,
      "totalWins": 1240,
      "activityData": [
        {
          "date": "2026-05-24",
          "count": 3
        }
      ],
      "achievements": {
        "earned": [
          {
            "id": "top10",
            "label": "Top 10",
            "labelTr": "İlk 10",
            "labelRu": "Топ 10",
            "icon": "medal"
          }
        ],
        "nextGoals": [
          {
            "id": "explorer_25",
            "label": "Globe Trotter",
            "labelTr": "Dünya Gezgini",
            "labelRu": "Путешественник",
            "icon": "plane"
          }
        ]
      },
      "votedServers": [
        {
          "serverId": "JS6o0w88QP6oZHDj",
          "serverSlug": "mchypixelnet",
          "serverName": "Hypixel Network",
          "serverIconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "votedAt": "2026-05-24T22:10:00Z"
        }
      ],
      "reviews": [
        {
          "id": "Rv8xKp2mNq7wTz1a",
          "rating": 5,
          "content": "Great server!",
          "createdAt": "2026-05-20T10:00:00Z",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          }
        }
      ]
    }
  }
}

Tìm kiếm

Tìm kiếm hợp nhất trên máy chủ và người chơi.

GET

/api/v1/search

Tìm kiếm toàn cầu

Tìm kiếm máy chủ và người chơi trong một lệnh gọi.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/search"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`q`	`string`	Có	`—`	Truy vấn tìm kiếm (2–100 ký tự).
`type`	`string`	Không	`all`	Loại kết quả: all, servers, players.
`limit`	`integer`	Không	`10`	Các mục trên mỗi trang.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "results": {
      "servers": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
          "currentPlayers": 48230,
          "maxPlayers": 200000,
          "isOnline": true,
          "rating": 3.4
        }
      ],
      "players": [
        {
          "id": "h6JDPuUGKI3Mfw3m",
          "minecraftUuid": "de5f2979-1168-43d6-b5f3-e18f975a806b",
          "mainNickname": "Notch",
          "createdAt": "2026-04-01T10:00:00Z",
          "updatedAt": "2026-05-24T22:00:00Z"
        }
      ]
    },
    "query": "hypixel"
  }
}

Số liệu thống kê trực tiếp và toàn cầu

Hoạt động toàn cầu theo thời gian thực, phân tích khu vực và quốc gia.

GET

/api/v1/live

Số liệu thống kê trực tiếp

Tổng số trực tuyến toàn cầu, máy chủ hàng đầu, hoạt động gần đây, phân tích khu vực và quốc gia.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live"

Tham số truy vấn

Không có tham số

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "stats": {
      "totalPlayers": 184320,
      "totalServers": 12480,
      "onlineServers": 9821,
      "newPlayersToday": 412,
      "peakToday": 202700,
      "generatedAt": "2026-05-24T22:00:00Z",
      "latestPingAt": "2026-05-24T21:59:48Z",
      "statsAgeSeconds": 18,
      "stale": false
    },
    "topServers": [
      {
        "id": "mchypixelnet",
        "name": "Hypixel Network",
        "players": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "trend": "up",
        "change": 240
      }
    ],
    "recentActivity": [
      {
        "type": "vote",
        "actor": "Notch",
        "target": "Hypixel Network",
        "time": "2026-05-24T22:00:00Z"
      }
    ],
    "regions": [
      {
        "id": "na",
        "name": "North America",
        "players": 80120,
        "servers": 4120
      }
    ],
    "countryPlayers": {
      "United States": 60120,
      "Germany": 18230
    }
  }
}

GET

/api/v1/live/history

Lịch sử trực tiếp

Tổng số người chơi trực tuyến hàng giờ trong 7 ngày qua.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live/history"

Tham số truy vấn

Không có tham số

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "history": [
      {
        "timestamp": "2026-05-23T22:00:00Z",
        "totalPlayers": 174200
      }
    ]
  }
}

Bảng xếp hạng

Những người chơi hàng đầu được xếp hạng theo phiên, máy chủ hoặc điểm cấp bậc.

GET

/api/v1/leaderboards

Bảng xếp hạng

Những người chơi hàng đầu cho các bộ lọc chỉ số, giai đoạn, cấp độ và thành tích đã chọn.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/leaderboards"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`metric`	`string`	Không	`best`	Số liệu xếp hạng: best, sessions, servers.
`period`	`string`	Không	`all-time`	Cửa sổ thời gian: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`20`	Các mục trên mỗi trang.
`tier`	`string`	Không	`—`	Bộ lọc cấp.
`achievement`	`string`	Không	`—`	Bộ lọc thành tích
`search`	`string`	Không	`—`	Truy vấn văn bản tự do.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "leaderboard": {
      "metric": "best",
      "period": "all-time",
      "serverId": null,
      "generatedAt": "2026-05-24T22:00:00Z",
      "entries": [
        {
          "rank": 1,
          "player": {
            "id": "Vz2BaB2r6eC9TL_o",
            "mainNickname": "Notch",
            "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
            "tierOverall": "MCStat Mythic",
            "tierPoints": 224606,
            "tierRank": 1,
            "skinModel": "classic",
            "skinUrl": "http://textures.minecraft.net/texture/d71c3adef2ec…",
            "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png"
          },
          "value": 224606,
          "formattedValue": "224,606 score"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

Da & Áo choàng

Tìm kiếm giao diện và áo choàng do cộng đồng tải lên.

GET

/api/v1/skins

Danh sách giao diện

Duyệt tải lên giao diện cộng đồng bằng cách sắp xếp/bộ lọc.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`24`	Các mục trên mỗi trang.
`sort`	`string`	Không	`recent`	Sắp xếp thứ tự.
`model`	`string`	Không	`—`	Mẫu da: cổ điển hoặc thon gọn.
`search`	`string`	Không	`—`	Truy vấn văn bản tự do.
`tag`	`string`	Không	`—`	Lọc theo thẻ.
`owner`	`string`	Không	`—`	Bộ lọc tên người dùng của chủ sở hữu.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "skins": [
      {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "cool-knight",
        "name": "Cool Knight",
        "model": "classic",
        "tags": [
          "medieval",
          "armor"
        ],
        "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
        "viewCount": 3120,
        "likeCount": 124,
        "favoriteCount": 88,
        "downloadCount": 980,
        "usageCount": 12,
        "isFeatured": false,
        "createdAt": "2026-05-01T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/skins/{slug}

Chi tiết da

Siêu dữ liệu đầy đủ về giao diện cộng với trạng thái thích/yêu thích của người xem.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins/hypixel-net"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "skin": {
      "id": "Wi_n1dUvFqgJs0aP",
      "slug": "cool-knight",
      "name": "Cool Knight",
      "description": "Custom medieval knight skin",
      "tags": [
        "medieval",
        "armor"
      ],
      "model": "classic",
      "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
      "viewCount": 3120,
      "likeCount": 124,
      "favoriteCount": 88,
      "downloadCount": 980,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "tierOverall": "MCStat Mythic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/cool-knight.png"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

GET

/api/v1/capes

Danh sách áo choàng

Duyệt các bản tải lên của cộng đồng bằng tính năng sắp xếp/bộ lọc.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`page`	`integer`	Không	`1`	Số trang, bắt đầu từ 1.
`limit`	`integer`	Không	`24`	Các mục trên mỗi trang.
`sort`	`string`	Không	`recent`	Sắp xếp thứ tự.
`search`	`string`	Không	`—`	Truy vấn văn bản tự do.
`tag`	`string`	Không	`—`	Lọc theo thẻ.
`owner`	`string`	Không	`—`	Bộ lọc tên người dùng của chủ sở hữu.

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "capes": [
      {
        "id": "De-jbTlj_PTnJJ5N",
        "slug": "royal-red",
        "name": "Royal Red",
        "tags": [
          "red",
          "royal"
        ],
        "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
        "viewCount": 210,
        "likeCount": 18,
        "favoriteCount": 6,
        "downloadCount": 44,
        "isFeatured": false,
        "createdAt": "2026-05-02T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/capes/{slug}

Chi tiết áo choàng

Siêu dữ liệu áo choàng đầy đủ cùng trạng thái thích/yêu thích của người xem.

Yêu cầu mẫu

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes/hypixel-net"

Tham số truy vấn

Tên	loại	bắt buộc	mặc định	Mô tả
`slug`	`string`	Có	`—`	Sên máy chủ (từ danh sách/máy chủ).

Phản hồi mẫu

JSON

{
  "success": true,
  "data": {
    "cape": {
      "id": "De-jbTlj_PTnJJ5N",
      "slug": "royal-red",
      "name": "Royal Red",
      "description": "Deep red royal cape",
      "tags": [
        "red",
        "royal"
      ],
      "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
      "viewCount": 210,
      "likeCount": 18,
      "favoriteCount": 6,
      "downloadCount": 44,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
          "tierOverall": "MCStat Mythic"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}