公開API は、組織の管理者に組織のライブデータへの直接のHTTPアクセスを提供します — HTTPリクエストを行える任意のウェブサイト、アプリ、ボット、または自動化に取り込めます。これは ビジネスプラン の機能です。
キーはあなたの組織にスコープされています — すべてのエンドポイントは自動的にそのグループを対象に動作します。ベースURL: https://api.ludoya.com/public/v1。認証ヘッダー: X-Api-Key: YOUR_KEY。レート制限: 1分あたり100リクエスト。超過後は 429 が返されます。
キーは ldy_ で始まり、36文字です。設定ファイルでも見つけやすく、万一不適切な場所に露出した場合でもスキャンで検出しやすい形式です。パスワード同様に扱ってください。サーバーサイドのみで使用し、漏えいした場合は同じページから失効してください。
アクセスできる内容
- 場所 — グループで利用可能な場所とそのスポット。イベント作成時の入力として使用します
- イベント（読み取り） — タイトル、説明、日時、タイムゾーン、定員、参加者数、ステータスを含む、今後および過去のイベント
- イベント（書き込み） — POST と PUT でイベントを作成・更新。場所、定員、権限、公開範囲、画像を完全に制御
- サブイベント — 親イベント内にネストされたイベントを一覧表示
- 参加者 — イベントへの追加、出欠の変更、削除
- メンバー — ユーザープロフィールと役割（オーナー、管理者、メンバー）を含むメンバー一覧。ページネーション対応
- 招待 — グループに招待を送る
- 検索 — Ludoya のユーザーやボードゲームカタログを検索し、書き込み前に名前をIDへ解決
- コレクション — 所有状況、名前、プレイヤー人数、リストでフィルタ可能なゲームのコレクション。並べ替えとページネーションに対応。各ゲームには BGG のメタデータを含みます
- 統計 — 任意期間のプレイ記録の統計。合計、平均、勝利数やスコアによる上位プレイヤー、プレイヤー人数別の内訳、場所別、ゲーム別
- キャンペーン（読み取り） — メンバー数とセッション数付きでグループのキャンペーンを一覧表示。メンバー、過去のセッション、予定されているイベントを含む完全なキャンペーン詳細を取得
- キャンペーン（書き込み） — グループ向けのキャンペーンを作成し、名前、説明、ステータス、公開範囲を更新
- キャンペーンメンバー — キャンペーン内のメンバーの追加、更新、削除
エンドポイント
GET /locations
グループで利用可能な場所を返します。各場所には id、name、任意の address、capacity、isDefault フラグ、および spots 配列（各スポットには独自の id、name、capacity があります）が含まれます。イベントを作成する際は、場所IDとスポットIDを使用してください。
Ludoya でサインイン
API キーが表示される同じページで、あなたの組織をサインインプロバイダーにすることもできます。利用者は自分の Ludoya アカウントであなたのウェブサイトやフォーラム、コミュニティプラットフォームにログインでき、別途パスワードを覚える必要も、あなたがユーザーデータベースを運用する必要もありません。
導入する理由
誰かがサインインを承認すると、その人はあなたの組織に関連付けられます。グループの参加ポリシーに応じて、（オープンの場合は）すぐにメンバーになる、（参加申請制の場合は）管理者の承認用に参加申請を送信する、（招待制の場合は）参加せずにサインインのみ行う、のいずれかになります。いずれの場合でも、その人は他の人と同様に /members エンドポイントに表示されるため、あなたのウェブサイトのログインと Ludoya のメンバー一覧は自動的に同期状態を保てます。
設定方法
標準的な OpenID Connect なので、ほとんどのプラットフォームでは発行者 URL とクライアント ID・シークレットさえあれば十分です。Public API ページからアプリケーションを登録してこれらの認証情報を取得し、サイトで使用するリダイレクト URIを列挙してください。複数登録できますが、各 URI はサイトが送信する redirect_uri と末尾のスラッシュも含めて文字単位で完全一致している必要があります。わずかな不一致が、初回のサインイン試行が失敗する最も一般的な原因です。
- Discourse — OpenID Connect プラグインをインストールし、ディスカバリー URL を貼り付けて、認証情報を追加
- WordPress — 任意の汎用 OpenID Connect プラグインを使用し、その「自動検出」オプションを有効化
- その他 — OIDC に対応していれば、発行者 URL を指定すれば自動設定されます
各サインインでは、その人の永続的な識別子、ユーザー名、表示名とアバター、そしてメールアドレスが返されます。手動フローを含む完全な設定手順は、アプリ内の開発者向けガイド「開発者 → Ludoya でサインイン」にあります。
サインインする人向け
どこかで Ludoya を使ってサインインしたことがある人は、設定 → 連携アプリ でそれらの連携を閲覧し、各連携の接続日時と最終利用日時を確認し、いつでも任意の連携を切断できます。切断すると、そのサイトからのアクセスは即時に無効化されますが、あなたのグループからは削除されません。
GET /events
今後および過去のイベントを、別々のページングされたリストで返します。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
onlyFuture |
ブール値 | true |
過去のイベントも返すには false を設定します |
各イベントに含まれる項目: type (MEETUP または PLANNED_PLAY)、title、description、startsAt、endsAt、timeZone、imageUrl、capacity、participantCount、canceled、teacher（ユーザーオブジェクトまたは null）、master（ユーザーオブジェクトまたは null）。ユーザーオブジェクトには id、username、name、avatarUrl が含まれます。
POST /events
グループ内にイベントを作成します。必須フィールド: type と title。locationId を省略した場合は、グループの既定の場所が使用されます。存在しない場合は 400 を返します。
任意フィールドには次が含まれます: description, locationId, spotId, gameId, parentEventId（サブイベント用）, startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image。
image フィールドは {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."} のいずれかを受け付けます。最大 5 MB。
ステータス 201 で {"id": "string"} を返します。
PUT /events/{eventId}
既存のイベントを更新します。リクエストボディの形式は POST と同じで、変更したいフィールドのみを含めてください。呼び出し元はイベントの主催者（グループアカウント）である必要があります。空のボディで 202 を返します。
GET /events/{eventId}
ID で指定した単一のイベントを取得します。戻り値の構造は GET /events のエントリと同一です。
GET /events/{eventId}/children
親イベント内にネストされた子イベント（大規模な集まりにおける個別のトラックやセッション）を一覧します。各子イベントは通常のイベントと同じ構造です。
参加者の管理
3つのエンドポイントにより、Ludoya の外部からイベントの参加者リストを管理できます—申し込みが自分のウェブサイトで行われる場合や、既存のリストをインポートする場合に便利です。
| メソッド | パス | 機能 |
|---|---|---|
POST |
`/events/ |
GET /members
ページネーションされたメンバー一覧を返します。
| パラメータ | 型 | 既定値 |
|---|---|---|
pagination.size |
int | 50 |
pagination.offset |
int | 0 |
各メンバーには次が含まれます: id, username, name, avatarUrl, role (OWNER, ADMIN, または MEMBER)。
POST /members/invite
あなたのグループに誰かを招待します。このエンドポイントは username を直接受け付けます — ID の検索は不要です — ので、独自のサイトや管理ツールからそのままメンバーを追加できます。
GET /search/users と GET /search/boardgames
2 つの検索用エンドポイント。ほとんどの書き込み操作では名前ではなく id が必要で、これらを使って取得します。
GET /search/users
| パラメータ | 型 | 既定値 |
|---|---|---|
query |
文字列 | 必須 |
intent |
文字列 | — |
pagination.size |
整数 | 20 |
pagination.offset |
整数 | 0 |
GET /search/boardgames
| パラメータ | 型 | 既定値 |
|---|---|---|
query |
文字列 | 必須 |
filter |
文字列 | — |
pagination.size |
整数 | 50 |
pagination.offset |
整数 | 0 |
ゲームのフィルターは、コレクションのフィルターと同じ、セミコロン区切りの key=value 形式を取り、プレイ人数、プレイ時間、複雑度、年、対象年齢、またはタグでカタログを検索できます。
GET /collection
フィルタ、並べ替え、ページングに対応したあなたのゲームコレクションを返します。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
filter |
string | — | セミコロン区切りの key=value のペア。キー: ownership (OWNED, PREVIOUSLY_OWNED, PREORDERED, WISHLISTED)、played (boolean)、listId、nameFilter、playerCountFilterType (OFFICIAL, GOOD, BEST)、playerCountFilter (number) |
groupExpansions |
boolean | true |
拡張をベースゲームの下にグループ化します |
sort |
string | — | 形式: property,direction — 例: name,asc |
pagination |
string | — | 形式: size,pageIndex — 例: 20,0 |
レスポンス: totalGames, totalExpansions, games[] — 各要素には id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount が含まれます。
GET /stats
設定可能な期間のプレイ記録統計を返します。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
period |
string | ALL_TIME | 形式: PERIOD,date,index。値: ALL_TIME, ONE_YEAR, ONE_MONTH, THIRTY_DAYS, SEVEN_DAYS, ONE_DAY, CUSTOM。index はウィンドウを過去にずらします（0 = 現在、1 = 直前）。カスタム: CUSTOM,startDate,0,endDate |
レスポンスに含まれるもの:
- 概要 — 合計プレイ記録数、総／平均プレイ時間、および一意のゲーム・プレイヤー・場所の数
- プレイヤー別 — 各人のプレイ記録数、勝利数、平均スコアと最高スコア
- プレイヤー人数別 — 2人プレイ、3人プレイ、4人プレイなどの内訳
- 場所別 — 場所ごとのプレイ記録数と一意のゲーム数
- ゲーム別 — タイトルごとのプレイ記録数、総／平均プレイ時間、および一意のプレイヤー数
GET /campaigns
グループに属するキャンペーンのページ分割された一覧を返します。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
status |
string | — | 状態で絞り込み: ACTIVE、COMPLETED、またはARCHIVED |
pagination.size |
int | 50 | ページあたりのアイテム数 |
pagination.offset |
int | 0 | オフセット |
各キャンペーンに含まれる項目: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.
GET /campaigns/{campaignId}
グループに属するキャンペーンの詳細全体を返します。
レスポンスに含まれる内容: リストのすべてのフィールドに加えて、template、description、globalNotes、globalState、members[]（各要素は user、role、characterNotes、characterState を含む）、sessions[]、および events[]。
POST /campaigns
グループ向けのキャンペーンを作成します。必須フィールド: gameId と name。省略した場合、公開範囲の既定値はグループメンバーのみ（ONLY_GROUP）です。
任意フィールド: templateId、description、visibility（PUBLIC、ONLY_GROUP、ONLY_FRIENDS、または PRIVATE）。
ステータス 201 で {"id": "string"} を返します。
PUT /campaigns/{campaignId}
既存のキャンペーンを更新します。すべてのフィールドは任意です。変更したい項目だけを指定してください。
任意のフィールド: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility。
空のボディで202を返します。
キャンペーンのメンバー
キャンペーンのメンバーは、イベントの参加者と同様の方法で管理します。
| メソッド | パス | 機能 |
|---|---|---|
POST |
`/campaigns/ |
エラーコード
| ステータス | 発生条件 |
|---|---|
| 400 | 検証エラー（必須項目の欠落、場所が見つからない、無効な画像） |
| 401 | APIキーがない、または無効 |
| 403 | 操作が許可されていない、またはグループが Business プランに加入していない |
| 404 | リソースが見つからない |
| 429 | レート制限を超過 |
はじめに
1. API キーを生成する
- 組織のプロフィールページに移動します
- メニュー（⋮）→ 公開 API をタップします
- キーを生成 をタップします
- 今すぐキーをコピー — 一度しか表示されず、再取得はできません
キーは組織に紐づいています。秘密にしてください。キーを持っている人は上記のすべてのデータを読み書きできます。
2. 失効または再生成
既存のキーを失効するには、公開 API ページに戻り、失効 をタップします。ダイアログで確認してください。古いキーを使用しているシステムは、直ちに 401 エラーを受け取り始めます。新しいキーを発行するには、もう一度 キーを生成 をタップします。
関連: