通过

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

迁移必应地图地理编码数据流 API

本文介绍如何将必应地图地理编码数据流 API 迁移到 Azure Maps 地理编码批处理和反向地理编码批处理 API。 Azure Maps 地理编码批处理 API 用于通过单个 API 调用在批处理模式下获取街道地址或地点名称的纬度和经度坐标。 Azure Maps 地理编码批处理 API 是一个 HTTP POST 请求，用于在单个请求中向 Azure Maps 地理编码 API 发送批量查询。 Azure Maps 反向地理编码批处理 API 用于将纬度和经度坐标转换为人类可理解的街道地址。 Azure Maps 反向地理编码批处理 API 是一个 HTTP POST 请求，用于在单个请求中将批量查询发送到 Azure Maps 获取反向地理编码 API。

先决条件

显著差异

  • 必应地图地理编码数据流 API 支持在同一 API 中正向和反向批处理地理编码。 Azure Maps 具有用于正向和反向地理编码的单独 API。
  • 必应地图地理编码数据流 API 要求将位置数据作为 XML 或文本（csv、管道或制表符分隔）数据文件上传。 Azure Maps 地理编码批处理和反向地理编码批处理 API 不使用数据文件上传方法，而是使用 HTTP POST 请求，请求正文中包含 GeoJSON 格式的位置数据。
  • 必应地图地理编码数据流 API 支持每次最多上传 200,000 个实体。 Azure Maps 地理编码批处理和反向地理编码批处理 API 在同步请求中最多支持 100 个批量查询，在异步请求中最多支持 200,000 个查询。
  • 必应地图地理编码数据流 API 需要在初始数据上传后进行一系列 API 调用来获取状态和下载结果。 Azure Maps 地理编码批处理和反向地理编码批处理 API 同步请求不需要额外的 API 调用。 异步请求确实需要其他调用来获取批处理状态和下载结果。
  • 必应地图地理编码数据流坐标采用纬度/经度格式。 Azure Maps 地理编码批处理和反向地理编码批处理 API 坐标采用经度/纬度格式（由于采用 GeoJSON 格式）。
  • 与必应地图企业版不同，Azure Maps 是一项支持指定地理范围的全局服务，可用于将数据驻留限制为欧洲 (EU) 或美国 (US) 地理区域（地区）。 所有请求（包括输入数据）都专门在指定的地理区域进行处理。 有关详细信息，请参阅 Azure Maps 服务地理范围。

安全性和身份验证

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

请求参数

下表列出了必应地图地理代码工作流请求参数和 Azure Maps 等效参数：

必应地图参数 Azure Maps 参数 说明
dataLocation 无需
input 无需 必应地图地理编码数据流 API 支持批处理地理编码输入数据文件的 XML 和文本（csv、选项卡和管道分隔）格式。 Azure Maps 支持 HTTP POST 请求中批处理地理编码输入数据的 JSON 格式。
output 无需 必应地图地理编码数据流 API 支持批处理地理编码输出数据的 JSON 和 XML。 Azure Maps 支持批处理地理编码输出数据的 JSON 格式。

有关 Azure Maps URI 参数和请求正文的详细信息，请参阅 Azure Maps 地理编码批处理和反向地理编码批处理文档。

必应地图数据架构 2.0 输入和输出与 Azure Maps 地理编码批处理和反向地理编码批处理 API 的比较：

必应地图字段 必应地图操作 Azure Maps 字段 Azure Maps 数据类型 说明
Address.AddressLine 地理编码请求
地理编码响应 		addressLine 字符串
Address.AdminDistrict 地理编码请求
地理编码响应 		adminDistrict string
Address.CountryRegion 地理编码请求
地理编码响应 		countryRegion string
Address.District 地理编码请求 adminDistrict2 string
Address.FormattedAddress 地理编码响应
Address.Landmark 地理编码响应 不支持 不支持
Address.Locality 地理编码请求
地理编码响应 		产地 字符串
Address.Neighborhood 地理编码响应 neighborhood 字符串
Address.PostalCode 地理编码请求
地理编码响应 		postalCode 字符串
Address.PostalTown 地理编码请求 adminDistrict3
BoundingBox.SouthLatitude、BoundingBox.EastLongitude、BoundingBox.NorthLatitude、BoundingBox.EastLongitude 地理编码响应 bbox number[] 使用的 Azure Maps 投影是 EPSG:3857。 有关详细信息，请参阅 RFC 7946。
置信度 地理编码响应 confidence ConfidenceEnum 有关详细信息，请参阅 Azure Maps 地理编码批处理和反向地理编码批处理 API 文档。 
ConfidenceFilter.MinimumConfidence 地理编码请求
反向地理编码请求		 不支持 不支持
环境 地理编码请求
反向地理编码请求		 请求头：Accept-Language 字符串 有关详细信息，请参阅 Azure Maps 支持的语言。
EntityType 地理编码响应 type 字符串 有关详细信息，请参阅 Azure Maps 地理编码批处理和反向地理编码批处理 API 文档。 
FaultReason 地理编码响应 不支持 不支持
GeocodeEntity XML 容器 无需 无需
GeocodeFeed XML 容器 无需 无需
GeocodePoint 地理编码响应 geocodePoints GeocodePoints[] 有关详细信息，请参阅 Azure Maps 地理编码批处理和反向地理编码批处理 API 文档。 
GeocodeRequest XML 容器 无需 无需 Azure Maps 具有用于正向地理编码和反向地理编码的单独 API。
ID 地理编码请求 无需 无需
IncludeEntityTypes 地理编码请求
反向地理编码请求 		不支持 不支持
IncludeNeighborhood 地理编码请求
反向地理编码请求 		无需 无需 在 Azure Maps 中，默认情况下，近邻信息会在响应中返回（如果可用）。 
IncludeQueryParse 地理编码请求 不支持 不支持
Location.Latitude
Location.Longitude 		反向地理编码请求 坐标 number[] 如果使用 Azure Maps 反向地理编码批处理 API 执行反向地理编码，则需要将其作为输入。
MatchCodes 地理编码响应 matchCodes MatchCodesEnum 有关详细信息，请参阅 Azure Maps 地理编码批处理和反向地理编码批处理 API 文档。 
MaxResults 地理编码请求
反向地理编码请求 		top integer
int32 		在 Azure Maps 中，返回的最大响应数。 默认值为 5，最小值为 1，最大值为 20。 
名称 地理编码响应 不支持 不支持
Point.Latitude、Point.Longitude 地理编码响应 坐标 number[] 必应地图以纬度/经度格式返回坐标。 Azure Maps 以经度/纬度格式返回坐标（由于采用 GeoJSON 格式）。
查询 地理编码请求 query 字符串
QueryParseValue 地理编码响应 不支持 不支持
ReverseGeocodeRequest XML 容器 无需 无需 Azure Maps 具有用于正向地理编码和反向地理编码的单独 API。
StatusCode 地理编码响应 不支持 不支持
StrictMatch 地理编码请求 不支持 不支持
TraceId 地理编码响应 不支持 不支持
版本 无需 无需

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

请求示例

必应地图地理编码数据流 API 请求：

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}

有关显示地理编码数据流 2.0 版样例输入和输出数据的示例，请参阅地理编码数据流示例输入和输出数据版本 2.0。

Azure Maps 地理编码批处理 API 请求：

POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

若要发送地理编码查询，请使用 HTTP POST 请求，其中请求正文包含 JSON 格式的 batchItems 数组，并将 Content-Type标头设置为 application/json。

以下 JSON 显示了包含两个地理编码查询的示例请求，其中一个位置采用非结构化格式，一个位置采用结构化格式：

{ 
  "batchItems": [ 
    { 
      "addressLine": "One, Microsoft Way, Redmond, WA 98052", 
      "top": 2 
    }, 
    { 
      "addressLine": "Pike Pl", 
      "adminDistrict": "WA", 
      "locality": "Seattle", 
      "top": 3 
    } 
  ] 
}

Azure Maps 反向地理编码批处理 API 请求：

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

若要发送反向地理编码查询，请使用 HTTP POST 请求，其中请求正文包含 JSON 格式的 batchItems 数组，并将 Content-Type标头设置为 application/json。

以下 JSON 显示了包含两个反向地理编码查询的示例请求：

{ 
  "batchItems": [ 
    { 
      "coordinates": [ 
        -122.128275, 
        47.639429 
      ], 
      "resultTypes": [ 
        "Address", 
        "PopulatedPlace" 
      ], 
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B" 
    }, 
    { 
      "coordinates": [ 
        -122.341979399674, 
        47.6095253501216 
      ], 
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7" 
    } 
  ] 
}

响应示例

当必应地图地理编码数据流批处理作业成功完成时，将提供下载地理编码作业结果的 URL，如“已完成”作业状态所示。 有关必应地图地理编码数据流输出成功的示例，请参阅必应地图文档中的地理编码数据流示例输入和输出数据 2.0 版。

以下示例显示了执行 Azure Maps 地理编码批处理 API 请求时 HTTP 响应正文中返回的内容：

{ 
  "summary": { 
    "successfulRequests": 1, 
    "totalRequests": 2 
  }, 
  "batchItems": [ 
    {
      "type": "FeatureCollection", 
      "features": [ 
        { 
          "type": "Feature", 
          "properties": { 
            "type": "Address", 
            "confidence": "High", 
            "matchCodes": [ 
              "Good" 
            ], 
            "address": { 
              "locality": "Redmond", 
              "adminDistricts": [ 
                { 
                  "shortName": "WA" 
                }, 
                { 
                  "shortName": "King" 
                } 
              ], 
              "countryRegion": { 
                "ISO": "US", 
                "name": "United States" 
              }, 
              "postalCode": "98052", 
              "formattedAddress": "1 Microsoft Way, Redmond, WA 98052", 
              "addressLine": "1 Microsoft Way" 
            }, 
            "geocodePoints": [ 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.128275, 
                    47.639429 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Display", 
                  "Route" 
                ] 
              }, 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.127028, 
                    47.638545 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Route" 
                ] 
              } 
            ] 
          }, 
          "geometry": { 
            "type": "Point", 
            "coordinates": [ 
              -122.128275, 
              47.639429 
            ] 
          }, 
          "bbox": [ 
            -122.1359181505759, 
            47.63556628242932, 
            -122.1206318494241, 
            47.643291717570676 
          ] 
        } 
      ]
    },
    {
      "error": {
        "code": "Conflicting Parameters",
        "message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
      }
    }
  ]
}

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

{ 
    "batchItems": [ 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.1294081, 
                            47.6391325 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.1294081, 
                                        47.6391325 
                                    ] 
                                }, 
                                "calculationMethod": "Rooftop", 
                                "usageTypes": [ 
                                    "Display" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "15770 NE 31st St", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA" 
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "locality": "Redmond", 
                            "neighborhood": "Overlake", 
                            "postalCode": "98052", 
                            "formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States" 
                        }, 
                        "confidence": "High", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.13705120720665, 
                        47.635269782429326, 
                        -122.12176499279336, 
                        47.64299521757068 
                    ] 
                } 
            ] 
        }, 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.341979399674, 
                            47.6095253501216 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.341979399674, 
                                        47.6095253501216 
                                    ] 
                                }, 
                                "calculationMethod": "Interpolation", 
                                "usageTypes": [ 
                                    "Display", 
                                    "Route" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "1736 Pike Pl", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA"
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "intersection": { 
                                "baseStreet": "Pike Pl", 
                                "displayName": "Pike Pl and Stewart St", 
                                "intersectionType": "Near", 
                                "secondaryStreet1": "Stewart St", 
                                "secondaryStreet2": null 
                            }, 
                            "locality": "Seattle", 
                            "neighborhood": "Downtown Seattle", 
                            "postalCode": "98101", 
                            "formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States" 
                        }, 
                        "confidence": "Medium", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.34961817972945, 
                        47.605662632550924, 
                        -122.33434061961856, 
                        47.61338806769228 
                    ] 
                } 
            ] 
        } 
    ], 
    "summary": { 
        "successfulRequests": 2, 
        "totalRequests": 2 
    } 
}

事务使用情况

与必应地图地理编码数据流 API 类似，Azure Maps 地理编码批处理和反向地理编码批处理 API 记录每个地理编码项的一个计费事务。 例如，在批处理请求中对 100 个位置进行地理编码会导致 100 个计费事务。 有关 Azure Maps 事务的详细信息，请参阅了解 Azure Maps 事务。

其他信息

更多 Azure Maps 地理编码 API

支持

  • Last updated on