使用 Azure 地圖服務搜尋服務搜尋位置

  • 發行項

搜尋服務是一組 RESTful API，目的在於協助開發人員依名稱、類別和其他地理資訊搜尋地址、地點和公司清單。 除了支援傳統地理編碼之外，服務也可根據經緯度反向搜尋地理編碼地址和交叉路口。 搜尋傳回的緯度與經度值可用來做為其他 Azure 地圖服務的參數，例如路線和氣象。

本文會示範如何：

  • 使用搜尋地址要求地址 (地理編碼地址位置) 的緯度和經度座標。
  • 使用模糊搜尋搜尋地址或景點 (POI)。
  • 使用反向地址搜尋，將座標位置轉譯為街道地址。
  • 使用搜尋位址反向交叉街道，將座標位置轉譯為人類可理解的交叉街道，在追蹤從裝置或資產接收 GPS 摘要的應用程式時，最常需要，而且想要知道座標的位置。

必要條件

本教學課程使用 Postman 應用程式，但您可以選擇不同的 API 開發環境。

要求地址 (地理編碼) 的緯度和經度

本節範例使用 Azure 地圖服務取得搜尋地址，將地址轉換成緯度和經度座標。 此流程也稱為地理編碼。 除了傳回座標以外，回應也會傳回詳細的地址屬性，例如街道、郵遞區號、自治區和國家/區域資訊。

提示

如果您有一組要進行地理編碼的地址，可以使用搜尋後地址批次，在單一要求中傳送批次查詢。

  1. 在 Postman 應用程式中，選取 [新增] 以建立要求。 在 [新建] 視窗中，選取 [HTTP 要求]。 輸入要求的 [要求名稱]。

  2. 選取建立器索引標籤上的 GET HTTP 方法，然後輸入下列 URL。 在此要求中，我們會搜尋特定地址：400 Braod St, Seattle, WA 98109。 對於此要求以及本文中提及的其他要求，請將 {Your-Azure-Maps-Subscription-key} 取代為您的 Azure 地圖服務訂用帳戶金鑰。

    https://atlas.microsoft.com/search/address/json?&subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109

  3. 選取藍色的 [傳送] 按鈕。 回應本文包含單一位置的資料。

  4. 接下來，搜尋具有多個可能位置的地址。 在 [Params] 區段中，將 query 索引鍵變更為 400 Broad, Seattle。 選取藍色的 [傳送] 按鈕。

    Search for address

  5. 接下來，嘗試將 query 索引鍵設定為 400 Broa。

  6. 選取 [Send] \(傳送\) 按鈕。 回應包含來自多個國家/地區的結果。 若要為使用者顯示對相關區域的地理偏好結果，請一律在要求中盡可能新增最多位置詳細資料。

模糊搜尋支援標準單行和自由格式搜尋。 若您不知道搜尋查詢的使用者輸入型別，建議您使用 Azure 地圖服務的搜尋模糊 API。 查詢輸入可以是完整或部分地址， 也可以是景點 (POI) 權杖，例如 POI 名稱、POI 類別或品牌名稱。 此外，若要改善搜尋結果的相關性，使用座標位置和半徑或藉由定義周框方塊，加以限制查詢結果。

提示

大部分的搜尋查詢預設為 maxFuzzyLevel=1 以改善效能並減少不尋常的結果。 使用 maxFuzzyLevel 或 minFuzzyLevel 參數來調整模糊等級。 如需 maxFuzzyLevel 和所有選用參數完整清單的詳細資訊，請參閱模糊搜尋 URI 參數。

本節中的範例會使用 Fuzzy Search 來搜尋整個世界的披薩，然後搜尋特定國家/地區的範圍。 最後，這會示範如何使用座標位置和半徑設定特定區域的搜尋範圍，並限制傳回的結果數目。

重要

若要為使用者顯示對相關區域的地理偏好結果，請一律盡可能新增最多位置詳細資料。 如需詳細資訊，請參閱最佳搜尋做法。

  1. 在 Postman 應用程式中，選取 [新增] 以建立要求。 在 [新建] 視窗中，選取 [HTTP 要求]。 輸入要求的 [要求名稱]。

  2. 選取建立器索引標籤上的 GET HTTP 方法，然後輸入下列 URL。 對於此要求以及本文中提及的其他要求，請將 {Your-Azure-Maps-Subscription-key} 取代為您的 Azure 地圖服務訂用帳戶金鑰。

    https://atlas.microsoft.com/search/fuzzy/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=pizza

    注意

    URL 路徑中的 Json 屬性會判斷回應格式。 為了方便使用和可讀性，本文使用 json。 若要尋找其他支援的回應格式，請參閱 URI 參數參考文件中的 format 參數定義。

  3. 選取 [傳送]，然後檢閱回應本文。

    「pizza」的不明確查詢字串分別在「pizza」和「restaurant」類別中傳回 10 個景點結果 (POI)。 每個結果皆包含街道地址、緯度和經度值、檢視連接埠和位置進入點等詳細資料。 現在此查詢中的結果有所不同，且未繫結至任何參考位置。

    在下一個步驟中，您會使用 countrySet 參數，僅指定您應用程式需要涵蓋的國家/區域。 如需支援國家/區域的完整清單，請參閱搜尋涵蓋範圍。

  4. 預設行為會搜尋整個世界，因此可能傳回不必要的結果。 接下來，只會搜尋北美洲的披薩餐廳。 將 countrySet 索引鍵新增至 [Params] 區段，並將其值設定為 US。 把 countrySet 索引鍵設定為 US 會將結果繫結至北美洲。

    Search for pizza in the United States

    結果現在會依國家/地區程式碼繫結，此查詢會傳回美國境內的披薩餐廳。

  5. 若要取得目標更精確的搜尋，則可透過經緯座標組的範圍。 下列範例使用西雅圖太空針頭的經緯度座標。 由於我們只想傳回半徑 400 公尺內的結果，因此要新增 radius 參數。 此外，我們會新增 limit 參數，將結果限制為五個最接近的披薩餐廳地點。

    在 [Params] 區段中，新增下列索引鍵/值組：

    機碼 值
    lat 47.620525
    lon -122.349274
    半徑 400
    limit 5

  6. 請選取傳送。 回應包括西雅圖太空針塔附近披薩餐廳的結果。

取得搜尋地址反向會將座標轉譯成人類可讀懂的街道地址。 此 API 通常用於取用 GPS 摘要，且想探索特定座標點地址的應用程式。

重要

若要為使用者顯示對相關區域的地理偏好結果，請一律盡可能新增最多位置詳細資料。 如需詳細資訊，請參閱最佳搜尋做法。

提示

如果您有一組要進行反向地理編碼的座標位置，可以使用搜尋後地址反向批次，在單一要求呼叫中傳送批次查詢。

此範例會示範用一些可用的選用參數進行反向搜尋。 如需選用參數的完整清單，請參閱反向搜尋參數。

  1. 在 Postman 應用程式中，選取 [新增] 以建立要求。 在 [新建] 視窗中，選取 [HTTP 要求]。 輸入要求的 [要求名稱]。

  2. 選取建立器索引標籤上的 GET HTTP 方法，然後輸入下列 URL。 對於此要求以及本文中提及的其他要求，請將 {Your-Azure-Maps-Subscription-key} 取代為您的 Azure 地圖服務訂用帳戶金鑰。 要求應會類似於下列 URL：

    https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700&number=1

  3. 選取 [傳送]，然後檢閱回應本文。 您應該會看到一個查詢結果。 回應會包含關於薩菲柯球場的重要地址資訊。

  4. 接下來，要將下列索引鍵/值組新增至 [Params] 區段：

    機碼 值 傳回
    數值 1 回應可能包含街道邊 (左/右)，以及該號碼的位移位置。
    returnSpeedLimit true 傳回地址的速度限制。
    returnRoadUse true 傳回地址的道路使用型別。 如需所有可能的道路使用型別，請參閱道路使用型別。
    returnMatchType true 傳回符合型別。 如需所有可能的值，請參閱反向地址搜尋結果。

    Search reverse.

  5. 選取 [傳送]，然後檢閱回應本文。

  6. 接下來，我們會新增 entityType 索引鍵，並將其值設為 Municipality。 entityType 索引鍵會覆寫上一個步驟中的 returnMatchType 索引鍵。 由於您要求自治區相關資訊，因此也需移除 returnSpeedLimit 和 returnRoadUse。 如需所有可能的實體類型，請參閱實體類型。

    Search reverse entityType.

  7. 請選取傳送。 比較結果與步驟 5 傳回的結果。 由於目前要求的實體類型是 municipality，因此回應不包含街道地址資訊。 此外，傳回的 geometryId 可透過 Azure 地圖服務取得搜尋多邊形 API，用來要求界限多邊形。

提示

如需這些參數和其他參數的詳細資訊，請參閱反向搜尋參數。

此範例示範如何根據地址座標搜尋交叉路口。

  1. 在 Postman 應用程式中，選取 [新增] 以建立要求。 在 [新建] 視窗中，選取 [HTTP 要求]。 輸入要求的 [要求名稱]。

  2. 選取建立器索引標籤上的 GET HTTP 方法，然後輸入下列 URL。 對於此要求以及本文中提及的其他要求，請將 {Your-Azure-Maps-Subscription-key} 取代為您的 Azure 地圖服務訂用帳戶金鑰。 要求應會類似於下列 URL：

    https://atlas.microsoft.com/search/address/reverse/crossstreet/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700

    Search cross street.

  3. 選取 [傳送]，然後檢閱回應本文。 發現回應包含 South Atlantic Street 的 crossStreet 值。

下一步

Azure 地圖服務搜尋服務

Azure 地圖服務搜尋服務的最佳做法