Places (Search) API 開発者ガイド ( 場所 ( 検索 ))

フィルタリング-場所で検索します

Places (Search) API を使用すると、特定の場所または場所の領域で関連性を判断できる場合に、結果をフィルタリングできます。 関連するロケーション情報を ロケーションコンテキストの形式で入力します。 Places ( 検索 ) API では、次の種類のロケーションコンテキストがサポートされています。
  • EXPLICIT –リクエストクエリーのパラメータに含まれます

    明示的な場所のコンテキストの例としては、クエリーパラメータ atまたはinの値を指定して、ユーザーの入力に基づいて特定の位置、円、またはバウンディング ボックスを提供することがあります。 使用可能なクエリーパラメータの詳細について は、『 API リファレンス 』を参照してください。

  • Implicit –リクエストヘッダに含まれます

    暗黙的なロケーションコンテキストの例としては、デバイスの GPS ユニットから現在のロケーションを提供することや、ヘッダー GeolocationおよびX‑Map‑Viewportの要求ヘッダーに表示されるマップ ビューなどがあります。 使用可能なロケーションコンテキストヘッダーの詳細について は、「 HTTP リクエストヘッダー」を参照してください。

関連性のカテゴリで検索結果をフィルタリングすることもできます。 詳細について は、「カテゴリによるフィルタリング」を参照してください。

すべての場所 ( 検索 ) API エントリーポイント には、少なくとも 1 つの場所のコンテキストが必要です。 できるだけ暗黙的なロケーションコンテキスト情報と、該当する場合は明示的なロケーションコンテキスト情報を提供することを強く推奨します。 ベストプラクティスの詳細について は、「ベストプラクティス」を参照してください。

明示的な場所のコンテキスト

ユーザーがアプリケーションの場所を明示的に指定する場合 ( たとえば、マップの位置をクリックしてその場所での検出クエリをトリガする場合 ) 、アプリケーションは、次のいずれかのクエリ文字列パラメータを使用して、 Places (Search) API に明示的な場所のコンテキストを提供する必要があります。

名前 空き状況 形式 説明
at Always 位置 明示的な位置を点として指定します
in 選択したリクエストタイプ または 円( Circle or バウンディング ボックス) 明示的な領域を指定します

暗黙的な場所のコンテキスト

アプリケーションでは、ユーザーの地理位置情報や、ユーザーに現在表示されている地図領域など、ユーザーが明示的に提供していない位置情報が利用できることがあります。 明示的な場所のコンテキストがない場合は、少なくとも 1 つのタイプの暗黙的な場所のコンテキスト情報を送信する必要があります。明示的な場所を指定している場合でも、最適な結果を得るために、暗黙的な場所のコンテキスト情報を送信することを強くお勧めします。

値がわかっている場合、アプリケーションは常に次の暗黙的な位置コンテキストヘッダーを送信する必要があります。

名前 形式 説明
Geolocation 位置 ユーザーの物理的な位置を指定します
X‑Map‑Viewport バウンディング ボックス ユーザーに現在表示されている地図領域を指定します

ベストプラクティス

最適な結果を得るには、アプリケーションは、利用可能な場合は常に暗黙的な位置コンテキスト情報を送信し、ユーザーが特定の位置を明示的に指定 ( 選択 ) した場合にのみ、明示的な位置コンテキストパラメータを送信する必要があります。 したがって、マップ X-Map-Viewport をユーザーに表示する場合は常にヘッダーを送信し Geolocation 、ユーザーの位置がわかっている場合はヘッダーを送信する必要があります。 多くの場合、これで十分です。また、明示的な場所のコンテキスト(クエリー文字列パラメータを使用)は必要ありません。

たとえば、アプリケーションが常にユーザーにマップを表示し、 Places (Search) API を利用する無料テキスト検索のためのテキストボックスを提供search entrypointする場合です。 ユーザーが検索を実行すると、アプリケーションが X-Map-Viewport ヘッダーを提供する必要があります。 ユーザーの位置もわかっている Geolocation 場合は、アプリケーションにもヘッダーが含まれている必要があります。 このシナリオでは、ユーザーは検索に関連する明示的な場所を指定しません ( マップのビューポイントの位置を指定することはできません ) 。そのため、明示的な場所のコンテキストを指定する必要はありません。

ただし、ユーザーがを使用してマップをクリックし、その場所にあるものを検索できるようにアプリケーションが追加で許可 here entrypoint し、ユーザーがこの方法で場所を選択した場合 at 、アプリケーションはその場所を明示的な場所のコンテキストとしてクエリー文字列パラメータで提供する必要があります。 アプリケーションは X-Map-Viewport 、ヘッダーを介して暗黙的なコンテキスト情報を送信する必要 Geolocation がありますが(ユーザーの場所が利用可能な場合は)、明示的な場所がリクエストのプライマリの場所を決定する際に優先されます。

距離の計算

結果の場所には、ユーザーの場所からの距離、または明示的な参照点からその場所までの距離を示す距離フィールドがあります。 リクエストの明示的なロケーションコンテキストによって、距離の計算元のロケーションが提供されます。 明示的な場所のコンテキストがない場合 は、地理位置情報ヘッダーの位置が使用されます。 X-Map-Viewport からの位置コンテキストのみが使用可能な場合 、距離の計算は行われず、距離は設定されません。

位置の形式

地理位置 ヘッダー ( 暗黙的なコンテキスト ) および at パラメーター ( 明示的なコンテキスト ) では、位置を 'geo' URI で指定します。 位置は、緯度および経度 (WGS 84 座標系 ) のコンマ区切り値、およびオプションで高度 ( 海抜メートル単位 ) 、およびセミコロンで区切られた位置パラメータのリストで指定されます。

アプリケーションは、 cgen パラメーターに次のいずれかの値を渡して、位置のソースを指定する必要があります。

  • map マップ上のポイントの場合 ( 例 : ) geo:53.12,10.15;cgen=map
  • gps たとえば、 GPS デバイスからの値の場合geo:53.12,10.15;cgen=gpsは、です。
  • sgps 中国の法的要件を満たすデバイスからシフトされた GPS 座標の場合 geo:53.12,10.15;cgen=sgps( 例 : ) 。

地理座標の不確実性は 、メートル などの不確実性として u パラメータで指定する必要 geo:53.12,10.15;cgen=gps;u=100があります。 これは、 GPS 座標の修正の不確実性、またはマップの解決によって生じる不確実性です。 では、絶対に正確な位置を指定する必要 u=0があります。 u パラメータを指定しない場合、不確実性は 0 ではなく指定されません。 たとえば、 39.91,116.40;cgen=gps;u=16 16 メートルの不確実性を持つ GPS デバイスから派生した位置を指定します。

円の形式

位置 (位置を参照)と追加の半径を指定することで、円形領域を位置コンテキストとして指定できます。 半径は 、 r パラメーターをメートル単位の半径に設定することで指定されます。 たとえば、53.12,10.15;r=10500 半径 10.5km の領域を指定します。

バウンディング ボックス形式

バウンディング ボックスを使用して、地理的領域を位置コンテキストとして指定できます。 この領域をまたぐ矩形は、 WGS 84 座標系で、 West 経度、 South 緯度、 east 経度、 north 緯度の 4 つのコンマ区切り値として指定されます。 たとえば 13.125,52.362,13.661,52.693 、ベルリンのバウンディング ボックスを指定します。

HERE マップタイルを使用するマップアプリケーションの場合、ズーム レベルは 5 番目のパラメータとして送信されます。 たとえば、ズーム レベルが 4.3 の場合 13.125,52.362,13.661,52.693,4.3、上記の例はになります。

HERE ポリラインエンコード

パラメータには HERE ポリラインエンコーディングが使用 compressedRoute されます。 ポリラインエンコーディングは、座標ペアのリストを圧縮して表現したものです。 それをまでに達成する
  • 精度を小数点以下 5 桁に減らします
  • 前のポイントからのオフセットのみをエンコードしています
  • 各座標のデルタに可変の長さを使用します
  • 64 文字の URL セーフ文字を使用して結果を表示します
入力が一連の座標として与えられていると仮定 { latitude: 52.0, longitude: 13.1 }します。たとえば、このシーケンスを反復処理し、符号化された緯度デルタを追加してから、経度デルタを最終結果に追加します。 最初の座標では、絶対値をエンコードする必要があります。他のすべての座標では、現在の座標から前の値を減算してデルタを取得します。 また、ルートセグメントが都市内にあるか、ハイウェイ上にあるかを指定することもできます。これを行うには、セグメントの始点をそれぞれ .Cまたは.H でマークします。 これにより、検索距離が変更され、以降のすべてのセグメントのアルゴリズムが変更される可能性があります。 影響を受ける最初のセグメントは .C 、またはの前の点で始まるセグメント .Hです。 これは、次の JavaScript スニペットによって反映されます。

function hereEncodePolyline(positions) {
  var lastLat = 0, lastLon = 0;
  var result = [];
  var width = "D"
  var newWidth;
  for (var i = 0; i < positions.length; ++i) {
    var position = positions[i];
    if (i > 0) {
      if (isCityRoad(lastLat, lastLon, position.latitude, position.longitude)) {
        newWidth = "C";
      } else if (isHighway(lastLat, lastLon, position.latitude, position.longitude)) {
        newWidth = "H";
      } else {
        newWidth = "D"
      }
      if (newWidth != width) {
        result.push("." + newWidth);
        width = newWidth;
      }
    }
    // it is an actual route point
    result.push(hereEncodeFloat(position.latitude - lastLat));
    result.push(hereEncodeFloat(position.longitude - lastLon));
    lastLat = position.latitude;
    lastLon = position.longitude;

  }
  return result.join('');
}
          
浮動小数点数は次のようにエンコードされます。
  1. 1e5 で乗算し、最も近い整数に丸めます
  2. 一番下のビットに余裕を持たせるには、左にシフトします
  3. 負の数値を反転します
  4. 数値を 5 ビットのチャンクに分割し、最下位から最上位へとエンコードします
  5. 可変長のエンコードなので 0x20 、別のチャックが追従することを示す信号にを追加します

function hereEncodeFloat(value) {
  var ENCODING_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
  var result = [];

  // convert to fixed point
  var fixedPoint = Math.round(value * 100000);

  // make room on the lowest bit
  fixedPoint = fixedPoint << 1;

  // flip bits of negative numbers and ensure that the last bit is set
  // (should actually always be the case, but for readability it is ok to do it explicitly)
  if (fixedPoint > 0) {
    fixedPoint = ~(fixedPoint) | 0x01
  }

  // var-length encode the number in chunks of 5 bits starting with the least significant
  // to the most significant
  while (fixedPoint > 0x1F) {
    result.push(ENCODING_CHARS[(fixedPoint & 0x1F) | 0x20]);
    fixedPoint >>= 5;
  }
  result.push(ENCODING_CHARS[fixedPoint]);
  return result.join('');
}
          
緯度と経度のペアの入力リストと、対応するエンコードされた表現の例を以下に示します

input1 = "[50.1022829,8.6982122|50.1020076,8.6956695|50.1006313,8.6914960|50.0987800,8.6875156]"
encoded1 = "oz5xJ67i1B3B7PzIhaxL7Y"

input2 = "[52.5199356,13.3866272|52.5100899,13.2816896|52.4351807,13.1935196|" +
     "52.4107285,13.1964502|52.38871,13.1557798|52.3727798,13.1491003|" +
     "52.3737488,13.1154604|52.3875198,13.0872202|52.4029388,13.0706196|52.4105797,13.0755529]"
encoded2 = "05xgKuy2xCx9B7vUl0OhnR54EqSzpEl-HxjD3pBiGnyGi2CvwFsgD3nD4vB6e"

inputWithWidths = "[52.5160,13.3771|CW|52.5111,13.3712|52.5355,13.3634|52.5400,13.3704|" +
           "52.56 26,13.3307|52.5665,13.3076|52.6007,13.2806|HW|52.6135,13.2484|52.6303,13.2406|" +
           "52.6651,13.2410|52.7074,13.1926|52.7045,13.0661|52.7191,12.9621|52.76 36,12.8263|" +
           "52.7861,12.8000|52.8335,12.7919|52.9002,12.7451|52.9708,12.6311|53.0526,12.5392|" +
           "53.0867,12.5169|53.1146,12.4687|53.1334,12.4644|53.1415,12.4225|53.1666,12.3722|" +
           "53.1785,12.3050|53.2570,12.1618|53.2893,12.0618|53.3000,11.9373|53.3316,11.8724|" +
           "53.3463,11.8190|53.3669,11.7328|53.3725,11.6427|53.4154,11.5505|53.4309,11.4906|" +
           "53.4342,11.4000|53.4655,11.3370|53.4873,11.2631|53.4860,11.2011|53.5110,10.9647|" +
           "53.5128,10.8414|53.5495,10.6892|53.5692,10.5155|53.5596,10.4259|53.5682,10.2999|" +
           "53.5571,10.2020|CW|53.5672,10.1279|53.5534,9.9924];w=1000"
encodedWithWidth = "ghxgK820xC.Cze7kBw4E3wBkc4rBotEj4HsYrwE41G3oF.H" +
           "gwCnpGgpD3wBw5GwCsoIvuJjSz2Yo7C_pUk2I3wa0sErkFooJzyB8gNvkJo5NvoWo_Pr-Rk1GrrEsuFntJw1D7" +
           "a0yB7lI88Er6JsqC_jN0qP_-b8pG_wT8iCjqYwlGz1M87C3tK4gE36QgjBjzRksIngS8gDr2L0Un2R0jG3pM" +
           "ooE7tOjIvjMo8EvluBoLziYslHn3dk7Dz9hB_7B_vR41BvzYrlC7jT.Ck_BjvOn2C7ua;w=1000"
        

また、クライアント側で非可逆圧縮を使用して、ルートジオメトリへの偏差が小さい場合にセグメントを直線に結合することもお勧めします。 テンプレートとして使用できるオープンソースの実装がいくつかあります。