サジェストAPI

サジェストワード一覧の取得

リクエスト

HTTPメソッド GET
エンドポイント /api/v2/suggest-words

Fess に、 http://<Server Name>/api/v2/suggest-words?q=fes のようなリクエストを送ることで、入力したプレフィックスに対するサジェストワードの一覧をJSON形式で受け取ることができます。

サジェストワードには次の3つの生成元があります。

  • ドキュメント — クロールしたドキュメントから生成されます。取得するには、管理画面の システム > 全般 で「ドキュメントでサジェスト」を有効にする必要があります。

  • 検索語（検索ログ） — ユーザーの検索ログから生成されます。取得するには、管理画面の システム > 全般 で「検索語でサジェスト」を有効にする必要があります。

  • ユーザー辞書 — 管理者が登録したサジェストワードです。上記の設定に関わらず常に返されます。

「ドキュメントでサジェスト」「検索語でサジェスト」が無効の場合でも、APIはエラーにはならず、対象のサジェストワードが結果に含まれないだけです。 また、サジェストワードはリクエスト元ユーザーのロールに基づいて自動的にフィルタリングされます。

レスポンスの共通エンベロープおよびエラーモデルについては APIの概要 を参照してください。

リクエストパラメーター

使用できるリクエストパラメーターは以下の通りです。

リクエストパラメーター
q サジェストを行う検索語（プレフィックス）。省略した場合は、プレフィックスによる絞り込みを行わずにサジェストワードを返します。 (例) q=fes
num サジェストされる単語の数（0以上の整数）。デフォルト 10 。数値以外を指定した場合はデフォルト値が使用されます。 (例) num=20
fn サジェスト対象を絞り込むフィールド名。繰り返し指定することで配列として扱われます。 (例) fn=content&fn=title
lang 検索言語の指定。繰り返し指定することで配列として扱われます。 (例) lang=en
label フィルターするラベル（タグ）名。繰り返し指定することで配列として扱われます。指定した値は、各サジェストワードの types に対して照合されます。 (例) label=java

注釈

v2 では、フィールド名の指定は fn パラメーターです（v1 の fields ではありません）。 fn は値をカンマ区切りで列挙するのではなく、パラメーターを繰り返し指定して複数の値を渡します。

レスポンス

成功時には、以下のような共通エンベロープ形式のレスポンスが返ります。

{
  "response": {
    "status": 0,
    "q": "fes",
    "page_size": 10,
    "record_count": 355,
    "query_time": 18,
    "suggest_words": [
      {
        "text": "fess",
        "types": [
          "label1"
        ]
      }
    ]
  }
}

response の各要素については以下の通りです。

レスポンス情報
q リクエストされた検索語（文字列）。 q を省略した場合は空文字列になります。
page_size リクエストされたサジェスト単語数（ num の値、整数）。
record_count サジェストワードの該当総件数（64ビット整数）。
query_time クエリ処理時間。単位はミリ秒（64ビット整数）。
suggest_words サジェストワードの配列。各要素は text と types を持ちます。
text サジェストワード（文字列）。
types サジェストワードに紐づくタグの配列（文字列の配列）。各タグはドキュメントの label ・ virtual_host フィールドの値、または検索ログから抽出されたフィルター条件に由来します。タグがない場合は空配列になります。

注釈

types には、サジェストワードの種別（ document ・ query などの種別値）ではなく、タグの値が格納されます。この配列は v1 のサジェスト項目の labels フィールドに相当します。 label リクエストパラメーターは、この types の値に対してフィルタリングを行います。

使用例

curlコマンドでのリクエスト例:

curl "http://localhost:8080/api/v2/suggest-words?q=fes"

エラーレスポンス

サジェストAPIが失敗した場合、共通のエラーエンベロープが返されます。エラーモデルの詳細は APIの概要 を参照してください。

エラーレスポンス
ステータスコード 説明
405 Method Not Allowed サポートされていない HTTP メソッドが指定された場合。 Allow ヘッダーに GET が示されます。
500 Internal Server Error サーバー内部エラーが発生した場合。