空間参照を使用して結果を限定する

このチュートリアルでは、空間参照の使用方法について説明します。

手順

顧客アプリケーションでは、at を使用して、座標で表される検索コンテキストの中心を指定できます。または、in=circle または in=bbox を使用して、円形エリアまたはバウンディングボックスで結果を制限することもできます。in パラメーターはハードフィルターです。

たとえば、グローバルクエリ Paris の関連性の高い結果の 1 つはフランスの首都です。しかし、ベルリンにいるエンドユーザーが、Paris で始まる名前の、近くにある道路の結果に興味を持っているとします。

次のようにクエリを作成します。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &at=52.5249445%2C13.3689829
    &limit=2
    &apiKey={YOUR_API_KEY}

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

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

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

このクエリには候補の数を制限するパラメーターlimit=2が含まれています。/autocompleteエンドポイントのデフォルトの上限は5です。/autocompleteエンドポイントでサポートされているlimitパラメーターの最大値は20です。

レスポンスには、指定されたベルリン内の位置周辺の住所のうち、この例では道路名にParisというトークンを含んでいる候補が含まれます。

{
  "items": [
    {
      "title": "Deutschland, Berlin, Pariser Platz",
      "id": "here:af:street:blZMmLnwtsYaXawaeHWfzC",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Platz, 10117 Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "street": "Pariser Platz",
        "postalCode": "10117"
      },
      "distance": 1140,
      "highlights": {
        "title": [
          {
            "start": 21,
            "end": 26
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 5
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 5
            }
          ]
        }
      }
    },
    {
      "title": "Deutschland, Berlin, Straße der Pariser Kommune",
      "id": "here:af:street:AfkQXa0XADEPA-WZxLPzmB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Straße der Pariser Kommune, 10243 Berlin, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "BE",
        "state": "Berlin",
        "countyCode": "B",
        "county": "Berlin",
        "city": "Berlin",
        "district": "Friedrichshain",
        "street": "Straße der Pariser Kommune",
        "postalCode": "10243"
      },
      "distance": 4806,
      "highlights": {
        "title": [
          {
            "start": 32,
            "end": 37
          }
        ],
        "address": {
          "label": [
            {
              "start": 11,
              "end": 16
            }
          ],
          "street": [
            {
              "start": 11,
              "end": 16
            }
          ]
        }
      }
    }
  ]
}

この場合、各項目のレスポンスにはdistanceフィールドが含まれます。これは、at位置からこの結果までのメートル単位での距離です。

同様に、inパラメーターを使用してベルリン市周辺の円形エリアまたはバウンディングボックスで結果を制限するクエリの場合、/autocompleteエンドポイントは空間フィルター内の結果のみを返します。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &in=circle%3A52.5161288%2C13.3896019%3Br%3D20000
    &limit=2
    &apiKey={YOUR_API_KEY}

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

q - 名前を入力します。
in=circle - 地理的エリア内を検索します。これはハードフィルターです。指定した円形エリア内に結果がある場合、結果が返されます。
limit - 返される結果の最大数。
apiKey - API キー。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Paris
    &in=bbox%3A13.08835%2C52.33812%2C13.761%2C52.6755
    &limit=2
    &apiKey={YOUR_API_KEY}

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

q - 名前を入力します。
in=bbox - 地理的エリア内を検索します。これはハードフィルターです。指定したバウンディングボックス内に結果がある場合、結果が返されます。
limit - 返される結果の最大数。
apiKey - API キー。

追加情報

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