Browse

/browse エンドポイントでは特定の地理的位置での構造化検索が可能で、半径 250 km の範囲内でカテゴリーと名前を使って項目を絞り込むことができます。

返される項目は場所、番地、地域で、距離の長さによって順位付けされます。

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

/browseエンドポイントは、指定された検索地点から最大半径250 km以内のHERE Geocoding and Searchインデックスデータを返します。

検索地点は入力クエリのパラメーターatで指定された地理的位置によって定義されます。項目の距離はこの検索地点を基準に計算されます。

さらに、検索地点から 250 km 以内の暗黙的なフィルターに加えて、/browse はクエリパラメーター in による 3 つの追加の地理的フィルターにも対応しています。

円 (in パラメーターのタイプ circle)
バウンディングボックス (in パラメーターのタイプ bbox)
ISO 3166-1 alpha-3の大文字の国コードのリスト(inパラメーターのタイプcountryCode)

HERE Geocoding and Searchは国グループ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。

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

/browse で許可されている at と in の組み合わせの一覧は次のとおりです。

at
at と in=countryCode
at と in=circle
at と in=circle および in=countryCode
at と in=bbox
at と in=bbox および in=countryCode

複数の粒度でのプレースカテゴリーフィルター

/browseエンドポイントを使用すると、指定した位置にある特定のHERE PlacesカテゴリーまたはHERE Places料理タイプの場所を取得できます。それぞれ、クエリパラメーターのcategoriesとfoodTypesを使用します。

HERE Placesカテゴリーはcategoriesフィールドの値として、次の3つのレベルから指定できます。

上位のレベル1 (_飲食_ができる場所100など)
粒度が中位のレベル 2 (_レストラン_の場所 100-1000 など)
詳細なカテゴリーのレベル3 (_高級料理店_の場所100-1000-0002など)

HERE Places料理タイプはfoodTypesフィールドの値として、次の 2 つのレベルから指定できます。

上位のレベル1 (中華料理を提供する場所201など)
詳細な料理のレベル 2 (四川料理を提供している場所 201-009 など)

categories クエリフィールドも foodTypes クエリフィールドも複数の値に対応できます (カンマ区切り)。

例 1

たとえば、車載アプリケーションまたはモバイルアプリケーションでガソリンスタンドを示すアイコンを表示し、 /browseクエリのcategoriesパラメーターの値としてカテゴリーID 700-7600-0000,700-7600-0116を使用します。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=47.80049,3.57119
    &limit=2
    &categories=700-7600-0000,700-7600-0116
    &apiKey={YOUR_API_KEY}

このクエリの予想される結果は次のようになります。

{
  "items": [
    {
      "title": "E.Leclerc Traiteur Auxerre",
      "id": "here:pds:place:250u06xc-4555b052028de84cfb33cdf404dd63d5",
      "distance": 713,
      "categories": [{ "id": "700-7600-0116", "name": "Stations service", "primary": true }],
      "chains": [{ "id": "253", "name": "E. LECLERC" }],
      ...
    },
    {
      "title": "Total",
      "id": "here:pds:place:250u06xc-f9bea569497c4bac907f478cd4d9cb0d",
      "distance": 926,
      "categories": [
        { "id": "700-7600-0116", "name": "Stations service", "primary": true },
        { "id": "700-7850-0000", "name": "Garage auto" }
      ],
      "chains": [{ "id": "35", "name": "TotalEnergies" }],
      ...
    }
  ]
}

例2

観光客向けのモバイルアプリケーションでは、次の組み合わせを使用できます。

歴史的記念物 (300-3000-0025) と博物館 (300-3100)
ショッピングモール/センター (600-6100-0062)
公園 (550-5510-0202) とレジャー施設 (500-5520)

イタリアのローマにある場所からのクエリは次のようになります。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=41.93088,12.46803
    &limit=5
    &categories=300-3000-0025,300-3100,550-5510-0202,500-5520,600-6100-0062
    &apiKey={YOUR_API_KEY}

このクエリの予想される結果は次のようになります。

{
  "items": [
    {
      "title": "Parco Giochi Primo Sport 0246 - Roma",
      "id": "here:pds:place:380aabd1-7f7d1d1c8d4f038bcb5c5170c3a8a8c2",
      "distance": 118,
      "categories": [
        { "id": "550-5510-0202", "name": "Parco pubblico", "primary": true },
        { "id": "300-3000-0000", "name": "Punto di riferimento o attrazione" },
        { "id": "550-5520-0000", "name": "Parco divertimenti" }
      ],
      ...
    },
    {
      "title": "Maxxi",
      "id": "here:pds:place:380sr2ye-6e5ede6451bd2da9bf4598ff14de9716",
      "distance": 285,
      "categories": [{ "id": "300-3100-0029", "name": "Museo delle arti", "primary": true }, { "id": "300-3000-0000", "name": "Punto di riferimento o attrazione" }],
      ...
    },
    {
      "title": "Maxxi Museo Nazionale delle Arti del ventunesimo Secolo",
      "id": "here:pds:place:380sr2ye-3f8bfb611d1640e88a8577457c00b118",
      "distance": 285,
      "categories": [
        { "id": "300-3100-0029", "name": "Museo delle arti", "primary": true },
        { "id": "100-1000-0000", "name": "Ristorante" },
        { "id": "100-1100-0000", "name": "Caffè/Tè" },
        { "id": "300-3000-0000", "name": "Punto di riferimento o attrazione" },
        { "id": "300-3000-0023", "name": "Attrazione turistica" },
        { "id": "300-3100-0000", "name": "Museo" },
        { "id": "900-9300-0221", "name": "Edificio residenziale" }
      ],
      ...
    },
    {
      "title": "The Adventures of Alice",
      "id": "here:pds:place:380sr2ye-ced95a0feb6a925398849e4a1be972b9",
      "distance": 328,
      "categories": [{ "id": "300-3100-0027", "name": "Museo per bambini", "primary": true }, { "id": "300-3100-0000", "name": "Museo" }],
      ...
    },
    {
      "title": "Museo Archeologico, Orario Invernale",
      "id": "here:pds:place:380sr2ye-912af843284527e531b505d22a594eea",
      "distance": 487,
      "categories": [
        { "id": "300-3100-0000", "name": "Museo", "primary": true },
        { "id": "300-3100-0028", "name": "Museo storico" },
        { "id": "300-3100-0029", "name": "Museo delle arti" }
      ],
      ...
    }
  ]
}

例3

先ほどの例のモバイルアプリケーションでは、レストランのカテゴリーとそこで提供されている料理の組み合わせも使用できます。

ファストフード (100-1000-0009)
インド料理またはパキスタン料理 (202 または 208)

そうすると、ロンドンにある場所からのクエリは次のようになります。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=51.51979,-0.088
    &limit=5
    &categories=100-1000-0009
    &foodTypes=202,208
    &apiKey={YOUR_API_KEY}

このクエリの予想される結果は次のようになります。

{
  "items": [
    {
      "title": "Tifinbox",
      "id": "here:pds:place:826aabd1-e9ad6c1db5e50115cc767baf608af548",
      "distance": 851,
      "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        { "id": "100-1000-0003", "name": "Take Out & Delivery Only" },
        { "id": "100-1000-0009", "name": "Fast Food" },
        { "id": "100-1100-0010", "name": "Coffee Shop" }
      ],
      "foodTypes": [
        { "id": "202-000", "name": "Indian", "primary": true },
        { "id": "200-000", "name": "Asian" },
        { "id": "308-000", "name": "British Isles" },
        { "id": "800-050", "name": "Fast Food" },
        { "id": "800-058", "name": "Snacks & Beverages" },
        { "id": "800-064", "name": "International" }
      ],
      ...
    },
    {
      "title": "Chicken Run",
      "id": "here:pds:place:826gcpvn-c0598761d74c472cb5d8242dd7c44b6c",
      "distance": 1008,
      "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        { "id": "100-1000-0003", "name": "Take Out & Delivery Only" },
        { "id": "100-1000-0009", "name": "Fast Food" }
      ],
      "foodTypes": [
        { "id": "800-062", "name": "Chicken", "primary": true },
        { "id": "101-000", "name": "American" },
        { "id": "202-000", "name": "Indian" },
        { "id": "308-000", "name": "British Isles" },
        { "id": "800-050", "name": "Fast Food" }
      ],
      ...
    },
    {
      "title": "Bhaji's",
      "id": "here:pds:place:826gcpvj-98c36252b22a40ee9f1a6ec602a9ba44",
      "distance": 1063,
      "categories": [{ "id": "100-1000-0000", "name": "Restaurant", "primary": true }, { "id": "100-1000-0009", "name": "Fast Food" }],
      "foodTypes": [{ "id": "202-000", "name": "Indian", "primary": true }, { "id": "208-000", "name": "Pakistani" }],
      ...
    },
    {
      "title": "Bs Foods",
      "id": "here:pds:place:826gcpvn-d1cb2bffe48840b3ae17b7663c35d303",
      "distance": 1171,
      "categories": [
        { "id": "100-1000-0009", "name": "Fast Food", "primary": true },
        { "id": "100-1000-0000", "name": "Restaurant" },
        { "id": "100-1000-0003", "name": "Take Out & Delivery Only" },
        { "id": "600-6300-0067", "name": "Specialty Food Store" }
      ],
      "foodTypes": [{ "id": "202-000", "name": "Indian", "primary": true }, { "id": "800-064", "name": "International" }],
      ...
    },
    {
      "title": "Fig & Olive",
      "id": "here:pds:place:826gcpvj-427179ed410567ab0267a22cbf0aef6c",
      "distance": 1254,
      "categories": [{ "id": "100-1000-0009", "name": "Fast Food", "primary": true }, { "id": "100-1000-0000", "name": "Restaurant" }],
      "foodTypes": [
        { "id": "800-057", "name": "Pizza", "primary": true },
        { "id": "200-000", "name": "Asian" },
        { "id": "202-000", "name": "Indian" },
        { "id": "800-050", "name": "Fast Food" },
        { "id": "800-075", "name": "Seafood" }
      ],
      ...
  ]
}

プレースチェーンフィルター

categoriesとfoodTypesのクエリフィルターに加えて、/browseエンドポイントではchainsクエリフィルターも提供されています。

HEREチェーンIDの任意の組み合わせを使用して、該当するチェーンの場所を取得できます。

たとえば、自動車メーカーのコンパニオンアプリでcategories=700-7850-0122&chains=299というフィルターを使用すると、近隣にある修理工場で、その自動車メーカーブランドを扱うもののみを取得できます。

除外フィルター

/browseエンドポイントでは、特定のカテゴリー、料理、チェーン_以外_の場所を取得することもできます。この場合、この場合感嘆符 (!) をカテゴリーID、料理ID、チェーンIDの前に付ける必要があります。除外する値と含める値の両方を同じフィールドに含めることができます。除外するカテゴリーは含めるカテゴリーよりも優先されます。

たとえば、ファストフードレストランを除くすべてのレストランを取得するには、アプリケーションはBrowseクエリにcategories=100-1000,!100-1000-0009を追加します。

名前フィルター

位置をフィルタリングするもう 1 つの方法は name フィルターの使用です。

このフィルターはカテゴリーフィルターを補完するものとしても役に立ちますが、単独でも使用できます。

具体的には、/browseエンドポイントによって返される各結果には、1つ以上の名前にnameフィルター値の各トークンが含まれています。

たとえば、モバイルアプリケーションでPetrobrasのガソリンスタンドを表すアイコンを表示する場合、 categoriesパラメーターにカテゴリID 700-7600-0000,700-7600-0116を指定し、さらにnameパラメーターに「Petrobras」を設定します。

なお、/browseエンドポイントのnameフィルターは、発音記号の有無に関係なく名前トークンを照合します。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=-23.000813,-43.351629
    &categories=700-7600-0000,700-7600-0116
    &limit=3&lang=en-US
    &name=petrobras
    &apiKey={YOUR_API_KEY}

このクエリの予想される結果は次のようになります。

{
  "items": [
    {
      "title": "Petrobras",
      "id": "here:pds:place:07655b54-303f70db75afadf86c2b61953c3c7fb6",
      "distance": 47,
      "categories": [{ "id": "700-7600-0116", "name": "Posto de combustível", "primary": true }],
      "chains": [{ "id": "4017", "name": "Petrobras" }],
      ...
    },
    {
      "title": "4017",
      "id": "here:pds:place:07675cjj-b8103bd885d428acbb6b55e78cb38d4f",
      "distance": 1017,
      "categories": [{ "id": "700-7600-0116", "name": "Posto de combustível", "primary": true }, { "id": "600-6000-0061", "name": "Loja de Conveniência" }],
      "chains": [{ "id": "4017", "name": "Petrobras" }],
      ...
    },
    {
      "title": "Petrobras",
      "id": "here:pds:place:07675cjj-ce7df2e0f8d74c68a323b4ba474b736f",
      "distance": 1172,
      "categories": [{ "id": "700-7600-0116", "name": "Posto de combustível", "primary": true }],
      "chains": [{ "id": "4017", "name": "Petrobras" }],
      ...
    }
  ]
}

言語優先設定

/browse結果項目で優先言語を適用する必要があるアプリケーションは、langパラメーターに必要なBCP 47言語コードを設定する必要があります。

可能な限り、エンドポイントは構造化されたレスポンス項目を指定された言語で表示します。langが設定されていない場合、または結果項目にリクエストされた言語の翻訳が存在しない場合は、デフォルトの言語が使用されます。

周辺

/browseエンドポイントの特殊なユースケースとして、名前またはカテゴリーで絞り込みをせずに、指定した位置の周辺にある場所、道路、地域を返す方法があります。

たとえば、シカゴ内の位置(41.89296,-87.62283)で10項目を取得する場合、顧客は次のようなクエリを送信します。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=41.89344,-87.62406
    &limit=10
    &apiKey={YOUR_API_KEY}

このクエリの予想される結果は次のようになります。

{
 "items": [
   {
     "title": "N St Clair St, Chicago, IL 60611, United States",
     "id": "here:af:street:eV0uyr2TvcpfdLCTfbpurC",
     "resultType": "street",
     ...
   },
   {
     "title": "N Saint Clair St, Chicago, IL 60611, United States",
     "id": "here:af:street:Kr6eYtK0ihAE7z-IfffUDB",
     "resultType": "street",
     ...
   },
   {
     "title": "System Parking",
     "id": "here:pds:place:840dp3wq-f9e63058fb95162b048da6c56b03555e",
     "resultType": "place",
     ...
   },
   {
     "title": "Lavazza Coffee Cafe",
     "id": "here:pds:place:840dp3wq-7aeb9307f97903b4284d998975098951",
     "resultType": "place",
     ...
   },
   {
     "title": "Innbar",
     "id": "here:pds:place:840cc9e6-89a36e059babf45d3ef5bae7176349fb",
     "resultType": "place",
     ...
   },
   ...
 ]
}

1つ目の結果は道路、2つ目は場所、などのようになります。

結果に場所のみが含まれるようにするには、すべてのレベル 1 カテゴリーの承認リストが必要です。

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=41.89344,-87.62406
    &limit=10
    &categories=100,200,300,350,400,500,550,600,700,800,900
    &apiKey={YOUR_API_KEY}

ルート沿い

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

絞り込みとワンボックス

/discoverエンドポイントは送信者(人間)の検索リクエストの意図を推測するのに対し、 /browseエンドポイントはリクエストをより機械的に、またはより厳密に解釈します。

たとえば、「New York Pizza」というリクエストを送信した場合、/discoverエンドポイントは「ニューヨーク市にあるピザを提供するレストラン」の結果を返します。これに対し、/browseエンドポイントは「New York Pizza」という名前のレストランを返します。

別の例として、ドイツのエンドユーザーはガソリンスタンドを検索する際、「Tankstellen」というフレーズを/discoverエンドポイントに送信します。一方、車載アプリケーションでは、ガソリンスタンドを表すカテゴリーID (700-7600-0000)とともに、/browseエンドポイントにリンクされた事前定義済みのカテゴリー検索ショートカットを表示します。

並べ替えも同様に異なります。/discoverエンドポイントの結果は主に関連性に基づいて並べ替えられるのに対し、 /browseエンドポイントの結果は常に距離順で並べ替えられます。