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

迁移必应地图按查询查找位置 API

本文介绍如何将必应地图通过查询 API 查找位置迁移到 Azure Maps 获取地理编码 API。 Azure Maps 获取地理编码 API 用于获取街道地址、地点或地标的经度和纬度坐标。 Azure Maps Get Geocoding API 支持采用非结构化或结构化格式的地理编码输入。此迁移文档适用于地理编码输入数据（如街道地址、地区、邮政编码或地标名称）采用非结构化格式（query=）的情况，这类似于必应地图通过查询 API 所支持的查找位置功能。有关如何迁移必应地图方案（其中地理编码输入结构化以按地址查找位置）的信息，请参阅迁移必应地图的按地址查找位置 API。

先决条件

显著差异

必应地图通过查询 API 查找位置仅支持非结构化格式的地理编码输入，而 Azure Maps Get Geocoding API 支持非结构化（query=）或结构化（addressLine=）格式的地理编码输入。对于将地标名称进行地理编码，请使用 Azure Maps 的 Get Geocoding API，并采用非结构化输入格式。
必应地图通过查询 API 查找位置时返回的坐标为纬度/经度格式，而 Azure 地图的 Get Geocoding API 返回的坐标为经度/纬度格式（由 GeoJSON 格式定义）。
必应地图查找位置的查询 API 支持 XML 和 JSON 响应格式。 Azure Maps 获取地理编码 API 支持 GeoJSON。
与必应地图按查询 API 查找位置不同，Azure Maps Get Geocoding API 具有输入 view 参数，该参数表示 ISO 3166-1 Alpha-2 区域/国家/地区代码。输入 view 参数更改地缘政治争议边界和标签，使其与指定的用户区域保持一致。有关详细信息，请参阅 URI 参数。
与必应地图通过查询 API 查找位置不同，Azure Maps 获取地理编码 API 目前不支持中国的地址地理编码。
与必应地图企业版不同，Azure Maps 是一项支持指定地理范围的全局服务，允许对欧洲（欧盟）或美国（美国）地理区域（地理区域）的数据驻留限制。所有请求（包括输入数据）都专门在指定的地理区域进行处理。有关详细信息，请参阅地理范围。

安全性和身份验证

必应地图企业版仅支持 API 密钥身份验证。 Azure Maps 支持通过多种方式对 API 调用进行身份验证，例如订阅密钥、Microsoft Entra ID 和共享访问签名 (SAS) 令牌。有关 Azure Maps 中的安全性和身份验证的详细信息，请参阅 Azure Maps 获取地理编码文档中的 “使用 Azure Maps 进行身份验证 ”和“ 安全性”部分。

请求参数

下表列出了必应地图的 查找位置（通过查询）的请求参数以及 Azure Maps 的等效参数：

必应地图请求参数	必应地图请求参数别名	Azure Maps 请求参数	Azure Maps 中必需	Azure Maps 数据类型	Description
区域性	c	请求标头：Accept-Language	假	字符串	如 Azure Maps 请求标头中指定的， `culture` 定义使用 Azure Maps Get Geocoding API 时搜索结果中使用的语言。有关详细信息，请参阅支持的语言。
include	包括	不需要	不需要	不需要	使用必应地图的查询 API 查找位置时，需要通过 `include` 输入参数来获取响应中位置结果的两个字母的 ISO 国家代码（include=ciso2），并指定响应应显示如何将查询字符串解析为地址值（include=queryParse）。在 Azure Maps Get Geocoding API 中，默认返回双字母 ISO 国家/地区代码，并且不支持 queryParse 等效项。
includeNeighborhood	inclnb	不需要	不需要	不需要	在 Azure Maps Get Geocoding API 中，当可用时，社区信息默认在响应中返回。
maxResults	maxRes	返回页首	假	整数（int32）	在 Azure Maps 获取地理编码 API 中，返回的默认响应数为 5。最小值为 1，最大值为 20。
查询	q	查询	True	字符串
用户IP	uip	不支持	不支持	不支持
用户位置	ul	坐标	假	number[]	在 Azure Maps 获取地理编码 API 中，地球上的坐标指定为经度和纬度格式（经度,纬度）。指定此参数时，将考虑用户的位置，并且返回的结果与用户更相关。
userMapView	umv	bbox	假	number[]	地球上定义为边界框对象的矩形区域。矩形的两侧由经度和纬度值（经度1，纬度1，经度2，纬度2）定义。使用以下语法指定边界框：西经、南纬、东经、北纬如果指定此参数，则计算位置查询的结果时，将考虑地理区域。
userRegion	ur	视图	假	字符串	一个字符串，表示 ISO 3166-1 Alpha-2 区域/国家/地区代码。这会更改地缘政治争议边界和标签，使其与指定的用户区域保持一致。默认情况下，即使请求中未定义，View 参数也会设置为 “自动 ”。有关可用视图的详细信息，请参阅支持的视图。

有关 Azure Maps 获取地理编码 API 请求参数的详细信息，请参阅 URI 参数。

请求示例

必应地图 通过查询 API POST 请求查找位置：

http://dev.virtualearth.net/REST/v1/Locations/15127 NE 24th Street Redmond WA&key={BingMapsKey}

Azure Maps 获取地理编码 API POST 请求：

https://atlas.microsoft.com/geocode?api-version=2023-06-01&query=15127 NE 24th Street Redmond WA&subscription-key={Your-Azure-Maps-Subscription-key}

响应字段

下表列出了运行必应地图的“按查询查找位置”请求和 Azure Maps 等效请求时，HTTP 响应中可能出现的字段：

必应地图字段	Azure Maps 字段	Description
地址：addressLine （JSON）地址：地址行（XML）	地址：addressLine
地址：adminDistrict (JSON) 地址：AdminDistrict (XML)	地址：adminDistricts
地址：adminDistrict2 （JSON）地址：AdminDistrict2 （XML）	地址：adminDistricts
地址：国家地区（JSON）地址：CountryRegion （XML）	地址：国家或地区
地址：countryRegionIso2 (JSON) 地址：CountryRegionIso2 （XML）	地址：countryRegion - iso
地址：社区（JSON）地址：附近（XML）	地址：社区
address：formattedAddress（JSON）地址：“FormattedAddress” （XML）	地址：formattedAddress
address：locality（JSON）地址：区域（XML）	地址：地点
地址：postalCode （JSON）地址：邮政编码（XML）	地址：邮政编码
地址：交叉口 - baseStreet（JSON）地址：交汇点 - BaseStreet (XML)	地址：交汇点 - baseStreet
地址：交汇点 - secondaryStreet1 (JSON)	地址：交叉口 - 辅路1
地址：路口 - secondaryStreet2 （JSON）地址：路口 - SecondaryStreet2 （XML）	地址：交汇点 - secondaryStreet2
地址：交汇点 - intersectionType (JSON) 地址：交点 - 交点类型（XML）	地址：交叉点 - 交叉点类型
地址：Intersection – displayName（JSON）地址：十字路口-DisplayName（XML）	地址：交汇点 - displayName
bbox （JSON） BoundingBox （XML）	功能：bbox	在必应地图按查询 API 查找位置时，响应中的坐标采用纬度/经度格式。 Azure Maps Get Geocoding API 响应中的坐标采用经度/纬度格式（因为使用了 GeoJSON 格式）。
计算方法（JSON） CalculationMethod（XML）	属性：geocodePoints - calculationMethod
置信度（JSON）置信度（XML）	属性：置信度
entityType（JSON） EntityType （XML）	属性：类型
geocodePoints （JSON） GeocodePoint （XML）	属性：geocodePoints - 坐标
matchCodes（JSON） MatchCode （XML）	属性：matchCodes
名称（JSON）名称（XML）	不支持	`formattedAddress` 是 Azure Maps 等效项。
point (JSON) 点（XML）	功能：坐标	在必应地图按查询 API 查找位置时，响应中的坐标采用纬度/经度格式。 Azure Maps Get Geocoding API 响应中的坐标采用经度/纬度格式（因为使用了 GeoJSON 格式）。
queryParse(JSON) QueryParse （XML）	不支持
usageTypes（JSON） usageType （XML）	属性：geocodePoints:：usageTypes

有关 Azure Maps 获取地理编码 API 响应字段的详细信息，请参阅定义。

响应示例

以下 JSON 示例展示了在执行必应地图 按查询请求查找位置 时，HTTP 响应正文中返回的内容。

{ 
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.", 
    "resourceSets": [ 
        { 
            "estimatedTotal": 1, 
            "resources": [ 
                { 
                    "__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "bbox": [ 
                        47.62649628242932, 
                        -122.14631082421619, 
                        47.634221717570675, 
                        -122.1310271757838 
                    ], 
                    "name": "15127 NE 24th St, Redmond, WA 98052", 
                    "point": { 
                        "type": "Point", 
                        "coordinates": [ 
                            47.630359, 
                            -122.138669 
                        ] 
                    }, 
                    "address": { 
                        "addressLine": "15127 NE 24th St", 
                        "adminDistrict": "WA", 
                        "adminDistrict2": "King County", 
                        "countryRegion": "United States", 
                        "formattedAddress": "15127 NE 24th St, Redmond, WA 98052", 
                        "locality": "Redmond", 
                        "postalCode": "98052" 
                    }, 
                    "confidence": "High", 
                    "entityType": "Address", 
                    "geocodePoints": [ 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630359, 
                                -122.138669 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Display" 
                            ] 
                        }, 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630563, 
                                -122.1387383 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Route" 
                            ] 
                        } 
                    ], 
                    "matchCodes": [ 
                        "Good" 
                    ] 
                } 
            ] 
        } 
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "7896468b37528ac145ef77cc62484fd6|MWH0032BE2|0.0.0.1|Ref A: 7D01B283F7644D2891600E265FB30B24 Ref B: CO1EDGE2318 Ref C: 2024-04-23T18:29:55Z"

以下 JSON 示例演示执行 Azure Maps Get Geocoding 请求时 HTTP 响应正文中返回的内容：

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -122.138679,
                    47.630356
                ]
            },
            "bbox": [
                -122.14632082377759,
                47.62649328242932,
                -122.1310371762224,
                47.634218717570675
            ],
            "properties": {
                "type": "Address",
                "confidence": "High",
                "matchCodes": [
                    "Good"
                ],
                "geocodePoints": [
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Display"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138679,
                                47.630356
                            ]
                        }
                    },
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Route"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138685,
                                47.6305637
                            ]
                        }
                    }
                ],
                "address": {
                    "addressLine": "15127 NE 24th St",
                    "postalCode": "98052",
                    "locality": "Redmond",
                    "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
                    "countryRegion": {
                        "name": "United States",
                        "ISO": "US"
                    },
                    "adminDistricts": [
                        {
                            "shortName": "WA"
                        },
                        {
                            "shortName": "King County"
                        }
                    ]
                }
            }
        }
    ]
}

事务用法

与必应地图按查询查找位置 API 一样，Azure Maps 获取地理编码 API 也会针对每个请求记录一个计费事务。有关 Azure Maps 事务的详细信息，请参阅了解 Azure Maps 事务。

其他信息

获取地理编码批处理：用于在单个同步请求中向 Get Geocoding API 发送一批查询。

Support

Microsoft Q&A 论坛

反馈

此页面是否有帮助？

Last updated on 2025-10-31