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

教程:从 Google Maps 迁移 Web 服务

Azure Maps 和 Google Maps 都通过 REST Web 服务提供对空间 API 的访问。 这些平台的 API 接口执行类似的功能。 但是,每个接口使用不同的命名约定和响应对象。

本教程演示如何:

  • 正向/反向地理编码
  • 搜索兴趣点
  • 计算路线和方向
  • 检索地图图像
  • 计算距离矩阵
  • 获取时区详细信息

你还将了解:

  • 从 Google Maps Web 服务迁移时,使用哪种 Azure Maps REST 服务
  • 有关如何充分利用 Azure Maps 服务的提示
  • 对其他相关 Azure Maps 服务的见解

下表显示了功能与所列 Google Maps 服务 API 类似的 Azure Maps 服务 API。

Google Maps 服务 API Azure Maps 服务 API
方向 Route
距离矩阵 发布路线矩阵
地理编码 搜索
地点搜索 搜索
地点自动完成 搜索
对齐道路 请参阅计算路线和方向部分。
速度限制 请参阅对坐标进行反向地理编码部分。
静态地图 Render
时区 Timezone

以下服务 API 目前在 Azure Maps 中不可用:

  • 地理位置 - Azure Maps 确实提供名为地理位置的服务,但它只在位置信息中提供 IP 地址,当前并不支持手机信号塔或 Wifi 三角测量。
  • 位置详细信息和照片 - 电话号码和网站 URL 在 Azure Maps 搜索 API 中可用。
  • 地图 URL
  • 最近的道路 - 可以通过使用 Web SDK 实现,如沿实际道路基本逻辑示例所示,但目前未作为服务提供。
  • 静态街道视图

先决条件

如果没有 Azure 订阅,请在开始之前创建一个免费帐户

注意

有关 Azure Maps 中身份验证的详细信息,请参阅在 Azure Maps 中管理身份验证

地理编码地址

地理编码是将地址转换为坐标的过程。 例如,将“1 Microsoft way, Redmond, WA”转换为经度:-122.1298,纬度:47.64005。 然后,坐标可用于不同的目的,例如,在地图上定位并居中某个标记。

Azure Maps 提供多种方法用于对地址进行地理编码:

  • Get Search Address:自由格式的地址地理编码用于指定单个地址字符串(如 "1 Microsoft way, Redmond, WA")并立即处理请求。 如果需要快速对各个地址进行地理编码,我们建议使用此服务。
  • Get Search Address Structured:指定单个地址的各个部分(例如街道名称、城市、国家/地区和邮政编码),并立即处理请求。 如果需要快速对单个地址进行地理编码,并且数据已分析成各个地址组成部分,则我们建议使用此 API。
  • Post Search Address Batch:创建最多包含 10,000 个地址的请求,并在一段时间内对其进行处理。 所有地址会在服务器上并行进行地理编码,完成后,可以下载完整的结果集。 若要对大型数据集进行地理编码,建议使用此方法。
  • Get Search Fuzzy:模糊搜索 API 将地址地理编码与兴趣点搜索相结合。 此 API 采用自由格式的字符串(可以是地址、地点、地标、兴趣点或兴趣点类别),并立即处理请求。 对于其用户可以从同一文本框搜索地址或兴趣点的应用程序,建议使用此 API。
  • Post Search Fuzzy Batch:使用模糊批量搜索创建包含最多 10,000 个地址、地点、地标或兴趣点的请求,并在一段时间内对其进行处理。 所有数据会在服务器上并行进行处理,完成后,可以下载完整的结果集。

下表对 Google Maps API 参数与 Azure Maps 中的类似 API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
address query
bounds topLeftbtmRight
components streetNumber
streetName
crossStreet
postalCode
municipality - 城市/城镇
municipalitySubdivision – 周边区域,城市副中心/超级城市
countrySubdivision - 州或省/自治区/直辖市
countrySecondarySubdivision - 县
countryTertiarySubdivision - 区
countryCode - 双字母国家/地区代码
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
region countrySet

有关使用搜索服务的详细信息,请参阅使用 Azure Maps 搜索服务搜索位置。 请务必查看搜索最佳做法

提示

可以通过将 &typeahead=true 添加到请求 URL,在自动完成模式下使用自由格式的地址地理编码和模糊搜索 API。 这可以让服务器知道输入文本可能是不完整的,搜索将进入预测模式。

对坐标进行反向地理编码

反向地理编码是将地理坐标转换为大致地址的过程。 例如,将坐标“经度:-122.1298,纬度:47.64005”转换为“1 Microsoft way, Redmond, WA”。

Azure Maps 提供多种反向地理编码方法:

  • Get Search Address Reverse:指定单个地理坐标,以获取对应于此坐标的大致地址。 以近实时的速度处理请求。
  • Get Search Address Reverse Cross Street:指定单个地理坐标,以获取附近的十字街信息,并立即处理请求。 例如,你可能会获得以下十字街位置:第一大道和主街。
  • Post Search Address Reverse Batch:创建最多包含 10,000 个坐标的请求,并在一段时间内对其进行处理。 所有数据将在服务器上并行进行处理。 请求完成后,可以下载整个结果集。

下表对 Google Maps API 参数与 Azure Maps 中的类似 API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
latlng query
location_type 空值
result_type entityType

有关详细信息,请参阅搜索最佳做法

Azure Maps 反向地理编码 API 提供 Google Maps 所不能提供的其他一些功能。 在迁移应用时,这些功能可能对集成应用程序有帮助:

  • 检索限速数据
  • 检索道路使用信息:地方道路、干道、限制进入、匝道等
  • 检索坐标所在的街道一侧

搜索兴趣点

在 Google Maps 中可以使用地点搜索 API 搜索兴趣点数据。 此 API 提供三种不同的方式来搜索兴趣点:

  • 从文本中查找地点: 基于兴趣点的名称、地址或电话号码搜索该兴趣点。
  • 附近搜索: 搜索位于某个位置特定距离内的兴趣点。
  • 文本搜索: 使用包含兴趣点和位置信息的自由格式文本来搜索地点。 例如,“纽约的披萨店”或“主街附近的餐厅”。

Azure Maps 提供多个搜索 API 用于搜索兴趣点:

  • Get Search POI:按名称搜索兴趣点。 例如“星巴克”。
  • Get Search POI Category:按类别搜索兴趣点。 例如“餐厅”。
  • Get Search Nearby:搜索位于某个位置特定距离内的兴趣点。
  • Get Search Fuzzy:模糊搜索 API 将地址地理编码与兴趣点搜索相结合。 此 API 采用自由格式的字符串(可以是地址、地点、地标、兴趣点或兴趣点类别),并立即处理请求。 对于其用户可以从同一文本框搜索地址或兴趣点的应用程序,建议使用此 API。
  • Post Search Inside Geometry:搜索指定几何图形中的兴趣点。 例如,在多边形中搜索兴趣点。
  • Post Search Along Route:搜索指定路线上的兴趣点。
  • Post Search Fuzzy Batch:使用模糊批量搜索创建包含最多 10,000 个地址、地点、地标或兴趣点的请求,并在一段时间内对其进行处理。 所有数据会在服务器上并行进行处理,完成后,可以下载完整的结果集。

目前,Azure Maps 没有与 Google Maps 中的文本搜索 API 类似的 API。

提示

可以通过将 &typeahead=true 添加到请求 URL,在自动完成模式下使用 POI 搜索、POI 类别搜索和模糊搜索 API。 这可以让服务器知道输入文本可能是不完整的。API 将在预测模式下执行搜索。

有关详细信息,请参阅搜索最佳做法

从文本中查找地点

使用 Azure Maps Get Search POIGet Search Fuzzy,可按名称或地址搜索兴趣点。

下表对 Google Maps API 参数与类似的 Azure Maps API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
fields 空值
input query
inputtype 空值
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
locationbias latlonradius
topLeftbtmRight
countrySet

在 Azure Maps 中,使用 Get Search Nearby API 来检索附近的兴趣点。

下表显示了 Google Maps API 参数与类似的 Azure Maps API 参数。

Google Maps API 参数 类似的 Azure Maps API 参数
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
keyword categorySetbrandSet
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
location latlon
maxprice 空值
minprice 空值
name categorySetbrandSet
opennow 空值
pagetoken ofslimit
radius radius
rankby 空值
type categorySet – 有关详细信息,请参阅支持的搜索类别

计算路线和方向

使用 Azure Maps 计算路线和方向。 Azure Maps 具有许多与 Google Maps 路线服务相同的功能,例如:

  • 抵达和出发时间。
  • 实时和基于预测的交通路线。
  • 不同的交通方式。 例如开车、步行、骑行。

注意

Azure Maps 要求以坐标提供中途点。 必须先对地址进行地理编码。

Azure Maps 路线服务提供以下 API 来计算路线:

  • Get Route Directions:计算路线并立即处理请求。 此 API 同时支持 GETPOST 请求。 指定大量途经点或使用大量路线选项时,建议使用 POST 请求,以确保 URL 请求不会太长并导致出现问题。 Azure Maps 中的“POST 路线方向”提供了一个选项,可以接受数千个支持点,并使用这些支持点在它们之间重新创建一个逻辑路线路径(贴靠到道路)。
  • Post Route Directions Batch:创建最多包含 1,000 个路线请求的请求,并在一段时间内对其进行处理。 所有数据会在服务器上并行进行处理,完成后,可以下载完整的结果集。

下表对 Google Maps API 参数与 Azure Maps 中的类似 API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
alternatives maxAlternatives
arrival_time arriveAt
avoid avoid
departure_time departAt
destination query – 采用 "lat0,lon0:lat1,lon1…." 格式的坐标
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
mode travelMode
optimize computeBestOrder
origin query
region 不适用 – 此功能与地理编码相关。 使用 Azure Maps 地理编码 API 时,请使用 countrySet 参数。
traffic_model 不适用 – 仅当交通数据应与 traffic 参数结合使用时才能指定。
units 不适用 – Azure Maps 仅使用指标系统。
waypoints query

提示

默认情况下,Azure Maps 路线 API 仅返回摘要。 它返回距离和时间,以及路径的坐标。 使用 instructionsType 参数可检索转弯提示说明。 使用 routeRepresentation 参数筛选出摘要和路径。

Azure Maps 路线 API 提供 Google Maps 所不能提供的其他功能。 在迁移应用时,请考虑使用以下功能:

  • 路线类型支持:最短、最快、trilling 和最省油。
  • 支持其他交通方式:公共汽车、摩托车、出租车、货车和面包车。
  • 支持 150 个中途点。
  • 计算单个请求中的多个旅行时间;历史交通状况、实时交通状况、无交通状况。
  • 避开其他道路类型:共乘车道、土路、已占用的道路。
  • 指定要避开的自定义区域。
  • 限制路线可能上升的高度。
  • 基于发动机规格规划路线。 根据发动机规格和剩余燃料或电量计算燃料汽车或电动车的路线。
  • 支持商务车路线参数。 例如车辆尺寸、重量、轴数和货物类型。
  • 指定最大车速。

此外,Azure Maps 中的路线服务还支持 Get Route Range。 可达范围也称为等时线。 这种计算会生成一个多边形,其中涵盖了在指定的时间内或根据剩余的燃料/电量, 从某个原点朝任意方向可以行进到的区域。

有关详细信息,请参阅路线规划的最佳做法

检索地图图像

Azure Maps 提供一个 API 用于呈现包含叠加数据的静态地图图像。 Azure Maps 中的 Get Map Static Image API 类似于 Google Maps 中的静态地图 API。

注意

Azure Maps 要求以“经度,纬度”格式的坐标提供中心点、所有标记和路径位置。 而 Google Maps 则使用“纬度,经度”格式。 首先需要对地址进行地理编码。

下表对 Google Maps API 参数与 Azure Maps 中的类似 API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
center center
format format – 指定为 URL 路径的一部分。 目前仅支持 PNG。
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
maptype layerstyle - 有关详细信息,请参阅受支持的地图样式
markers pins
path path
region 不适用 – 地理编码相关的功能。 使用 Azure Maps 地理编码 API 时,请使用 countrySet 参数。
scale 空值
size widthheight – 最大大小为 8192 x 8192。
style 空值
visible 空值
zoom zoom

注意

在 Azure Maps 图块系统中,图块大小是 Google Maps 中所用地图图块的两倍。 因此,相比 Google Maps,Azure Maps 中的缩放级别值看上去要更近一个级别。 若要补偿这种差异,请要迁移的请求中降低缩放级别。

有关详细信息,请参阅在光栅地图上呈现自定义数据

除了能够生成静态地图图像以外,Azure Maps 呈现服务还支持直接访问光栅 (PNG) 和矢量格式的地图图块:

提示

许多 Google Maps 应用程序在几年前已从交互式地图体验切换为静态地图图像。 这是一种成本节省的方法。 在 Azure Maps 中,使用 Web SDK 中的交互式地图控件可以提高性价比。 交互式地图控件是按照图块加载次数收费的。 Azure Maps 中的地图图块较大。 通常只需添加少量的图块即可重新创建与静态地图相同的地图视图。 浏览器会自动缓存地图图块。 因此,在再现静态地图视图时,交互式地图控件通常只生成一部分事务。 平移和缩放会加载更多图块,但是,可以使用地图控件中的选项来禁用此行为。 此外,交互式地图控件提供的可视化选项比静态地图服务要多得多。

标记 URL 参数格式比较

前者:Google Maps

可以通过在 URL 中使用 markers 参数来添加标记。 markers 参数采用某种样式以及要在地图上呈现的位置列表,其中,样式如下所示:

&markers=markerStyles|markerLocation1|markerLocation2|...

若要添其他样式,请在包含不同样式和位置集的 URL 中使用 markers 参数。

使用“纬度,经度”格式指定标记位置。

添加采用 optionName:value 格式的标记样式,多个样式以竖线 (|) 字符分隔,例如 “optionName1:value1|optionName2:value2”。 请注意,选项名称和值以冒号(:) 分隔。 使用以下样式选项名称来为 Google Maps 中的标记设置样式:

  • color – 默认标记图标的颜色。 可以是 24 位十六进制颜色 (0xrrggbb) 或以下值之一:blackbrowngreenpurpleyellowbluegrayorangeredwhite
  • label – 要在图标顶部显示的单个大写字母数字字符。
  • size - 标记的大小。 可以是 tinymidsmall

对 Google Maps 中的自定义图标使用以下样式选项名称:

  • anchor – 指定如何将图标图像与坐标对齐。 可以是像素 (x,y) 值或以下值之一:topbottomleftrightcentertoplefttoprightbottomleftbottomright
  • icon - 指向图标图像的 URL。

例如,让我们将中等大小的红色标记添加到地图中的经度:-110,纬度:45:

&markers=color:red|size:mid|45,-110

Google Maps 标记

后者:Azure Maps

通过在 URL 中指定 pins 参数,将标记添加到静态地图图像。 与 Google Maps 一样,可以在此参数中指定样式和位置列表。 可以指定 pins 参数多次,以支持采用不同样式的标记。

&pins=iconType|pinStyles||pinLocation1|pinLocation2|...

若要使用其他样式,请在包含不同样式和位置集的 URL 中添加其他 pins 参数。

在 Azure Maps 中,图钉位置需要采用“经度,纬度”格式。 Google Maps 使用“纬度,经度”格式。 使用空格而不是逗号来分隔 Azure Maps 格式中的经度和纬度。

iconType 指定要创建的图钉类型。 该选项可具有以下值:

  • default – 默认的图钉图标。
  • none - 不显示图标,只呈现标签。
  • custom – 指定要使用的自定义图标。 可将指向图标图像的 URL 添加到图钉位置信息后的 pins 参数的末尾。

添加采用 optionNameValue 格式的图钉样式。 使用竖线 (|) 字符分隔多个样式。 例如:iconType|optionName1Value1|optionName2Value2。 不用分隔选项名称和值。 使用以下样式选项名称来为标记设置样式:

  • al – 指定标记的不透明度 (alpha)。 选择 0 到 1 的数字。
  • an – 指定图钉定位点。 以“x y”格式指定 X 和 Y 轴值。
  • co – 图钉的颜色。 指定 24 位十六进制颜色:000000FFFFFF
  • la – 指定标签定位点。 以“x y”格式指定 X 和 Y 轴值。
  • lc – 标签的颜色。 指定 24 位十六进制颜色:000000FFFFFF
  • ls – 标签的大小(以像素为单位)。 选择大于 0 的数字。
  • ro – 图标的旋转度数值。 选择 -360 到 360 的数字。
  • sc – 图钉图标的比例值。 选择大于 0 的数字。

为每个图钉位置指定标签值。 此方法比向位置列表中的所有标记应用单个标签值更加高效。 标签值可以是包含多个字符的字符串。 将字符串括在单引号中,以确保不会错误地将它视为样式或位置值。

让我们添加一个具有标签“Space Needle”、定位在 (15 50) 下的红色 (FF0000) 默认图标。 该图标的位置为经度:-122.349300,纬度:47.620180:

&pins=default|coFF0000|la15 50||'Space Needle' -122.349300 47.620180

Azure Maps 标记

添加具有标签值“1”、“2”和“3”的三个图钉:

&pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12

Azure Maps 多个标记

路径 URL 参数格式比较

前者:Google Maps

通过在 URL 中使用 path 参数,将线条和多边形添加到静态地图图像。 path 参数采用某种样式以及要在地图上呈现的位置列表:

&path=pathStyles|pathLocation1|pathLocation2|...

通过将其他 path 参数添加到包含不同样式和位置集的 URL 来使用其他样式。

latitude1,longitude1|latitude2,longitude2|… 格式指定路径位置。 路径可以编码,或包含点的地址。

添加采用 optionName:value 格式的路径样式,使用竖线 (|) 字符分隔多个样式。 另请使用冒号 (:) 分隔选项名称和值。 例如:optionName1:value1|optionName2:value2。 可使用以下样式选项名称来为 Google Maps 中的路径设置样式:

  • color – 路径或多边形轮廓的颜色。 可以是 24 位十六进制颜色 (0xrrggbb)、32 位十六进制颜色 (0xrrggbbbaa) 或以下值之一:black、brown、green、purple、yellow、blue、gray、orange、red、white。
  • fillColor – 用于填充路径区域(多边形)的颜色。 可以是 24 位十六进制颜色 (0xrrggbb)、32 位十六进制颜色 (0xrrggbbbaa) 或以下值之一:black、brown、green、purple、yellow、blue、gray、orange、red、white。
  • geodesic – 指示路径是否应为遵循地球曲率的线条。
  • weight – 路径线条的粗细(以像素为单位)。

在 URL 参数中,将红色线条不透明度和像素粗细添加到地图上的坐标之间。 在以下示例中,线条不透明度为 50%,粗细为 4 像素。 坐标为经度:-110,纬度:45)和(经度:-100,纬度:50。

&path=color:0xFF000088|weight:4|45,-110|50,-100

Google Maps 折线

后者:Azure Maps

通过在 URL 中指定 path 参数,将线条和多边形添加到静态地图图像。 与 Google Maps 一样,可以在此参数中指定样式和位置列表。 指定 path 参数多次,以呈现采用不同样式的多个圆、线条和多边形。

&path=pathStyles||pathLocation1|pathLocation2|...

涉及到路径位置时,Azure Maps 要求坐标采用“经度,纬度”格式。 Google Maps 使用“纬度,经度”格式。 使用空格而不是逗号来分隔 Azure Maps 格式中的经度和纬度。 Azure Maps 不支持编码的路径或点地址。

添加采用 optionNameValue 格式的路径样式。 使用竖线 (|) 字符分隔多个样式,例如 optionName1Value1|optionName2Value2。 不用分隔选项名称和值。 使用以下样式选项名称来为 Azure Maps 中的路径设置样式:

  • fa - 呈现多边形时使用的填充颜色不透明度 (alpha)。 选择 0 到 1 的数字。
  • fc - 用于呈现多边形区域的填充颜色。
  • la – 在呈现多边形的线条和轮廓时使用的线条颜色不透明 (alpha)。 选择 0 到 1 的数字。
  • lc – 用于呈现多边形的线条和轮廓的线条颜色。
  • lw – 线条的宽度(以像素为单位)。
  • ra – 指定圆的半径(以米为单位)。

在 URL 参数中,将红色线条不透明度和像素粗细添加到坐标之间。 在以下示例中,线条不透明度为 50%,粗细为 4 像素。 坐标值如下:经度:-110,纬度:45)和(经度:-100,纬度:50。

&path=lcFF0000|la.5|lw4||-110 45|-100 50

Azure Maps 折线

计算距离矩阵

Azure Maps 提供距离矩阵 API。 使用此 API 可以计算一组位置之间的行程时间和距离以及距离矩阵。 它类似于 Google Maps 中的距离矩阵 API。

  • Post Route Matrix:以异步方式计算一组起点和终点的行程时间与距离。 每个请求最多支持 700 个单元。 该数字为出发地数乘以目的地数。 考虑到这一限制,可能的矩阵维度示例如下:700x1、50x10、10x10、28x25、10x70。

注意

只能使用在请求正文中包含来源和目标信息的 POST 请求向距离矩阵 API 发出请求。 此外,Azure Maps 要求以坐标形式指定所有来源和目标。 首先需要对地址进行地理编码。

下表对 Google Maps API 参数与类似的 Azure Maps API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
arrivial_time arriveAt
avoid avoid
depature_time departAt
destinations destination - 在 POST 请求正文中以 GeoJSON 形式指定。
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
mode travelMode
origins origins - 在 POST 请求正文中以 GeoJSON 形式指定。
region 不适用 – 此功能与地理编码相关。 使用 Azure Maps 地理编码 API 时,请使用 countrySet 参数。
traffic_model 不适用 – 仅当交通数据应与 traffic 参数结合使用时才能指定。
transit_mode 不适用 - 目前不支持基于交通方式的距离矩阵。
transit_routing_preference 不适用 - 目前不支持基于交通方式的距离矩阵。
units 不适用 – Azure Maps 仅使用指标系统。

提示

Azure Maps 路线 API 中提供的所有高级路线选项在 Azure Maps 距离矩阵 API 中均受支持。 高级路线选项包括:货车路线、发动机规格,等等。

有关详细信息,请参阅路线规划的最佳做法

获取时区

Azure Maps 提供一个 API 用于检索坐标所在的时区。 Azure Maps 时区 API 相当于 Google Maps 中的时区 API:

下表对 Google Maps API 参数与 Azure Maps 中的类似 API 参数做了交叉比较。

Google Maps API 参数 类似的 Azure Maps API 参数
key subscription-key - 有关详细信息,请参阅向 Azure Maps 进行身份验证
language language - 有关详细信息,请参阅 Azure Maps 中的本地化支持
location query
timestamp timeStamp

除此 API 以外,Azure Maps 还提供了许多时区 API。 这些 API 可根据时区的名称或 ID 转换时间:

客户端库

Azure Maps 为以下编程语言提供客户端库:

这些开源客户端库适用于其他编程语言:

清理资源

没有要清理的资源。

后续步骤

详细了解 Azure Maps REST 服务: