# Webカタログ検索API（β）

Webカタログに登録された出店・作品を検索する公開APIです。HTMLレンダリングの負荷を軽減するアクセス経路として、読み取り専用MCPサーバを推奨のアクセス方法として提供しています。JSON APIは、MCPを利用できない環境などで使える任意の代替手段です。

## 検索できる情報

- 開催回ごとの本・作品・出店
- テーマやジャンルに関連する作品
- 著者、創作者、サークル、出店者の登録情報
- ブース番号、ページ数、書影、価格など

情報は開催回ごとに登録されています。カタログへの掲載は、現在の在庫や当日の入手可能性を保証するものではありません。

## MCP（推奨）

- 接続先：同じサイトの `/c/api/v1/mcp`
- 通信方式：Streamable HTTP（2025-06-18）
- 認証：不要、読み取り専用
- [MCP接続設定・ツール仕様](/api-catalog.md)

公開ツール：

- `list_events`: 利用可能な開催回の名称・日時・会場・略称（`abbrev`）を返します。
- `search_catalog`: 開催回と検索条件を指定し、出店・作品を検索します。

引数は各ツールのJSONスキーマに定義されています。MCPエンドポイントは、MCP対応クライアントがJSON-RPCをPOSTで送る接続先です。通常のWeb閲覧によるGET検索用URLではありません。

このファイルの相対リンクとパスは、取得元サイトを基準としています。公開情報の検索にログインやAPIキーは不要です。

## 検索結果の構造

- `results`: 検索条件に一致した結果の配列。空の配列は、その条件で一致する結果がなかったことを表します。
- `entry`: 出店情報。
- `item`: 作品情報。nullの場合、当該結果には作品情報がありません。
- `item.images.medium`: 登録された書影のURL。画像の登録がない場合は仕様書記載の形式で返します。
- `web_url`: 結果に対応する公式カタログページのURL。相対URLの基準は取得元サイトです。
- `count`: 上限付きの件数であり、全件数を保証するものではありません。

APIが返す登録情報と、作品の推薦・解釈は別のものです。取得エラーは検索結果が空であることを意味しません。

## 利用条件

同じ検索条件・ページ・並び順の結果には一定時間のキャッシュが必要です。HTMLページの巡回による収集や、全件取得を目的とする条件分割・ページ巡回は禁止しています。レート制限、ページ指定、キャッシュの詳細は仕様書に記載しています。

公開情報の検索は認証不要です。「気になる！」の登録状態を扱う機能は本人のログインが必要で、ログインセッションのユーザー間共有は認めていません。

検索APIはWebカタログ公開開始からイベント終了7日後まで（カタログ公開終了が先ならその時点まで）利用できます。イベント一覧APIは利用可能な開催回だけを返し、該当する開催回がない場合は空の一覧になります。この案内と仕様書は期間外でも参照できます。

## Optional: GETのJSON API

[イベント一覧API](/c/api/v1/events)は `GET /c/api/v1/events`、開催回ごとの検索は `GET /c/api/v1/{abbrev}/search/results` です。GETのJSON APIはMCPへの接続設定なしで利用できます。

検索URLの例：

```text
/c/api/v1/{abbrev}/search/results?s=他者,表象,言説&per_page=10
```

`{abbrev}` はイベント一覧に含まれる開催回の略称を表すプレースホルダーです。この例では「他者」「表象」「言説」のいずれかを含む出店・作品を検索します。

キーワードの区切りは `,` がOR、`+` がANDです。個々の語はURLエンコードできます。区切り自体を `%2C` や `%2B` にすると、区切りではなく検索する文字として扱われます。