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

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

2024-05-17

本文介绍如何将必应地图按点查找位置 API 迁移到 Azure Maps 获取反向地理编码 API。 Azure Maps 获取反向地理编码 API 用于将经度和纬度坐标转换为人类可理解的街道地址。

先决条件

明显区别

必应地图按点查找位置 API 支持 XML 和 JSON 响应格式。 Azure Maps 获取反向地理编码 API 支持 GeoJSON 响应格式。
必应地图按点查找位置 API 采用纬度/经度格式的坐标。 Azure Maps 获取反向地理编码 API 采用经度/纬度格式的坐标（如 GeoJSON 所定义）。
与必应地图按点查找位置 API 不同，Azure Maps 获取反向地理编码 API 目前不支持中国、日本或韩国的地址或街道级别数据。
与必应地图按点查找位置 API 不同，Azure Maps 获取反向地理编码 API 有一个 view 输入参数，这是一个表示 ISO 3166-1 Alpha-2 区域/国家/地区代码的字符串。 view 输入参数将更改地缘政治争议边界和标签，以与指定的用户区域保持一致。有关详细信息，请参阅 URI 参数。
与必应地图企业版不同，Azure Maps 是一项支持指定地理范围的全局服务，可用于将数据驻留限制为欧洲 (EU) 或美国 (US) 地理区域（地区）。所有请求（包括输入数据）都专门在指定的地理区域进行处理。有关详细信息，请参阅 Azure Maps 服务地理范围。

安全性和身份验证

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

请求参数

下表列出了必应地图按点查找位置请求参数和 Azure Maps 等效参数：

必应地图请求参数	必应地图请求参数别名	Azure Maps 请求参数	在 Azure Maps 中必需	Azure Maps 数据类型	说明
culture	c	请求头：Accept-Language	False	string	在 Azure Maps 获取反向地理编码 API 中，这是返回搜索结果时应使用的语言。这在 Azure Maps 请求头中指定。有关详细信息，请参阅支持的语言。
include	incl	无需	无需	无需	在必应地图按点查找位置中，需要“include”输入参数才能获取响应中位置结果的两个字母的 ISO 国家/地区代码。在 Azure Maps 获取反向地理编码 API 中，默认返回两个字母的 ISO 国家/地区代码。
includeEntityTypes		resultTypes	False	查询
includeNeighborhood	inclnb	无需	无需	无需	在 Azure Maps 获取反向地理编码 API 中，默认情况下，近邻信息会在响应中返回（如果可用）。
point		坐标	True	number[]	在必应地图按点 API 查找位置时，请求中的坐标和响应采用纬度/经度格式，而 Azure Maps 获取反向地理编码 API 要求请求中的坐标和响应中的坐标采用经度/纬度格式，如 GeoJSON所定义。
userRegion	ur	视图	False	string	一个字符串，表示 ISO 3166-1 Alpha-2 区域/国家/地区代码。它将更改地缘政治争议边界和标签，以与指定的用户区域保持一致。默认情况下，“视图”参数设置为“自动”，即使你未在请求中定义它也是如此。有关详细信息，请参阅支持的视图，并查看可用的视图。
verboseplacenames	vbpn	不支持	不支持	不支持	Azure Maps 获取反向地理编码 API 仅支持返回 adminDistricts 短名称（FL 而不是佛罗里达州）。

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

请求示例

必应地图按点查找位置 API 请求：

https://dev.virtualearth.net/REST/v1/Locations/48.830345,2.338166&key={BingMapsKey}

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

http://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates=2.338166,48.830345&subscription-key={Your-Azure-Maps-Subscription-key}

响应字段

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

必应地图响应	Azure Maps 响应	说明
地址：addressLine (JSON) 地址：AddressLine (XML)	地址：addressLine
地址：adminDistrict (JSON) 地址：AdminDistrict (XML)	地址：adminDistricts
地址：adminDistrict2 (JSON) 地址：AdminDistrict2 (XML)	地址：adminDistricts
地址：countryRegion (JSON) 地址：CountryRegion (XML)	地址：countryRegion
地址：countryRegionIso2 (JSON) 地址：CountryRegionIso2 (XML)	地址：countryRegion - iso
地址：neighborhood (JSON) 地址：Neighborhood (XML)	地址：neighborhood
地址：formattedAddress (JSON) 地址：FormattedAddress (XML)	地址：formattedAddress
地址：locality (JSON) 地址：Locality (XML)	地址：locality
地址：postalCode (JSON) 地址：PostalCode (XML)	地址：postalCode
地址：交汇点 – baseStreet (JSON) 地址：交汇点 – BaseStreet (XML)	地址：交汇点 -baseStreet
地址：交汇点 – secondaryStreet1 (JSON) 地址：交汇点 – SecondaryStreet1 (XML)	地址：交汇点 - secondaryStreet1
地址：交汇点 – secondaryStreet2 (JSON) 地址：交汇点 – SecondaryStreet2 (XML)	地址：交汇点 - secondaryStreet2
地址：交汇点 – intersectionType (JSON) 地址：交汇点 – IntersectionType (XML)	地址：交汇点 - intersectionType
地址：交汇点 – displayName (JSON) 地址：交汇点 – DisplayName (XML)	地址：交汇点 - displayName
bbox (JSON) BoundingBox (XML)	功能：bbox	在必应地图按点查找位置 API 中，响应中的坐标采用纬度/经度格式。 Azure Maps 获取反向地理编码 API 采用经度/纬度格式的坐标（如 GeoJSON 所定义）。
calculationMethod (JSON) CalculationMethod (XML)	属性：geocodePoints - calculationMethod
置信度 (JSON) 置信度 (XML)	属性：置信度
entityType (JSON) EntityType (XML)	属性：类型
geocodePoints (JSON) GeocodePoint (XML)	属性：geocodePoints - 坐标
matchCodes (JSON) MatchCode (XML)	属性：matchCodes
名称 (JSON) 名称 (XML)	不支持	Azure Maps `formattedAddress` 提供与必应地图 `name` 类似的值
点 (JSON) 点 (XML)	功能：坐标	在必应地图按点查找位置 API 中，响应中的坐标采用纬度/经度格式。 Azure Maps 获取反向地理编码 API 采用经度/纬度格式的坐标（如 GeoJSON 所定义）。
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": [
                        48.826534682429326,
                        2.330334564829834,
                        48.83426011757068,
                        2.345980835170166
                    ],
                    "name": "30 Rue Cabanis, 75014 Paris, France",
                    "point": {
                        "type": "Point",
                        "coordinates": [
                            48.8303974,
                            2.3381577
                        ]
                    },
                    "address": {
                        "addressLine": "30 Rue Cabanis",
                        "adminDistrict": "Île-de-France",
                        "adminDistrict2": "Paris",
                        "countryRegion": "France",
                        "formattedAddress": "30 Rue Cabanis, 75014 Paris, France",
                        "intersection": {
                            "baseStreet": "Rue Cabanis",
                            "secondaryStreet1": "Villa de Lourcine",
                            "intersectionType": "Near",
                            "displayName": "Rue Cabanis and Villa de Lourcine"
                        },
                        "locality": "Paris",
                        "neighborhood": "14th Arrondissement",
                        "postalCode": "75014"
                    },
                    "confidence": "High",
                    "entityType": "Address",
                    "geocodePoints": [
                        {
                            "type": "Point",
                            "coordinates": [
                                48.8303974,
                                2.3381577
                            ],
                            "calculationMethod": "Rooftop",
                            "usageTypes": [
                                "Display"
                            ]
                        }
                    ],
                    "matchCodes": [
                        "Good"
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "c525b02f7f1e9e4ee3d7b81cce266671"

以下 JSON 示例显示了执行 Azure Maps 获取反向地理编码请求时，HTTP 响应正文中返回的内容：

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    2.3381577,
                    48.8303974
                ]
            },
            "properties": {
                "geocodePoints": [
                    {
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                2.3381577,
                                48.8303974
                            ]
                        },
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Display"
                        ]
                    }
                ],
                "address": {
                    "addressLine": "30 Rue Cabanis",
                    "adminDistricts": [
                        {
                            "shortName": "Île-de-France"
                        },
                        {
                            "shortName": "Paris"
                        }
                    ],
                    "countryRegion": {
                        "name": "France",
                        "iso": "FR"
                    },
                    "intersection": {
                        "baseStreet": "Rue Cabanis",
                        "displayName": "Rue Cabanis and Villa de Lourcine",
                        "intersectionType": "Near",
                        "secondaryStreet1": "Villa de Lourcine",
                        "secondaryStreet2": null
                    },
                    "locality": "Paris",
                    "neighborhood": "14th Arrondissement",
                    "postalCode": "75014",
                    "formattedAddress": "30 Rue Cabanis, 75014 Paris, France"
                },
                "confidence": "High",
                "matchCodes": [
                    "Good"
                ],
                "type": "Address"
            },
            "bbox": [
                2.330334564829834,
                48.826534682429326,
                2.345980835170166,
                48.83426011757068
            ]
        }
    ]
}

事务使用情况

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

其他信息

Azure Maps 获取反向地理编码批处理 API：用于在单个请求中将批量查询发送到 Azure Maps 获取反向地理编码 API。

支持

Microsoft Q&A 论坛

通过