結果をレンダリングして強調表示を使用する

このチュートリアルでは、/autocompleteエンドポイントが、入力された単語を住所または行政区画の一部と照合して、テキスト入力を補完する方法を説明します。

手順

エンドユーザーはすでに入力済みの単語がレスポンスに表示されること、目的の住所を簡単に特定して選択できることを求めています。この期待に応えるために、/autocompleteエンドポイントは結果titleを他のエンドポイントとは異なる方法で表示します。

/autocompleteエンドポイントはすべての国で、国名から住所の順で統一された形式で結果titleを表示します。結果titleには、常にすべての住所コンポーネントが含まれているとは限りません。すべてを含めると長くなり過ぎ、負荷が大きくなるためです。エンドユーザーが結果を認識して、最終的な選択に重要となる部分のみが含まれます。

たとえば、フランクフルトの Pariser Straße の住所を検索する中間クエリは Frankfurt Pari となります。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Frankfurt+Pari
    &limit=1
    &apiKey={YOUR_API_KEY}

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

q - 名前を入力します。
limit - 返される結果の最大数。
apiKey - APIキー。

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

ドイツの道路の結果におけるデフォルトの結果titleには、国名、郵便番号、市区町村、道路名が含まれています。

{
  "items": [
    {
      "title": "Deutschland, Frankfurt am Main, Pariser Straße",
      "id": "here:af:street:Hg5LQ9NeP5Clua0GQ5dkIB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Straße, 60486 Frankfurt am Main, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "HE",
        "state": "Hessen",
        "countyCode": "F",
        "county": "Frankfurt am Main",
        "city": "Frankfurt am Main",
        "district": "Gallus",
        "street": "Pariser Straße",
        "postalCode": "60486"
      },
      "highlights": {
        "title": [
          {
            "start": 13,
            "end": 22
          },
          {
            "start": 32,
            "end": 36
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 4
            },
            {
              "start": 22,
              "end": 31
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 9
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 4
            }
          ]
        }
      }
    }
  ]
}

住所を確認する場合、ドイツの州名と郡名はそれほど重要ではありません。そのため、デフォルトでは州名と郡名は結果 title に表示されません。

ただし、ユーザーが州 Hessen の候補のみを取得して、それをクエリの一部として Frankfurt, Hessen, Pari のように使用することを求めている場合もあります。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Frankfurt%2C+Hessen%2C+Pari
    &apiKey={YOUR_API_KEY}

国名、郵便番号、市区町村、道路名に加え、結果 title には州名も含まれます。

{
  "items": [
    {
      "title": "Deutschland, Hessen, Frankfurt am Main, Pariser Straße",
      "id": "here:af:street:Hg5LQ9NeP5Clua0GQ5dkIB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Straße, 60486 Frankfurt am Main, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "HE",
        "state": "Hessen",
        "countyCode": "F",
        "county": "Frankfurt am Main",
        "city": "Frankfurt am Main",
        "district": "Gallus",
        "street": "Pariser Straße",
        "postalCode": "60486"
      },
      "highlights": {
        "title": [
          {
            "start": 13,
            "end": 19
          },
          {
            "start": 21,
            "end": 30
          },
          {
            "start": 40,
            "end": 44
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 4
            },
            {
              "start": 22,
              "end": 31
            }
          ],
          "state": [
            {
              "start": 0,
              "end": 6
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 9
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 4
            }
          ]
        }
      }
    }
  ]
}

いずれの場合も、/autocomplete エンドポイントは地域の郵便ルールに従って address ブロックの結果 label を表示します。これらのルールはすべてのエンドポイントで同じです。入力された単語がすべて含まれるわけではありません。

結果には highlights という名前のブロックも含まれます。

highlights ブロックには結果 title 内および address ブロックの詳細な住所コンポーネント内で、一致しているクエリ内の単語を強調表示するために必要なすべての情報が含まれています。

結果 title は、顧客アプリケーションがこれを使用して候補を強調表示できるように構成されています。上の 2 つのクエリの結果は同じですが、2 つ目の場合は title に州名の Hessen が含まれ、エンドユーザーは結果 title で強調表示されたすでに入力済みの単語をすべて確認できます。

追加情報

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