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

本文演示如何：

• 使用搜索地址请求地址（地理编码地址位置）的纬度和经度坐标。
• 使用模糊搜索搜索地址或兴趣点 (POI)。
• 使用反向地址搜索，将坐标位置转换为街道地址。
• 使用 搜索地址反向十字街 API 将坐标位置转换为人可读的十字街。 这对于跟踪从设备或资产接收 GPS 数据的应用程序特别有用，需要确定这些坐标最近的街道级别位置。

先决条件

• Azure Maps 帐户
• 订阅密钥

本文使用 Bruno 应用程序，但可以选择不同的 API 开发环境。

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

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   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
   

4. 选择“创建”按钮。

5. 选择“运行”按钮。

   此请求会搜索特定地址：400 Broad St, Seattle, WA 98109。 接下来，搜索具有多个可能位置的地址。

6. 在“Params”部分中，将 键更改为 query，然后选择“运行”按钮。400 Broad, Seattle

   

7. 接下来，请尝试将 query 键设置为 400 Broa，然后选择“运行”按钮。

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

模糊搜索

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

使用模糊搜索搜索地址

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   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。 若要查找其他受支持的响应格式，请参阅 format中的 参数定义。

4. 选择“运行”按钮，然后查看响应正文。

   “pizza”的模糊查询字符串返回了“pizza”和“restaurant”类别中的 10 个兴趣点 (POI) 结果。 每个结果都包含相应位置的街道地址、纬度和经度值、视区和入口点。 现在此查询的结果各不相同，且与任何参照位置都不相关。

   在下一步中，你将使用 countrySet 参数，以便仅指定应用程序需要覆盖的国家/地区。 有关支持的国家/地区的完整列表，请参阅 Azure Maps 地理编码覆盖。

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

   

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

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

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

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

7. 选择“运行”。 响应包含西雅图太空针塔附近的比萨店。

使用反向地址搜索搜索街道地址

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

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 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
   

4. 选择“运行”按钮，并查看响应正文。 应该会看到一个查询结果。 响应包括有关 T-Mobile Park 的关键地址信息。

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

   密钥	值	返回
   数字	1	响应可能包含街道的边侧（左/右）以及该数字的偏移位置。
   returnSpeedLimit	true	返回该地址的速度限制。
   returnRoadUse	true	返回该地址的道路使用类型。 有关所有可能的道路使用类型，请参阅道路使用类型。
   returnMatchType	true	返回匹配类型。 若要查看所有可能的值，请参阅反向地址搜索结果。

   

6. 选择“运行”按钮，并查看响应正文。

7. 接下来，添加 entityType 键，并将其值设置为 Municipality。 entityType 键覆盖上一步中的 returnMatchType 键。 returnSpeedLimit 和 returnRoadUse 还需要删除，因为你正在请求有关市政当局的信息。 有关所有可能的实体类型，请参阅实体类型。

   

8. 选择“运行”按钮。 将结果与步骤 5 中返回的结果进行比较。 由于请求的实体类型现在为 municipality，因此响应不包含街道地址信息。 此外，返回的 geometryId 可用于通过 Azure Maps 获取搜索多边形 API 请求边界多边形。

使用反向地址十字街搜索来搜索十字街

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 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
   

4. 选择“运行”按钮，并查看响应正文。 注意，响应包含 crossStreet 的 South Atlantic Street 值。

本文演示如何：

• 使用 Get Geocoding 请求地址（地理编码地址位置）的纬度和经度坐标。
• 使用获取地理编码自动完成搜索部分地址。
• 使用 “获取反向地理编码 ”将坐标位置转换为街道地址。
• 使用获取反向地理编码将坐标位置转换为人类可理解的十字街，这在跟踪从设备或资产接收 GPS 源的应用程序以及希望知道坐标所在位置的应用程序时最常需要。

先决条件

• Azure Maps 帐户
• 订阅密钥

本文使用 Bruno 应用程序，但可以选择不同的 API 开发环境。

使用“获取地理编码”API请求地址的坐标

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   GET https://atlas.microsoft.com/geocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&query=400 Broad St, Seattle, WA 98109
   

4. 选择“创建”按钮。

5. 选择“运行”按钮。

   此请求会搜索特定地址：400 Broad St, Seattle, WA 98109。 接下来，搜索具有多个可能位置的地址。

6. 在“Params”部分中，将 键更改为 query，然后选择“运行”按钮。400 Broad, Seattle

7. 接下来，请尝试将 query 键设置为 400 Broa，然后选择“运行”按钮。

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

使用“地理编码自动填充”功能进行部分地址搜索

获取地理编码自动补全 API 支持单行和自由格式地址输入，因此非常适合完整地址不可用的场景。 可以将完整地址或部分地址作为查询提交。 若要提高结果的准确性和相关性，建议通过指定坐标或边界框来限制搜索。

搜索位置

此示例演示如何使用“Geocode Autocomplete API”搜索整个北美的部分输入，例如“华盛顿大学”。然后，它展示如何使用 countryRegion 参数将搜索范围缩小到特定国家或地区。 最后，它演示如何使用 coordinates 参数将搜索聚焦到特定区域。

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&subscription-key={Your-Azure-Maps-Subscription-key}
   

4. 选择“运行”按钮，然后查看响应正文。

   注意

   bbox URL 中的参数定义一个边界框，其中包含加拿大、美国、墨西哥、格陵兰和加勒比部分。 它返回位于该区域内的几所大学，包括：

   • 美国华盛顿 州金县华盛顿大学
   • 加拿大安大略省滑铁卢滑铁卢大学
   • 怀俄明 大学，美国怀俄明州拉米大学
   • 加拿大安大略省温莎温莎大学
   • 美国佛罗里达州埃斯坎比亚县西佛罗里达大学

接下来，使用 countryRegion 参数将搜索中包含的区域缩小到美国。

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&countryRegion=us&subscription-key={Your-Azure-Maps-Subscription-key}
   

4. 选择“运行”按钮，然后查看响应正文。

   注意

   bbox URL 中的参数定义了与上一示例中相同的边界框，而 countryRegion=us 参数则将结果仅限于美国。 它返回位于该区域内的几所大学，包括：

   • 美国华盛顿 州金县华盛顿大学
   • 怀俄明 大学，美国怀俄明州拉米大学
   • 美国佛罗里达州埃斯坎比亚县西佛罗里达大学
   • 威斯康星-苏必利尔大学，位于美国威斯康星州道格拉斯县
   • 威斯康星-斯托特大学，位于美国威斯康星州邓恩县的蒙莫尼市

接下来，使用 countryRegion 参数将搜索范围缩小到定义的 coordinates 内的特定区域，以包含更多结果。 这会导致更多原本不会被列入列表的项返回到指定区域附近。

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&countryRegion=us&coordinates=-122.136791,47.642232&subscription-key={Your-Azure-Maps-Subscription-key}
   

4. 选择“运行”按钮，然后查看响应正文。

   注意

   bbox 和 countryRegion 参数在此 URL 中定义了与上一示例相同的边界，而 coordinates=-122.136791,47.642232 参数则将搜索结果聚焦到指定区域。 它返回一所原本不会返回的本地大学。

   • 美国华盛顿 州金县华盛顿大学
   • 华盛顿大学，塔科马大学， 美国华盛顿州皮尔斯县塔科马
   • 怀俄明 大学，美国怀俄明州拉米大学
   • 美国佛罗里达州埃斯坎比亚县西佛罗里达大学
   • 威斯康星-斯托特大学，位于美国威斯康星州邓恩县的蒙莫尼市

搜索地址

本节中的示例演示了使用Get Geocode Autocomplete API参数进行地点搜索和地址搜索之间的区别。这些示例展示了如何使用部分输入（如“dis”）来搜索南加州的迪斯尼乐园，以及如何使用参数将搜索聚焦到特定区域。

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=dis&coordinates=-117.920219,33.809570&subscription-key={Your-Azure-Maps-Subscription-key}
   

4. 选择“运行”按钮，然后查看响应正文。

   请注意，响应中包含地点值，包括：

   属性名称	属性值
   typeGroup	地方
   类型	娱乐园
   姓名	迪斯尼加州冒险公园

   提示

   使用type时，该resultTypeGroups=place属性最相关。 若要查看可用类型，请参阅 Autocomplete ResultType 枚举。 若要定义要搜索的类型，请使用 resultTypesURI 参数。 有关实现详细信息，请参阅 自动完成 API 调用以搜索“Muir Woods”，按公园筛选并填充位置 resultTypes，放置 resultTypeGroups 示例。

5. 如果未为 resultTypeGroups 参数提供任何值，查询可以同时返回位置值和地址值。 如果仅对搜索地址感兴趣，请在请求中包括 resultTypeGroups=address ：

   https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=dis&coordinates=-117.920219,33.809570&resultTypeGroups=address&subscription-key={Your-Azure-Maps-Subscription-key}
   

   请注意， 响应包含地址 值，其中包括：

   属性名称	属性值
   typeGroup	地址
   街道名称	迪斯尼 乐园
   格式化地址	迪斯尼乐园，阿纳海姆，CA 92802，美国

使用“获取反向地理编码”搜索街道地址

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

此示例演示了使用几个可用的可选参数执行反向搜索。 有关可选参数的完整列表，请参阅 “获取反向地理编码参数”。

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&coordinates=-122.332700,47.591180
   

4. 选择“运行”按钮，并查看响应正文。 应该会看到一个查询结果。 响应包括有关 T-Mobile Park 的关键地址信息。

5. 接下来，将以下参数添加到请求： resultTypes=Postcode1

   https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&coordinates=-122.332700,47.591180&resultTypes=Postcode1
   

6. 选择“运行”按钮，并将结果与之前返回的结果进行比较。 由于请求的结果类型现在是 Postcode1，因此响应不包括街道地址信息，只是邮政编码。

使用“获取反向地理编码”搜索交叉路口

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

1. 打开 Bruno 应用程序。

2. 选择 “新建请求 ”以创建请求。 在“新建请求”窗口中，将“类型”设置为 HTTP。 输入请求的“名称”。

3. 在 URL 下拉列表中选择 GET HTTP 方法，然后输入以下 URL：

   https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&coordinates=-122.12429011774091,47.61697905124655&subscription-key={Your-Azure-Maps-Subscription-key}
   

4. 选择“运行”按钮，并查看响应正文。

   响应包括一个 intersection 部分，用于标识返回地址的街道部分： NE 8th St。它还指定相交的街道： 164 大道 NE，并提供完整的十字街，如： NE 8th St 和 164th Ave NE。

    "intersection": {
    "baseStreet": "NE 8th St",
    "displayName": "NE 8th St and 164th Ave NE",
    "intersectionType": "Near",
    "secondaryStreet1": "164th Ave NE"
    }