⚠️ 新しいGraphQL公開APIのアルファ版が登場しました。詳しくは新しい開発者ポータルをご覧ください。⚠️
以下で説明する旧APIは、新APIの開発期間中も引き続き利用できます。ただし、旧APIは将来的に廃止される予定なので、アプリケーションはできるだけ新APIで構築することをおすすめします。新APIは完全に別物であり、以下の情報は旧APIにのみ当てはまります。
REST APIの概要
smashggのREST APIは、現時点では最終版でも「正式公開」されたものでもありません。REST APIは予告なく変更される可能性があります。ご利用は自己責任でお願いします。
REST APIの基本概念
基本的に、REST APIのオブジェクト（大会、ブラケットなど）には api.start.gg/objectType/objectId という形式でアクセスします。オブジェクトに紐づくデータを取得しやすいように、expandという特別なパラメータを用意しています。これは各値が文字列の配列フィールドです。使えるexpandオプションはオブジェクトのタイプによって異なります。
たとえば、ある大会をそのすべてのイベント付きで取得するには https://api.start.gg/tournament/pulsar-premier-league?expand[]=event とします。大会のフェーズも含めたい場合は https://api.start.gg/tournament/pulsar-premier-league?expand[]=event&expand[]=phase とします
オブジェクト
-----------
大会（Tournaments）
大会はわかりやすいオブジェクトですが、REST APIでのアクセス方法が他のオブジェクトと大きく異なる点があります。大会にはスラッグ（大会ページのURLから取得できます）でアクセスします。例：https://api.start.gg/tournament/pulsar-premier-league
Expandオプション
event - 大会内のすべてのイベントを返します
phase - 大会内のすべてのフェーズを返します
groups - 大会内のすべてのフェーズグループを返します
stations - 大会内のすべてのステーション/配信を返します
イベント（Events）
イベントは必ず大会の中に含まれ、エントリーできるゲーム（例：Rocket League）と種目タイプ（例：Teams）を表します。イベントのIDがわかっていれば https://api.start.gg/event/eventId でアクセスできます。イベントのスラッグ（例：melee-singles）とその大会のスラッグ（例：the-big-house-6）しかわからない場合は、https://api.start.gg/tournament/the-big-house-6/event/melee-singles のようにアクセスできます。
Expandオプション
phase - 大会内のすべてのフェーズを返します
groups - 大会内のすべてのフェーズグループを返します
フェーズ（Phases）
フェーズはブラケットのコンテナです。1つのイベントは0個以上のフェーズを持てます。たとえば多くの大会では、多数のブラケットを含むプールフェーズがあり、そこから単一の決勝ブラケットフェーズへ勝ち上がる形になっています。
Expandオプション
groups - フェーズ内のすべてのフェーズグループを返します
フェーズグループ（Phase Groups）
フェーズグループは、要するにブラケットのことです。タイプはシングルイリミネーション、ダブルイリミネーション、総当たり（ラウンドロビン）のいずれかです。フェーズグループにはセットが含まれます。フェーズグループへのアクセス方法：https://api.start.gg/phase_group/phaseGroupId.
Expandオプション
sets - フェーズグループのすべてのセットを返します
entrants - フェーズグループのすべてのエントラントを返します
standings - seedsのexpandと併用すると順位データを返します
seeds - standingsと併用して順位データを取得します。ブラケットのシードも取得できます。
例
フェーズグループIDは、通常ブラケットURLの最後の数字です。
セット（Sets）
セットは、ブラケット（フェーズグループ）内の個々の試合です。セットにはentrant1Idとentrant2Idというフィールドがあり、そのセットで対戦するエントラントを表します。どちらかがnullの場合、そのセットは不戦勝（bye）です。
セットタスク（Set Tasks）
タスクはオンラインイベントでのみ使われます。セットをプレイする際に各エントラントが行うべきことのまとまりです。タスクによっては、エントラント内の1人以上の参加者による操作が必要になることもあります。
プレイヤー（Players）
プレイヤーは、サイト全体を通した個人の表現です。プレイヤーが大会にエントリーすると、そのプレイヤーと大会に対応するParticipant（参加者）が作成されます。
参加者（Participants）
Participantは、ある大会におけるプレイヤーの表現です。
エントラント（Entrant）
エントラントは、イベントにおける参加者（1人以上）のコンテナのようなものです。ブラケットに表示されるのはこのエントラントです。エントラントは、自身に含まれる参加者IDの配列を持ちます。
シード（Seeds）
シードはフェーズレベルの概念で、フェーズ内のブラケットにエントラントをどこに配置するかを決めるために使われます。シードには省略可能なentrantIdと、全体の
ステーション/配信（Stations/Streams）
大会主催者は、試合を整理するためにステーション（例：オフラインイベントの個々の対戦台やそのグループ）や配信（例：Twitch配信）を追加できます。大会のステーションと配信を確認するには、
配信キュー（Stream Queues）
セット（およびフェーズグループ全体）は配信に割り当てて、プレイ順に並べることができます。プレイ順の変更は、現在配信に対してのみサポートされています。大会の各配信でプレイ予定のセット一覧を取得するには、次のルートを使います：https://api.start.gg/station_queue/tournamentId（tournamentIdは大会のREST APIレスポンスから取得できます）。レスポンスにはqueuesフィールドがあり、配信IDからセットIDの配列へのマッピングになっています。レスポンスのdataフィールドには、キュー内のすべてのセットと配信のエンティティに加えて、キュー内のセットに関連するイベント、フェーズ、フェーズグループ、エントラント、プレイヤーのデータが含まれます。
例1
オンラインのチーム戦ブラケットで上位の順位を取得し、さらに各試合にチェックインした各チームのプレイヤーを知りたいとします。
まず、大会のイベント、フェーズ、フェーズグループ（ブラケット）を取得して、目的のブラケットのIDを調べます：https://api.start.gg/tournament/pulsar-premier-league?expand[]=phase&expand[]=groups&expand[]=event
順位とチェックインデータが欲しいフェーズグループ（ブラケット）のID（例：178064）がわかったら、次のようにして順位とブラケット内のセットを取得できます：https://api.start.gg/phase_group/178064?expand[]=sets&expand[]=standings&expand[]=seeds 。standingsエンティティにアクセスすると、各エントラントの順位を取得できます。
ブラケット内の個々のセットのチェックイン情報を取得するには、先ほどのREST APIリクエストのsetsエンティティからセットID（例：4761484）を取得し、https://api.start.gg/set/4761484?expand[]=setTask を実行します。セットのタスクはsetTaskエンティティに含まれます。チェックインタスクはtypeの値が1です。タスクのチェックインデータは、タスクのmetadataフィールドに含まれます。
例2
目標：イベント全体の現在の順位と、イベント内の各ブラケットの順位を取得する
イベント順位は、イベント全体のすべてのブラケットとフェーズを対象とします。ブラケット順位は、単一のブラケットのみが対象です。ブラケット順位とイベント順位では、アクセス方法が少し異なります。
単一ブラケットの順位を取得するには https://api.start.gg/phase_group/323872?expand[]=standings&expand[]=seeds を使い、レスポンスのstandingsフィールドを見ます。各standing項目には便利なフィールドがいくつかあります：
seedId は、この順位が対応するシードのIDです。シードの詳細は、レスポンスのseedsオブジェクトを確認してください
entrantId は、この順位が対応するエントラントのIDです。エントラントはイベント固有なので、チームやプレイヤーを同じイベント内の他のリザルトと結び付けるのに便利です。
placement は、ブラケットでの実際の順位です
pendingPlacement は、シード番号順に並べたブラケット内の順位です。たとえばウィナーズ側から2人抜けの場合、両エントラントとも順位は2位タイになりますが、pendingPlacementでは上位シードのエントラントが1、下位シードのエントラントが2になります。
イベントの順位を取得するには https://api.start.gg/tournament/cheeseadelphia-4-1/event/starcraft-ii-legacy-of-the-void-singles/standings?entityType=event&expand[]=entrants&mutations[]=playerData&mutations[]=standingLosses&page=1&per_page=25 を使います。順位は昇順にソートされ、上位のエントラントから順に表示されます。このURL構造について、いくつか補足します：
基本構造は /tournament/touranment-slug/event/event-slug/standings なので、お使いの大会/イベントに合わせて調整してください
イベント順位はページネーションされているため、イベントの全順位を取得するにはpageパラメータを変えながらリクエストする必要があります
上記のexpandとmutationsをURLに含めると、standingオブジェクトやentrantオブジェクトに、敗北数やプレイヤーデータなどの追加フィールドが付きます。
例3
目標：ブラケットの試合結果を取得する
先ほどと同じexpand（setsとseeds）を使って、このREST APIエンドポイントを利用します：https://api.start.gg/phase_group/323872?expand[]=sets&expand[]=seeds
レスポンスには、ブラケットのすべてのセットが含まれます。各セットには便利なフィールドがいくつかあります：
entrant1Id と entrant2Id は、そのセットで対戦したエントラントを表します
entrant1Score と entrant2Score は、各エントラントのゲームスコアを表します
winnerId と loserId には、完了したセットの勝者と敗者のentrantIdが入ります
stationId は、そのセットが割り当てられたステーションや配信を表します
state は試合のステータスです。1は未開始、6は呼び出し済み、2は開始済み、3は完了です。
各エントラントの名前を取得するには、レスポンスのseedsエンティティを使います。各シードはエントラントと1対1で対応しています。各シードにはmutationsフィールドがあり、そのシードに関連するオブジェクトの追加情報が入っています。たとえば上記のレスポンスでは、シードにparticipant、player、entrantsのmutationsがあるのが確認できます。シングルスのイベントでは、エントラントと参加者はほぼ同じものです。チーム戦イベントでは、エントラント（チーム）は複数の参加者で構成されます。プロフィール画像やランキング情報など、参加者についてより詳しい情報が必要な場合は、playersフィールドを使ってください。
例4
目標：リーグのすべてのサブリーグを取得する
リーグ内のすべてのサブリーグのIDを取得するには、https://api.start.gg/tournament/[league-slug]?expand[]=tagsByContainer を使い、レスポンスの「entityContainerTag」フィールドを見ます。
このオブジェクトは非常にシンプルで、あるエンティティが別のエンティティを含んでいることを表しているだけです（なお、リーグは内部的には大会として表現されるため、レスポンス内でのタイプは常に「tournament」になります）：
containerType と containerId：含む側エンティティのタイプとそのID。上記リクエストで返ってくるすべてのentityContainerTagでcontainerIdは同一になり、リクエストしたリーグのIDになります
entityType と entityId：含まれる側エンティティのタイプとそのID。entityTypeが「tournament」の場合、それはリクエストしたリーグのサブリーグです。entityTypeが「event」になることもあり、その場合はリクエストしたリーグ直下のイベントを表します
ID以外のサブリーグの詳しい情報も欲しい場合は、https://api.start.gg/tournament/[league-slug]?expand[]=visibleEntityContainerTag を使えます。これは、リーグとそのサブリーグのすべての「entityContainerTag」に加えて、それらの「entityContainerTag」に関連する大会やイベントも返します。
例：「brawlhalla-circuit」のすべてのサブリーグが欲しいので、https://api.start.gg/tournament/brawlhalla-circuit?expand[]=tagsByContainer を使うと、次のようなレスポンスが返ってきます：
これで、「brawlhalla-circuit」にはID 6755、6756、6763、6762の4つのサブリーグがあることがわかりました。次に https://api.start.gg/tournament/brawlhalla-circuit?expand[]=visibleEntityContainerTag を使い、「tournament」配列からこれらのIDを持つオブジェクトを探せば、各サブリーグの詳しい情報を取得できます。
例5
目標：リーグの順位を取得する
リーグの順位を取得するには、https://api.start.gg/standing/[league-slug]/getAllEvents?expand[]=participants&mutations[]=playerData を使い、レスポンスの「standing」配列を見ます。各standing項目には便利なフィールドがいくつかあります：
entityType と entityId：順位を持つエンティティのタイプ（例：「player」）と対応するIDです。後述のとおり、さらに詳しい情報を取得するのに使えます
standing：そのエンティティのリーグ内での順位です
points：この順位に紐づくポイント数です
containerType と containerId：containerTypeは順位の対象となるエンティティのタイプ（リーグは内部的には大会として表現されるため、リーグの場合は「tournament」になります）、containerIdはそのエンティティのIDで、対象のリーグについて詳しい情報を取得するのに使えます
重要な注意点として、サブリーグを含むリーグにアクセスする場合、デフォルトでは各サブリーグの上位3件の順位しか取得されません。この挙動は、省略可能な「top」パラメータを追加することで変更できます。
例：https://api.start.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 を使うと、各サブリーグの上位10件の順位を取得できます。
順位に紐づくエンティティ（例：「player」）の情報を取得するには、standingのentityTypeとentityIdを見て、レスポンス内の対応するデータオブジェクトにアクセスします。
例：https://api.start.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 を使い、下図のように「standing」配列の最初の「standing」を選びます。
「entityType」を見ると、この順位は「player」に紐づいているので、詳しい情報は「player」配列を見ればよいとわかります。必要になるのは「player」の「id」、つまりこの順位の「entityId」である11838です。
次に、レスポンスの「player」配列からID 11838のオブジェクトを探すと、そのプレイヤーに関するすべての情報を取得できます（下図参照）。
リーグの順位についてさらに詳しい情報を取得するには、リーグのIDが必要です。目的のサブリーグのIDの取得方法は、上の例4をご覧ください。IDがわかったら、https://api.start.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData を使えます。デフォルトでは上位25件の順位が返ってきます。この挙動は、省略可能な「per_page」パラメータで変更できます（例：https://api.start.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations=playerData&per_page=50）。
「standing」配列は先ほどと同じですが、今回は「standingPoints」配列が追加されており、次のような特徴があります：
sourceType と sourceId：これらのフィールドはポイントの出どころを表します。sourceType=”event”でsourceId=123なら、そのポイントはID 123のイベントから付与されたものです
standing：「event」の場合、この数字はそのポイントが付与される、イベント内での順位を表します
quantity：この順位に付与されるポイント数です
ポイントが直接付与されるような特殊なケースを除き、sourceType=”event”の「standingPoints」だけに注目すると、「standingPoints」はもっとシンプルに説明できます。つまり、あるイベントの「standingPoints」は、そのイベントのポイント構成を表しているのです。
例：ID 12345のイベント「example-event」があり、1位に100ポイント、2位に50ポイント、3位に25ポイント、4位に10ポイント、5位に5ポイントを付与すると決めたとします。この場合、standing pointsは次のような形になります（この例に関係のないフィールドは省略しています）。
"standingPoints": [
{"id": 123, "sourceType": "event", "sourceId": 12345, "quantity": 100, "standing": 1},
{"id": 124, "sourceType": "event", "sourceId": 12345, "quantity": 50, "standing": 2},
{"id": 125, "sourceType": "event", "sourceId": 12345, "quantity": 25, "standing": 3},
{"id": 126, "sourceType": "event", "sourceId": 12345, "quantity": 10, "standing": 4},
{"id": 127, "sourceType": "event", "sourceId": 12345, "quantity": 5, "standing": 5}
]
重要なのは、このイベントがシンプルなダブルイリミネーションブラケットで終わった場合、5位の人が2人になることがありますが、5位に対応する「standingPoint」のエントリは1つしかないという点です。「standingPoints」は、どの順位にどのポイントが対応するかを表すルックアップテーブルのような役割だからです。このイベントで5位になった2人のエントラントの「standing」オブジェクトを見ると、どちらも「pointIds」配列にID 127を持っているはずです。
例：これまでに説明した方法で、「Brawlhalla Circuit」のサブリーグ「United States 1v1」のIDが6755だとわかったとします。次に https://api.start.gg/standing/tournament/6755/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData を使うと、以下のレスポンスが得られます：
ここで、順位1のプレイヤーがどのイベントからポイントを獲得したのか、そのイベントで何位だったのか、そして何ポイント獲得したのかを知りたいとします。まずは「standing」が1のstandingを見てみましょう。
この順位は350ポイントで構成されており、「pointIds」配列にエントリが1つしかないため、350ポイントすべてがその1つの「standingPoints」オブジェクトから来ているはずです。そこで、ID 4627の「standingPoints」オブジェクトを探します。
これらのポイントの出どころは、ID 23910の「event」だとわかります。命名のせいで少しわかりにくいのですが、ここでの「standing」フィールドは、そのイベントで1位になった人にこれらのポイントが付与されるという意味です。「standingPoints」は単にイベントのポイント構成を表している、ということを思い出してください（前の例で説明したとおりです）。最後に、このイベントについて詳しく知りたい場合は、https://api.start.gg/event/eventId のルートを使います。https://api.start.gg/event/23910 にアクセスすると、次のレスポンスが得られます：
