你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure Maps 搜索服务来搜索位置

  • 项目

搜索服务是一组 REST API，旨在帮助开发人员按名称、类别和其他地理信息搜索地址、位置和业务列表。 除了支持传统的地理编码以外，该服务还可以根据纬度和经度对地址和十字街执行反向地理编码。 在诸如路线和天气服务之类的其他 Azure Maps 中，可将搜索返回的纬度和经度值用作参数。

本文演示了以下内容的操作方法：

  • 使用搜索地址请求地址（地理编码地址位置）的纬度和经度坐标。
  • 使用模糊搜索搜索地址或兴趣点 (POI)。
  • 使用反向地址搜索，将坐标位置转换为街道地址。
  • 使用搜索地址反向十字街将坐标位置转换为人类可理解的十字街，这在跟踪从设备或资产接收 GPS 源的应用程序以及希望知道坐标所在位置的应用程序时最常需要。

先决条件

本教程使用 Postman 应用，但你也可以选择其他 API 开发环境。

请求地址的纬度和经度（地理编码）

本部分中的示例使用获取搜索地址将地址转换为纬度和经度坐标。 此过程也称为“地理编码”。 除了返回坐标外，响应还会返回详细的地址属性，例如街道、邮政编码、市政当局和国家/地区信息。

提示

如果你有一组需执行地理编码的地址，则可以使用发布搜索地址批处理，以通过单个请求发送一批查询。

  1. 在 Postman 应用中，选择“新建”以创建请求。 在“新建”窗口中，选择“HTTP 请求” 。 在“请求名称”中，输入请求名称。

  2. 在生成器选项卡中选择“GET”HTTP 方法，然后输入以下 URL。 在此请求中，我们要搜索特定地址：400 Braod St, Seattle, WA 98109。 对于此请求和本文中提到的其他请求，请将 {Your-Azure-Maps-Subscription-key} 替换为你的 Azure Maps 订阅密钥。

    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. 接下来，搜索具有多个可能位置的地址。 在“参数”部分中，将 query 键更改为 400 Broad, Seattle。 选择蓝色的“发送”按钮。

    Search for address

  5. 接下来，尝试将 query 键设置为 400 Broa。

  6. 选择“发送”按钮 。 响应包括来自多个国家/地区的结果。 若要让结果在地理上偏近用户的相关区域，始终要在请求中添加尽可能多的位置详细信息。

模糊搜索支持标准单行搜索和自由格式搜索。 如果不知道搜索请求的用户输入类型，我们建议使用 Azure Maps 模糊搜索 API。 此查询输入可以是完整或部分地址。 它还可以是兴趣点 (POI) 标记，如 POI 名称、POI 类别或品牌名称。 此外，若要改善搜索结果的相关性，请使用坐标位置和半径或通过定义边界框来限制查询结果。

提示

大多数搜索查询默认指定 maxFuzzyLevel=1，以提高性能并减少不正常的结果。 使用 maxFuzzyLevel 或 minFuzzyLevel 参数调整模糊度。 有关 maxFuzzyLevel 的详细信息以及所有可选参数的完整列表，请参阅模糊搜索 URI 参数。

本部分中的示例使用 Fuzzy Search 在整个世界范围内搜索“pizza”，然后在特定国家/地区范围内搜索。 最后，演示如何使用坐标位置和半径来将搜索限定在特定区域内，并限制返回的结果数。

重要

若要让结果在地理上偏近用户的相关区域，始终要添加尽可能多的位置详细信息。 有关详细信息，请参阅搜索最佳做法。

  1. 在 Postman 应用中，选择“新建”以创建请求。 在“新建”窗口中，选择“HTTP 请求” 。 在“请求名称”中，输入请求名称。

  2. 在生成器选项卡中选择“GET”HTTP 方法，然后输入以下 URL。 对于此请求和本文中提到的其他请求，请将 {Your-Azure-Maps-Subscription-key} 替换为你的 Azure Maps 订阅密钥。

    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. 默认行为是在全球搜索，这样可能会返回不需要的结果。 接下来，仅在美国范围内搜索 pizza。 将 countrySet 键添加到“参数”部分，并将其值设置为 US。 将 countrySet 键设置为 US 会将结果限定在美国范围内。

    Search for pizza in the United States

    结果现在受限为国家/地区代码，查询返回了美国境内的比萨餐馆。

  5. 若要执行更具针对性的搜索，可以在纬度/经度坐标对的范围内搜索。 以下示例使用西雅图太空针塔的维度/经度坐标。 由于我们只想返回 400 米半径范围内的结果，因此我们添加 radius 参数。 此外，我们还添加 limit 参数，将结果限制为最近的五个比萨店位置。

    在“参数”部分中，添加以下键/值对：

    密钥 值
    lat 47.620525
    lon -122.349274
    radius 400
    limit 5

  6. 选择“发送”。 响应包含西雅图太空针塔附近的比萨店。

获取搜索地址反向将坐标转换为人类可理解的街道地址。 此 API 通常用于使用 GPS 源并且要发现位于特定坐标点的地址的应用程序。

重要

若要让结果在地理上偏近用户的相关区域，始终要添加尽可能多的位置详细信息。 有关详细信息，请参阅搜索最佳做法。

提示

如果你有一组需要执行反向地理编码的坐标位置，则可以使用 发布搜索地址反向批处理，以通过单个请求发送一批查询。

此示例演示了使用几个可用的可选参数执行反向搜索。 有关可选参数的完整列表，请参阅反向搜索参数。

  1. 在 Postman 应用中，选择“新建”以创建请求。 在“新建”窗口中，选择“HTTP 请求” 。 在“请求名称”中，输入请求名称。

  2. 在生成器选项卡中选择“GET”HTTP 方法，然后输入以下 URL。 对于此请求和本文中提到的其他请求，请将 {Your-Azure-Maps-Subscription-key} 替换为你的 Azure Maps 订阅密钥。 请求应如下面的 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. 选择“发送”并查看响应正文。 应该会看到一个查询结果。 该响应包括有关 Safeco Field 的关键地址信息。

  4. 接下来，在“参数”部分中，添加以下键/值对：

    项 值 返回
    数字 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 Maps 获取搜索多边形 API 请求边界多边形。

提示

有关这些参数以及其他参数的详细信息，请参阅反向搜索参数。

此示例演示如何根据地址的坐标搜索十字街。

  1. 在 Postman 应用中，选择“新建”以创建请求。 在“新建”窗口中，选择“HTTP 请求” 。 在“请求名称”中，输入请求名称。

  2. 在生成器选项卡中选择“GET”HTTP 方法，然后输入以下 URL。 对于此请求和本文中提到的其他请求，请将 {Your-Azure-Maps-Subscription-key} 替换为你的 Azure Maps 订阅密钥。 请求应如下面的 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 Maps 搜索服务

Azure Maps 搜索服务的最佳做法