Discover

/discover エンドポイントを使用すると、場所を簡単に検索できます。ユーザーが自由形式のテキストリクエストを送信すると、関連する候補項目(場所や住所)が検索意図との一致度が高い順に返されます。

順位付け品質のレベルは、グローバルレベルとローカルレベルで指定します。

ユースケース

/discover エンドポイントを使用すると、ユーザーは自由形式のテキストで次のものを検索できます。

正確な場所または住所
1. 名前を使用
2. 地理的位置を使用
3. 電話番号を使用
場所のクラス
1. カテゴリー名を使用
2. チェーン名を使用
3. カテゴリー名またはチェーン名を位置情報と合わせて使用
4. 特定の場所の周辺でカテゴリー名またはチェーン名を使用

自由形式のテキストは q パラメーターの値として指定します。

結果項目

エンドユーザーが知らない場所に行くかどうかを判断できるように、/discoverエンドポイントは複数の選択肢を返し、結果として複数の項目が表示されることが想定されています。エンドユーザーは最も適したものを選択します。

ワンボックス検索

/discoverエンドポイントのメインの入力フィールドはqです。これはエンドユーザーから送信された自由形式のテキストを含めることを目的としています。

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

q パラメーターのエンコードを UTF-8 に設定し、その後パーセントエンコードすることをお勧めします。

特殊なケース：

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

位置情報コンテキストとフィルター

形状コンテキスト

返される項目の関連性を高めるため、/discover エンドポイントは次のいずれかから提供されるクエリの位置コンテキストを求めます。

単一の地理的位置 (「検索地点」とも呼ばれます)
円
境界矩形 (バウンディングボックス、bbox とも呼ばれます)

この 3 つの位置情報コンテキストは相互に排他的であり、このうち 1 つのみが許可されます。

円と境界矩形は位置情報コンテキスト (中心位置) とフィルターの両方を定義します。すべての返される項目は、その地理的制限の範囲内に位置します。

検索地点はatパラメーターで指定し、円形範囲や国コードのフィルターは inパラメーターで指定します。

国フィルター

in=circle および in=bbox と同様に、顧客は検索地点に国関連の地理的範囲を指定できます。

これは ISO 3166-1 alpha-3 の大文字の国コードのリスト形式で指定します。返されるすべて項目が該当する国に位置するものとなります。次の点にご留意ください。

HERE Geocoding and SearchはISOコードに加えて国グループXEAをサポートしており、これはこの国コードのリスト (AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE)に相当します。

📘
注：
次の国では、HERE Geocoding and SearchはISO-3166コードとは異なるコードを使用しています。XSB-BSB、XCY-CUN、XGS-GAS、XGI-GRI、XKO-KOS、XKI-KRI、XNC-NCY、XPI-PLI、XSO-SAS、XSI-SPI。

使用可能な組み合わせ

使用可能な at と in の組み合わせの一覧は次のとおりです。

at
at と in=countryCode
in=circle
in=circle と in=countryCode
in=bbox
in=bbox と in=countryCode

最後に、/discoverエンドポイントはrouteパラメーターをat パラメーターに追加することにより、ルート沿いの検索に対応しています。詳細については、ルート沿いの検索の実装を参照してください。

詳細については、「API リファレンス」を参照してください。

インターナショナリゼーション

可能な場合は、HERE Geocoding and Searchの/discoverエンドポイントはエンドユーザーが使いやすい言語でレスポンス項目を表示しようとします。このためには、お客様はlangパラメーターに該当する BCP 47言語コードを設定する必要があります。langが設定されていない場合、または結果項目にリクエストされた言語の翻訳が存在しない場合は、デフォルトの言語が使用されます。

近接性

/discoverエンドポイントは自由形式のテキスト内の地理的な近接性も取得します。

エンドユーザーは、特定の地域や具体的な場所名の「近く」または「そば」にあるカテゴリーやチェーン店をクエリするフレーズを送信できます。

例

たとえば、(42.36346,-71.05444) という地理的位置から米国にあるレストランを探す場合、次のように作成します。

GET https://discover.search.hereapi.com/v1/
    discover
    ?at=42.36346,-71.05444
    &limit=1
    &q=restaurant
    &in=countryCode:USA
    &apiKey={YOUR_API_KEY}

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

上のリクエストに対するレスポンスは次のようになります。

{
  "items": [
    {
      "title": "Salumeria Italiana",
      "id": "here:pds:place:840drt3p-898f6ee434794fe59895e71ccf9381e1",
      "ontologyId": "here:cm:ontology:restaurant",
      "resultType": "place",
      "address": {
        "label": "Salumeria Italiana, 151 Richmond St, Boston, MA 02109-1414, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "North End",
        "street": "Richmond St",
        "postalCode": "02109-1414",
        "houseNumber": "151"
      },
      "position": { "lat": 42.36355, "lng": -71.05439 },
      "access": [{ "lat": 42.36349, "lng": -71.05448 }],
      "distance": 11,
      "categories": [
        { "id": "600-6300-0066", "name": "Grocery", "primary": true },
        { "id": "100-1000-0000", "name": "Restaurant" },
        { "id": "100-1000-0006", "name": "Deli" },
        { "id": "100-1000-0009", "name": "Fast Food" },
        { "id": "600-6000-0061", "name": "Convenience Store" },
        { "id": "600-6300-0064", "name": "Food/Beverage Specialty Store" },
        { "id": "600-6300-0067", "name": "Specialty Food Store" }
      ],
      "references": [
        { "supplier": { "id": "core" }, "id": "1221943904" },
        { "supplier": { "id": "core" }, "id": "31213861" },
        { "supplier": { "id": "tripadvisor" }, "id": "3172680" },
        { "supplier": { "id": "yelp" }, "id": "JNx0DlfndRurT-8KhSym7g" },
        { "supplier": { "id": "yelp" }, "id": "P44VNcZUUNZfiFy-c4SUJw" }
      ],
      "foodTypes": [
        { "id": "304-000", "name": "Italian", "primary": true },
        { "id": "800-057", "name": "Pizza" }],
      "contacts": [
        {
          "phone": [
            { "value": "+16175238743" },
            {
              "value": "+16177204243",
              "categories": [{ "id": "100-1000-0000" }, { "id": "100-1000-0006" }, { "id": "100-1000-0009" }]
            }
          ],
          "www": [
            {
              "value": "http://www.salumeriaitaliana.com",
              "categories": [
                { "id": "100-1000-0000" }, { "id": "100-1000-0006" }, { "id": "100-1000-0009" },
                { "id": "600-6300-0064" }, { "id": "600-6300-0066" }, { "id": "600-6300-0067" }
              ]
            }
          ],
          "email": [
            {
              "value": "[email protected]",
              "categories": [{ "id": "100-1000-0009" }, { "id": "600-6300-0066" }]
            }
          ]
        }
      ],
      "openingHours": [
        {
          "categories": [{ "id": "100-1000-0000" }],
          "text": ["Mon-Sat: 08:00 - 19:00", "Sun: 10:00 - 16:00"],
          "isOpen": true,
          "structured": [
            { "start": "T080000", "duration": "PT11H00M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA" },
            { "start": "T100000", "duration": "PT06H00M", "recurrence": "FREQ:DAILY;BYDAY:SU" }
          ]
        },
        {
          "categories": [{ "id": "600-6300-0067" }],
          "text": ["Mon-Thu: 09:30 - 18:00", "Fri, Sat: 09:00 - 19:00", "Sun: 09:30 - 16:00"],
          "isOpen": true,
          "structured": [
            { "start": "T093000", "duration": "PT08H30M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH" },
            { "start": "T090000", "duration": "PT10H00M", "recurrence": "FREQ:DAILY;BYDAY:FR,SA" },
            { "start": "T093000", "duration": "PT06H30M", "recurrence": "FREQ:DAILY;BYDAY:SU" }
          ]
        }
      ]
    }
  ]
}

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

各結果には次の上位要素が含まれます。

resultType - HERE Geocoding and Searchの/discoverエンドポイントは複数のタイプの項目を返すことができます：place、locality、streetなど
title - 場所や道路の名前など、結果の代表的な表記の文字列
address - 結果の詳細な住所。
position - 結果の代表的な地理的位置 (WGS 84)。これを使用して地図上に結果を表示します
access - 結果にアクセスするための地理的位置 (入口など)
id - 結果オブジェクトの識別子。この値を使用して /lookup エンドポイントからまったく同じオブジェクトを取得できます。

すべての結果に含まれると想定されるのは title、id、resultType、position の要素のみです。

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