CNTIERS
返回首页

API 文档

CN TIERS提供了一组API,允许开发者获取玩家数据和排行榜信息。以下是可用的API端点及其使用方法。

新版本 v1 API 现已推出！新版API提供了更多功能、更好的分页支持、更灵活的筛选选项以及更一致的响应格式。

我们欢迎任何一个开发者加入CN TIERS的开发团队,一起为CN TIERS的发展贡献力量。

CNTIER团队版权所有 一切问题由高层处理

v1 API 特性

  • 更一致的响应格式，所有响应都包含元数据
  • 支持分页，可以控制返回结果的数量
  • 更灵活的筛选和排序选项
  • 支持按ID或名称查询玩家
  • 提供系统统计信息API
  • 更详细的玩家信息和段位数据

GET获取所有玩家

/api/v1/players

获取所有玩家的列表，包括他们的基本信息和段位

响应：

[
  {
    "id": 1,
    "name": "玩家名称",
    "avatar": "/default-avatar.jpg",
    "region": "地区名称",
    "swordTier": 4,
    "crystalTier": 3,
    "buhcTier": 2,
    "potionTier": 1,
    "npotTier": 5,
    "smpTier": 3
  },
  ...
]

示例：

fetch('/api/v1/players').then(res => res.json())

GET获取单个玩家

/api/v1/players/:id

根据玩家ID获取单个玩家的详细信息

参数：

名称类型必填描述
idnumber是玩家的唯一ID

响应：

{
  "id": 1,
  "name": "玩家名称",
  "avatar": "/default-avatar.jpg",
  "region": "地区名称",
  "swordTier": 4,
  "crystalTier": 3,
  "buhcTier": 2,
  "potionTier": 1,
  "npotTier": 5,
  "smpTier": 3,
  "createdAt": "2025-09-15T12:00:00.000Z",
  "lastLogin": "2025-09-20T15:30:00.000Z"
}

示例：

fetch('/api/v1/players/1').then(res => res.json())

GET搜索玩家

/api/v1/search?query=

搜索玩家，支持按名称或地区搜索

参数：

名称类型必填描述
querystring是搜索关键词

响应：

[
  {
    "id": 1,
    "name": "玩家名称",
    "avatar": "/default-avatar.jpg",
    "region": "地区名称"
  },
  ...
]

示例：

fetch('/api/v1/search?query=牙刷').then(res => res.json())

GET获取游戏模式排行榜

/api/v1/leaderboard/:mode

获取特定游戏模式的排行榜

参数：

名称类型必填描述
modestring是游戏模式 (sword, crystal, buhc, potion, npot, smp)

响应：

[
  {
    "id": 1,
    "name": "玩家名称",
    "avatar": "/default-avatar.jpg",
    "region": "地区名称",
    "tier": 5,
    "rank": 1
  },
  ...
]

示例：

fetch('/api/v1/leaderboard/sword').then(res => res.json())

GET获取玩家排名（带分页）

/api/v1/rankings

获取玩家排名，支持按游戏模式筛选、分页和更多高级选项

参数：

名称类型必填描述
modestring否游戏模式 (SWORD, CRYSTAL, BUHC, POTION, NPOT, SMP)
limitnumber否每页返回的最大结果数（默认50）
pagenumber否页码（默认1）
regionstring否按地区筛选
minTierstring否最低段位要求（如 HT1, LT2）
includeRetiredboolean否是否包含退休玩家（默认false）

响应：

{
  "rankings": [
    {
      "id": "1",
      "name": "玩家名称",
      "avatar": "https://render.crafty.gg/3d/bust/玩家名称",
      "region": "地区名称",
      "region_id": "region1",
      "region_color": "#ff0000",
      "score": 150,
      "rank": 1,
      "tier": {
        "value": 1,
        "name": "HT1"
      }
    },
    ...
  ],
  "meta": {
    "total": 100,
    "pages": 2,
    "current": 1,
    "mode": "SWORD"
  }
}

示例：

fetch('/api/v1/rankings?mode=SWORD&limit=10&page=1').then(res => res.json())

GET高级玩家搜索

/api/v1/search

使用灵活的选项搜索玩家

参数：

名称类型必填描述
querystring是搜索关键词
fieldstring否搜索字段 (name, region, all)，默认为all
tierModestring否按拥有特定模式段位的玩家筛选
limitnumber否返回的最大结果数（默认20）
exactMatchboolean否是否执行精确匹配（默认false）

响应：

{
  "results": [
    {
      "id": "1",
      "name": "玩家名称",
      "avatar": "https://render.crafty.gg/3d/bust/玩家名称",
      "region": "地区名称",
      "region_id": "region1",
      "region_color": "#ff0000",
      "is_blacklisted": false,
      "score": 75,
      "tiers": {
        "sword": {
          "value": 3,
          "name": "HT2"
        },
        ...
      }
    },
    ...
  ],
  "meta": {
    "query": "搜索关键词",
    "field": "all",
    "total": 5
  }
}

示例：

fetch('/api/v1/search?query=玩家&field=name&limit=5').then(res => res.json())

GET获取玩家详细信息

/api/v1/players/:identifier

通过ID或名称获取玩家的详细信息

参数：

名称类型必填描述
identifierstring是玩家ID或玩家名称
includeScoresboolean否是否包含玩家的比赛分数

响应：

{
  "id": "1",
  "name": "玩家名称",
  "avatar": "https://render.crafty.gg/3d/bust/玩家名称",
  "region": "地区名称",
  "region_id": "region1",
  "region_color": "#ff0000",
  "is_blacklisted": false,
  "total_score": 150,
  "match_score": 50,
  "tier_score": 100,
  "level_name": "Combat Ace",
  "created_at": "2025-03-15T12:00:00.000Z",
  "tiers": {
    "sword": {
      "value": 1,
      "name": "HT1"
    },
    "crystal": {
      "value": 3,
      "name": "HT2"
    },
    ...
  },
  "scores": [
    {
      "id": "1",
      "mode": "SWORD",
      "value": 25,
      "date": "2025-03-10T15:30:00.000Z"
    },
    ...
  ]
}

示例：

fetch('/api/v1/players/玩家名称?includeScores=true').then(res => res.json())

GET获取系统统计信息

/api/v1/stats

获取有关玩家、段位和地区的聚合统计信息

参数：

名称类型必填描述
typestring否统计信息类型 (all, players, tiers, regions)，默认为all

响应：

{
  "stats": {
    "players": {
      "total": 150,
      "with_tiers": 120,
      "without_tiers": 30,
      "average_score": 85,
      "levels": {
        "Combat Master": 5,
        "Combat Ace": 15,
        "Combat Elite": 30,
        "Combat Trainee": 45,
        "Combat Novice": 35,
        "Newbie": 20
      },
      "newest": [
        {
          "id": "1",
          "name": "新玩家1",
          "created_at": "2025-03-28T10:00:00.000Z"
        },
        ...
      ]
    },
    "tiers": {
      "distribution": {
        "SWORD": {
          "HT1": 5,
          "LT1": 10,
          ...
        },
        ...
      },
      "mode_popularity": {
        "SWORD": 85,
        "CRYSTAL": 70,
        ...
      }
    },
    "regions": {
      "total": 10,
      "by_region": [
        {
          "name": "地区1",
          "player_count": 45,
          "players": [
            {
              "id": "1",
              "name": "玩家1"
            },
            ...
          ]
        },
        ...
      ]
    }
  },
  "timestamp": "2025-03-29T02:00:12.345Z"
}

示例：

fetch('/api/v1/stats?type=players').then(res => res.json())