Autocomplete

/autocompleteエンドポイントは、数回のキー操作に基づいて候補を表示することで、ユーザーが住所または行政区画を入力するのを支援します。ユーザーが希望する提案を選択すると、アプリケーションはその後、/lookupエンドポイントを使用してその候補の座標を取得できます。または、/geocodeエンドポイントを使用して、/autocompleteエンドポイントによって返された住所をジオコーディングすることもできます。

また、ユーザーは中間結果を選択し、それをベースにして/autocompleteエンドポイントの助けを借りながら住所入力を続けることもできます。たとえば、最初に都市名の候補を選択し、次に道路名、最後にその道路の特定の番地を選択するといった具合です。

「Pariser 2 Frank」というテキストを補完する住所のリストを取得するクエリは、次のリクエストのように作成できます。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Pariser+2+Frank
    &apiKey={YOUR_API_KEY}

このリクエストへのレスポンスには、次のようにクエリテキストを補完する 2 つの候補が含まれます。

{
  "items": [
    {
      "title": "Deutschland, 60486, Frankfurt am Main, Pariser Straße 2",
      "id": "here:af:streetsection:A2eGBPgL70TOTtA85fTiEB:CggIBCDg0K_aAhABGgEy",
      "language": "de",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "Pariser Straße 2, 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",
        "houseNumber": "2"
      },
      "highlights": {
        "title": [
          {
            "start": 20,
            "end": 25
          },
          {
            "start": 39,
            "end": 46
          },
          {
            "start": 54,
            "end": 55
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 7
            },
            {
              "start": 15,
              "end": 16
            },
            {
              "start": 24,
              "end": 29
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 5
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 7
            }
          ],
          "houseNumber": [
            {
              "start": 0,
              "end": 1
            }
          ]
        }
      }
    },
    {
      "title": "Deutschland, Frankenthal (Pfalz), Pariser Weg",
      "id": "here:af:streetsection:CUcedHTrEUhmgRAcm.mbnD",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Weg, 67227 Frankenthal (Pfalz), Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "RP",
        "state": "Rheinland-Pfalz",
        "countyCode": "FT",
        "county": "Frankenthal (Pfalz)",
        "city": "Frankenthal (Pfalz)",
        "district": "Frankenthal (Pfalz)",
        "street": "Pariser Weg",
        "postalCode": "67227"
      },
      "highlights": {
        "title": [
          {
            "start": 13,
            "end": 18
          },
          {
            "start": 34,
            "end": 41
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 7
            },
            {
              "start": 19,
              "end": 24
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 5
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 7
            }
          ]
        }
      }
    }
  ]
}

レスポンスには、結果ごとに次の上位要素が含まれます。

resultType - HERE Geocoding and Searchの/autocompleteエンドポイントは、次のような住所や行政区画をカバーする複数のタイプの項目を返すことができます：houseNumber、locality、street
administrativeArea、intersection、postalCodePoint
houseNumberType - 住所データのタイプ (住所結果の場合にのみ返されます)：
- PA - ポイント住所。位置情報は個々のポイントオブジェクトと一致します
- interpolated - 位置情報はアドレスレンジに基づいて補間されています。
title - 結果の代表的な表記の文字列。
address - 結果の詳細な住所。
id - 結果オブジェクトの識別子。この値を使用して /lookup エンドポイントからまったく同じオブジェクトを取得できます。
language - 結果の住所要素の優先言語。この値を使用して、/lookup エンドポイントで同じ言語優先設定を使用し、ID を使用して同じオブジェクトを取得できます。
highlights - クエリに一致するテキストスライス。このスライスを使用して、結果内の一致する関連クエリ用語を強調表示できます。

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

/autocompleteエンドポイントはテキストの単語を住所または行政区画の一部と照合して、テキスト入力を補完します。これは「補完」のユースケースであるため、ユーザーはすでに入力したすべての単語が/autocomplete候補に表示されることを期待している可能性があります。これに対応するために、/autocompleteエンドポイントには次の機能があります。

/autocompleteエンドポイントはクエリ内のすべての用語を含む結果のみを返します。唯一の例外は住居番号と一致しない場合です。/autocompleteエンドポイントで完全なクエリを番地まで照合できたものの、住居番号を照合できなかった場合、/autocompleteエンドポイントは結果を返さないのではなく、住居番号を含まない番地の候補を返します。上の例では、2番目の候補には住居番号が含まれていません。これは、住居番号がマップデータに存在しないためですが、実際には有効な住所である可能性があります。
/autocompleteエンドポイントはレスポンス言語を選択して、ユーザーがクエリに入力したすべての単語と同じ言語で表示し、認識できるようにします。langパラメーターを使用することで、顧客アプリケーションはユーザーが希望するレスポンス言語を指定できます。一致した住所フィールドの言語は変更されませんが、それ以外の住所では優先する言語が設定されます。
/autocompleteエンドポイントの結果titleは、他のすべてのエンドポイントの形式とは異なります。国名から始まる統一された形式で結果を表し、クエリで一致したすべての用語が含まれます。
レスポンスにはhighlightsブロックが含まれています。これを使用することで、結果のtitle内およびaddressブロックの詳細な住所コンポーネント内で、一致しているクエリ内の単語を強調表示できます。

📘
注：
HERE Geocoding and Searchの/autocompleteエンドポイントは日本のプレミアムデータをサポートしていません。