クエリの最後のワードの候補を取得する

このチュートリアルでは、API で用語補完をどのように提案するかを示します。

手順

ポツダムからの道中、ベルリンミッテでファストフードレストランのBurger Kingを検索しているユーザーがクエリの入力を開始すると、 queryTermsにクエリ用語の補完候補が表示され、さらに5つの位置情報とフォローアップクエリの候補がitemsに表示されます。

不完全なクエリ「Bur」の場合、「BURGER」、「Burgermeister」、「Burg」といったクエリ用語の補完候補と、その他の関連する位置情報の候補も表示されます。

以下はその例と、/autosuggestエンドポイントのクエリセッションおよびクエリ用語の補完の例です。

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=52.43414,13.19315
    &q=bur&lang=en
    &limit=5
    &termsLimit=3
    &apiKey={YOUR_API_KEY}

{
  "queryTerms": [
    { "term": "BURGER", "replaces": "bur", "start": 0, "end": 3 },
    { "term": "Burgermeister", "replaces": "bur", "start": 0, "end": 3 },
    { "term": "Burgunder", "replaces": "bur", "start": 0, "end": 3 }
  ],
  "items": [
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u336k-616d8703c79e45c28af2e3c4d322a724",
      "resultType": "place",
      ...
    },
    {
      "title": "Burgermeister",
      "id": "here:pds:place:276u33d9-ae15f7d5f65b470db3c93e9415f895e5",
      "resultType": "place",
      ...
    },
    {
      "title": "Burgunder Straße, 14129 Berlin, Germany",
      "id": "here:af:street:NxklGXv1cSEovzhnxdHxGB",
      "resultType": "street",
      ...
    },
    {
      "title": "Burg, Sachsen-Anhalt, Germany",
      "id": "here:cm:namedplace:20196144",
      "resultType": "locality",
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u3364-46972bb96b804b36a83f074d5213cd2e",
      "resultType": "place",
      ...
    }
  ]
}

次のパラメーターを使用します。

at - 座標で表される検索コンテキストの中心を指定します。
q - 名前を入力します。
limit - 返される結果の最大数。
termsLimit - 返されるクエリ用語候補の最大数。
apiKey - APIキー。

📘
注
このリクエストはAPIキー認証を使用します。HEREプラットフォームの認証オプションの詳細については、「Identity & Access Management Guide」(IDとアクセス管理ガイド)を参照してください。

エンドユーザーが提案された用語「BURGER」を選択すると、アプリケーションはqパラメーターの「bur」を「BURGER」に置き換え、不完全なクエリを続行します。

次に、エンドユーザーが「k」と入力して「BURGER k」というクエリになると、/autosuggestエンドポイントはエンドユーザーが使用できる用語候補として「KING」を返します。

完全なクエリ入力/completionセッションの例は次のとおりです(BKはBURGER KINGの略です)。

ユーザーアクション	`q`	`queryTerms[].term`	`items[]`
ユーザーが「bu」と入力	`bu`	`"Buckow"`、`"Budapest"`、`"Bülowstrasse"`	「bu」で始まる都市
ユーザーが「r」と入力	`bur`	`"BURGER"`、`"Burgermeister"`、`"Burg"`	近くの BK とその他の位置情報
ユーザーが「BURGER」を選択	`BURGER`	`"Burgermeister"`、`"Bürgeramt"`、`"Burgersaal"`	(idem)
ユーザーが「」と入力	`BURGER`	`"Burgermeister"`、`"Bürgeramt"`、`"Burgersaal"`	(idem)
ユーザーが「k」と入力	`BURGER k`	`"KING"`	近くの BK の場所
ユーザーが「KING」を選択	`BURGER KING`	`"Burgermeister"`、`"Bürgeramt"`、`"Burgersaal"`	2 つの BK の場所と、近くの BK の場所の `chainQuery`
ユーザーが「」と入力	`BURGER KING`	提案なし	(idem)
ユーザーが「m」と入力	`BURGER KING m`	`"Marienfelde"`、`"Mitte"`、`"Moos"`	近くの1 か所の BK 、Marienfelde に 2 か所、Mitte に 1 か所、Rudolf-Moos-Straße に 1 か所
ユーザーが「Mitte」を選択	`BURGER KING Mitte`	`"Mittenwalde"`	Mitte の 2 か所の BK、Mitte 近くの BK のフォローアップ `chainQuery`、Mittenwald 近くの BK のフォローアップ `chainQuery`、近くの BK 1 か所
ユーザーが「Mitte 近くの BURGER KING」を選択フォローアップクエリ

エンドユーザーが chainQuery 提案の「Mitte 近くの BURGER KING」を items 配列から選択すると、アプリケーションは関連する href レスポンス要素を Discover サービスに対して起動し、エンドユーザーが Mitte にある BURGER KING レストランのみを取得できるようにします。

chainQuery提案に対するDiscoverサービスのレスポンスは次のとおりです。

{
  "items": [
    {
      "title": "BURGER KING",
      "address": {
        "label": "BURGER KING, Alexanderplatz 8, 10178 Berlin, Germany",
        "district": "Mitte",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "address": {
        "label": "BURGER KING, Friedrichstraße 141, 10117 Berlin, Germany",
        "district": "Mitte",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING Storkower STR. Ecke Landsberger Allee",
      "address": {
        "label": "BURGER KING Storkower STR. Ecke Landsberger Allee, Landsberger Allee 119, 10407 Berlin, Germany",
        "district": "Fennpfuhl",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:2768lxx5-3d9439ccf0df01dd9657a0a56254c9cb",
      "resultType": "place",
      "address": {
        "label": "BURGER KING, Schönhauser Allee 79, 10439 Berlin, Germany",
        "district": "Prenzlauer Berg",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u33db-ad4ba38ca1674569acba3c98b953c532",
      "resultType": "place",
      "address": {
        "label": "BURGER KING, Jean-Monnet-Straße 2, 10557 Berlin, Germany",
        "district": "Moabit",
        ...
      },
      ...
    },
    ...
  ]
}

この例では、クエリ用語の補完を使用することで、エンドユーザーがHERE Geocoding and Searchとやり取りする回数は11回となり、アプリケーションがqueryTerms要素を統合していない場合の「Burger King Mitte」クエリにおける18回と比べて削減されています。

クエリ用語が長いほど得られる効果は高くなります。

追加情報

/autosuggestエンドポイントパラメーターの詳細については、「APIリファレンス」を参照してください。