試合ツール

試合の詳細データ・武器統計・リテイク率を取得します。

get_match_detail

試合IDで1試合の完全なデータを取得します。

パラメーター

名前	型	説明
match_id	string	get_player_matches などで取得したID

レスポンス

{
  "match_id": "xxxxxxxx-...",
  "match_url": "https://valo.town/match/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "map_id": "/Game/Maps/Ascent/Ascent",
  "queue": "competitive",
  "is_ranked": true,
  "started_at": "1784374685375",
  "duration_ms": "2255061",
  "season_id": "...",
  "players": [
    {
      "gameName": "PlayerName",
      "tagLine": "JP1",
      "teamId": "Blue",
      "characterId": "a3bfb853-43b2-7238-a4f1-ad90e9e46bcc",
      "stats": {
        "score": 6515,
        "kills": 21,
        "deaths": 17,
        "assists": 10,
        "roundsPlayed": 21
      },
      "competitiveTier": 18,
      "accountLevel": 125,
      "name_hidden": false
    }
  ],
  "teams": [
    { "teamId": "Blue", "won": true, "roundsWon": 13, "roundsPlayed": 21 },
    { "teamId": "Red",  "won": false, "roundsWon": 8,  "roundsPlayed": 21 }
  ],
  "roundResults": [
    {
      "roundNum": 0,
      "roundResult": "Eliminated",
      "winningTeam": "Blue",
      "winningTeamRole": "Attacker",
      "bombPlanter": null,
      "bombDefuser": null,
      "plantSite": null
    },
    {
      "roundNum": 5,
      "roundResult": "BombDetonated",
      "winningTeam": "Blue",
      "winningTeamRole": "Attacker",
      "bombPlanter": "puuid-...",
      "bombDefuser": null,
      "plantSite": "B"
    }
  ],
  "privacy": {
    "names_sanitized": false,
    "requester_can_see_own_name": true
  }
}

roundResults のフィールド

フィールド	説明
roundResult	"Eliminated" / "BombDetonated" / "BombDefused" / "Surrendered"
winningTeamRole	"Attacker"（攻撃側勝利）または "Defender"（守備側勝利）
bombPlanter	スパイク植え付けプレイヤーのpuuid（植えたラウンドのみ存在）
bombDefuser	解除プレイヤーのpuuid（解除成功ラウンドのみ存在）
plantSite	"A" / "B" / "C"

使用例

get_match_detail(match_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

リテイク率を計算したい場合

個別の試合を解析するより get_retake_stats に複数の match_id を渡すほうが効率的です。

---

search_matches

マップ・キュー・シーズンなどで試合を横断検索します。特定のプレイヤーではなくプラットフォーム全体のデータを対象にします。

パラメーター

名前	型	デフォルト	説明
map_id	string	""	マップID（/Game/Maps/Ascent/Ascent 形式）
queue	string	""	キュー（competitive など）
is_ranked	bool | null	null	ランク戦のみ絞り込み
season_id	string	""	シーズンID
limit	int	20	取得件数（最大100）
offset	int	0	オフセット

レスポンス

{
  "total": 4812,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "match_id": "...",
      "match_url": "https://valo.town/match/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "map_id": "/Game/Maps/Ascent/Ascent",
      "queue": "competitive",
      "is_ranked": true,
      "started_at": "1784374685375",
      "duration_ms": "2255061"
    }
  ]
}

使用例

# アセントのコンペティティブ試合を検索
search_matches(map_id="/Game/Maps/Ascent/Ascent", queue="competitive")

# ランク戦のみ
search_matches(is_ranked=true, limit=50)

---

get_match_weapon_stats

1試合における武器別のショット統計を取得します。

パラメーター

名前	型	説明
match_id	string	試合ID

レスポンス

[
  {
    "weaponId": "weapon-uuid",
    "matchId": "match-uuid",
    "headshots": 12,
    "bodyshots": 34,
    "legshots": 5,
    "total_shots": 51,
    "headshot_rate": 23.5
  }
]

使用例

get_match_weapon_stats(match_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

---

get_retake_stats

複数の試合IDからマップ・サイト別のリテイク率を集計します。

リテイク率 = スパイク植え付けが発生したラウンドのうち、守備側が解除（defuse）に成功した割合

パラメーター

名前	型	説明
match_ids	list[string]	試合IDのリスト（最大100件推奨）

レスポンス

{
  "/Game/Maps/Ascent/Ascent": {
    "map_id": "/Game/Maps/Ascent/Ascent",
    "planted_rounds": 38,
    "retake_success": 14,
    "retake_fail": 18,
    "retake_rate": 36.8,
    "by_site": {
      "A": { "planted": 18, "retake_success": 8, "retake_fail": 7, "retake_rate": 44.4 },
      "B": { "planted": 20, "retake_success": 6, "retake_fail": 11, "retake_rate": 30.0 }
    }
  }
}

使用例

# まず試合IDを取得
matches = get_player_matches(profile_uuid="...", queue="competitive", limit=20)
match_ids = [m["match_id"] for m in matches["results"]]

# リテイク率を集計
get_retake_stats(match_ids=match_ids)

推奨フロー

1. get_player_matches または search_matches で match_id のリストを取得
2. リストをそのまま get_retake_stats に渡す
3. マップ・サイト別にリテイク成功率が返ってくる

プロ試合のリテイク率を調べる場合は search_esports_matches から試合IDを集めることも可能です。

注意

round_results に bomb_planter が存在するラウンドのみカウントされます。スパイクが植えられなかったラウンドは除外されます。