Autosuggest

/autosuggest エンドポイントは自由形式の不完全で誤字脱字がある住所または場所の名前を使用して、ユーザーの検索品質を向上します。この候補提案エンジンは HERE WeGo アプリケーションと HERE Navigation アプリケーションのバックエンドで使用されます。

候補

基本的にHERE Geocoding and Searchはユーザーのクエリに対して、適切なレスポンスを提供することを目的としています。

クエリには次のタイプがあります。

• 「レストラン」や「スターバックス」などの特定のカテゴリーまたはチェーンで、場所が不明なもの
• 「エッフェル塔」や「ベルリン」などの確定的な名前で、場所が明らかなもの
• 「レストラン シカゴ」など、特定の地域にあり場所が不明なもの

Autosuggest は、「レスト」、「スターバ」、「エッフェル」、「ベルリ」、「レストラン シカ」などの部分的なクエリに対して、該当する候補を提示します。このような候補には次のタイプがあります。

• クエリ結果項目：

  部分的なクエリに関連するフォローアップ クエリが見つかった場合、フォローアップ クエリは次のいずれかのタイプとなります。

  • プレース カテゴリー クエリ (結果タイプ categoryQuery)
  • プレース チェーン クエリ (タイプ chainQuery を使用)

• エンティティ結果項目：

  部分的なクエリに関連する場所または住所オブジェクトが見つかった場合、結果タイプは、
  addressBlock、administrativeArea、houseNumber、intersection、locality、place、streetのいずれかとなります。

先ほどの画像の「レストラン」の候補は、Autosuggest クエリ結果項目のものです。

フォローアップ リクエスト

/autosuggest エンドポイントはテキストベースの入力エンジンで、エンド ユーザーの操作をサポートします。/autosuggest エンドポイントへのリクエストは 1 文字目から、入力するたびに送信されます。

返される各項目には、フォローアップ クエリの作成に必要な情報が含まれています。

• クエリ項目には /discover へのフォローアップ クエリを含む href 要素が含まれます。
• エンティティ項目には /lookup エンドポイントで使用できる位置情報 id が含まれます。

なお、Autosuggest がクエリ項目のみを返す場合、アプリケーションはエンドユーザーの選択を待たずに、/discoverフォローアップクエリを
続行できます。これはアプリケーションの応答性を向上するため、推奨されます。また、クエリ項目で返された id フィールドはエンティティ項目の id フィールドとは異なり、/lookup エンドポイントでは使用できません。

/discover へのフォローアップ

たとえば、HERE WeGoユーザーが画像内の「レストラン」候補などのクエリ結果項目をタップすると、
関連するレストランの検索結果が HERE WeGo に表示されます。

HERE WeGoはレストラン候補のhrefフィールドを使用して、検索バックエンドにフォローアップクエリを送信します。

APIキー認証を使用する場合、クライアントはAutosuggestから返されたすべてのクエリ結果項目に対して、
apiKeyパラメーターを追加する必要があります。認証方法の詳細については、「資格情報を取得する」を
参照してください。

/lookupへのフォローアップ

「Tomate Fresh Kitchen」など、レストランの候補をタップすると関連情報が表示されます。HERE WeGo は関連するエンティティ結果 id を使用して、/lookup を呼び出します。次の画像を参照してください。

位置情報コンテキスト

/autosuggestへのクエリには、/discoverエンドポイントと同様に、at、in、routeパラメーターを使用して位置情報コンテキストを指定する必要があります。

クエリ文字列

q パラメーターは変化するフレーズを送信するために使用します。文字を 1 文字追加するたびに 1 つの Autosuggest クエリが送信されます。

たとえば、エンド ユーザーがアプリケーションを使用して、「レ」、「ス」、「ト」、「ラ」、「ン」という文字を入力する場合、アプリケーションは q パラメーターを「レ」、次に「レス」、「レスト」、「レストラ」に設定してリクエストを送信します。早いタイミングで候補を示すため、顧客は最初に入力された文字から Autosuggest クエリを送信することを選択できます。または、3 番目の文字入力からクエリを送信することもできます。この場合、例に示したクエリでは、q を「レスト」、「レストラ」などに設定します。

discover の場合、入力文字列をさまざまな混合スクリプト (ラテン文字、キリル文字、アラビア文字、ギリシャ文字など) で作成できます。

特殊なケース：

• q 値は空白にできません。
• 空白、タブ、改行のみを含む q 値は有効なクエリであり、空の結果リストを返します。

たとえば、ボルチモア周辺で「レスト」という候補を検索するクエリは次のようになります。

{/* curl -H"Authorization:Bearer $(olp api token get --quiet)" -s "https://autosuggest.search.hereapi.com/v1/autosuggest?at=39.31974,-76.56721&q=rest&limit=5" | underscore print --wrapwidth 200*/}

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=39.31974,-76.56721
    &limit=5
    &q=rest
    &apiKey={YOUR_API_KEY}

結果項目フィールド

候補提案エンジンはクエリ項目またはエンティティ項目のいずれかの該当する候補のセットを返します。/autosuggestパラメーターの詳細については、
「APIリファレンス」を参照してください。

HERE WeGo アプリケーションが送信した、上の例に類似するリクエストへのレスポンスは次のとおりです。

{
  "items": [
    {
      "title": "Restaurant",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?at=39.31974%2C-76.56721&limit=5&q=Restaurant&_ontology=restaurant",
      "highlights": { "title": [{ "start": 0, "end": 4 }] }
    },
    {
      "title": "Rest stop",
      "id": "here:cm:ontology:rest_area",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?at=39.31974%2C-76.56721&limit=5&q=Rest+stop&_ontology=rest_area",
      "highlights": { "title": [{ "start": 0, "end": 4 }] }
    },
    {
      "title": "Restoration East",
      "id": "here:pds:place:840dqcx9-2f1561a4501b4cc0a49aa6611838b448",
      "resultType": "place",
      "address": { "label": "Restoration East, 4209 E Chase St, Baltimore, MD 21205-3020, United States" },
      "position": { "lat": 39.30398, "lng": -76.56193 },
      "access": [{ "lat": 39.30435, "lng": -76.56264 }],
      "distance": 1810,
      "categories": [{ "id": "700-7400-0000", "name": "Consumer Services", "primary": true }, { "id": "700-7200-0277", "name": "Specialty Trade Contractors" }],
      "highlights": { "title": [{ "start": 0, "end": 4 }], "address": { "label": [{ "start": 0, "end": 4 }] } }
    },
    {
      "title": "Rent Now (Rest for the Wicke)",
      "id": "here:pds:place:8403fv6k-b6fd543c49df01f3ae3981be17ed3412",
      "resultType": "place",
      "address": { "label": "Rent Now, 5229 Harford Rd, Baltimore, MD 21214-2622, United States" },
      "position": { "lat": 39.34978, "lng": -76.56321 },
      "access": [{ "lat": 39.34991, "lng": -76.56347 }],
      "distance": 3358,
      "categories": [{ "id": "700-7400-0145", "name": "Real Estate Services", "primary": true }, { "id": "600-6950-0000", "name": "Hair & Beauty" }, { "id": "700-7400-0000", "name": "Consumer Services" }],
      "highlights": { "title": [{ "start": 10, "end": 14 }], "address": { "label": [ ] } }
    },
    {
      "title": "Prorest Pest (Pro Rest Pest)",
      "id": "here:pds:place:840dqcxd-2a86850c1c34418f8023280a5f7baf62",
      "resultType": "place",
      "address": { "label": "Prorest Pest, 6600 Frankford Ave, Baltimore, MD 21206-4901, United States" },
      "position": { "lat": 39.31265, "lng": -76.54259 },
      "access": [{ "lat": 39.31285, "lng": -76.54273 }],
      "distance": 2260,
      "categories": [{ "id": "700-7200-0277", "name": "Specialty Trade Contractors", "primary": true }, { "id": "550-5520-0210", "name": "Wildlife Refuge" }, { "id": "700-7400-0000", "name": "Consumer Services" }],
      "references": [{ "supplier": { "id": "yelp" }, "id": "BY3MjxFzBwCl_OemyfJBKQ" }],
      "highlights": { "title": [{ "start": 3, "end": 7 }, { "start": 18, "end": 22 }], "address": { "label": [{ "start": 3, "end": 7 }] } }
    }
  ],
  "queryTerms": [ ]
}

共通要素

レスポンスには最も可能性の高い候補から最も可能性の低い候補まで、複数の項目が含まれます。

各項目には次の上位要素が含まれます。

• resultType - 項目タイプ

  HERE Geocoding and Searchの/autosuggestは、次のような複数のタイプの項目を返すことができます。

  categoryQuery、chainQuery、place、localityなど

• title - 項目の代表的な表記の文字列

  たとえば、場所の名前や候補のフォローアップ クエリのタイトルなどです。

• id - 項目の識別子

  項目が`categoryQuery`または`chainQuery`タイプでない場合、`id`値を使用して
  

  同じオブジェクトを/lookupエンドポイントから取得できます。

クエリ結果項目

クエリ候補固有の要素：

• href - フォローアップ クエリ URI

  このクエリはエンド ユーザーが関連項目を選択した場合にアプリケーションが使用します。フォローアップ クエリはカテゴリー クエリまたはチェーン クエリのいずれかとなります。

• highlights - クエリに一致するテキスト スライス

  このスライスを使用して、一致する関連フィールドを強調表示できます。

エンティティ結果項目

場所と住所の候補の固有の要素：

• position - 結果の代表的な地理的位置 (WGS 84)。これを使用して地図上に結果を表示します
• access - 結果にアクセスするための地理的位置 (入り口など)
• distance - クエリの at パラメーターで指定された位置からの直線距離 (メートル単位)
• address.label - エンティティ結果項目の完全な住所

place タイプの結果には「場所の結果」に記載されている、追加の属性が含まれる場合があります。

クエリ用語の補完サポート

エンドユーザーが自由形式のテキストクエリを作成できるようにするため、/autosuggestは、エンドユーザーが
入力し始めた単語を置き換える候補語のリストを提供します。最後に入力した単語の予測テキストのリストは、
termsLimitクエリパラメーターが0より大きい値に設定されている場合(最大値は10)、queryTermsレスポンス要素に含まれます。

なお、itemsには完全なフォローアップクエリにそのまま使用できる結果項目が含まれますが、queryTermsは
エンドユーザーが作成しているクエリに焦点を当てています。それぞれの配列は独立しているため、より柔軟性のあるアプリケーションのユーザー エクスペリエンスを実現できます。

例の詳細はクエリ用語の補完で確認できます。

優先言語

項目が優先言語で返される必要があるアプリケーションでは、lang パラメーターを該当する BCP 47 言語コードに設定する必要があります。Autosuggest サービスはその言語で候補を返すようにします。langが設定されていないか、候補項目にリクエストされた言語の翻訳がない場合は、デフォルトの言語が使用されます。

{/*##結果タイプフィルター。候補を特定の結果タイプに制限する必要があるアプリケーションでは、これらのタイプをresultTypesクエリパラメーターにカンマ区切りの値として設定します。たとえば、ベルリン周辺でcategoryQueryおよびplaceタイプの「レスト」候補の場合、クエリは実際には次のリクエストのようになります：http GET https://autosuggest.search.hereapi.com/v1/ autosuggest ?at=39.31974,-76.56721 &limit=5 &q=rest &apiKey={YOUR_API_KEY} その他の例については、「Autosuggestの例」セクションを参照してください。*/}

{/* https://saeljira.it.here.com/browse/OSQ-23574の想定どおりshow=detailsは非表示。##結果の詳細。Autosuggestは通常、LookupまたはDiscoverのフォローアップクエリと組み合わせて使用されます。特定のケースでは、デフォルトで返される情報よりも詳細な情報が必要です。たとえば、一部のアプリケーションでは住所や営業時間に関する詳細情報が必要になり、各結果に対して独自の表示形式を作成します。これらのアプリケーションをサポートするために、HERE Geocoding and Searchでは、AutoSuggestクエリにshow=detailsを追加できるようにしています。このオプションにより、利用可能な住所の詳細、連絡先情報、営業時間情報が公開されます。これらの詳細が不要なアプリケーションでは、結果のサイズを削減し、帯域幅を節約するため、このオプションは使用しないでください。これらの詳細は、ユーザークエリに追加された文字ごとに送り返されるためです。*/}

ドキュメント化されていないレスポンス属性は
<span style={{color: "red"}}>試験版
であり、常に削除または変更される可能性があります。ぜひフィードバックをお寄せください。

{/* lookupが他のエンドポイントよりも多くのコンテンツを提供する準備ができている場合に使用されるクエリワークフロー提案は非表示。##クエリワークフロー。HERE Geocoding and Searchエンドポイントは、目的の情報フローに応じて、場所(POI)やその他の位置を検索するためのさまざまなモデルを提供します。情報フロー(ユーザーフローとも呼ばれる)とは、エンドポイントへの最初のリクエストのレスポンスにハイパーメディアリンクや位置IDが含まれており、それらを使用して追加の結果セットや特定の場所のより詳細な情報を取得できるような情報取得パターンを指します。すべてのHERE Geocoding and Searchの/autosuggestは、クエリ/responseパターンに従って使用されることを前提としています。たとえば、/geocodeの結果は、開発者がアプリケーションに統合するのに十分な情報を含むことを目的としています。一方、/autosuggestは、/discoverまたは /lookupへのフォローアップクエリをサポートすることを目的としています。/lookupエンドポイントは、revgeocodeを除くすべてのエンドポイントで返される任意のロケーションオブジェクトを、IDを指定して取得するために使用できます。これは以下の図に示されています。