如需计算路线,您必须至少指定路线起点和路线终点的位置。您可以将这些位置定义为路线上的航点。
除了起点和终点之外,您还可以指定不同类型的航点以及如何处理路线的航点。如需了解详情和查看示例,请参阅以下主题:
为路线指定位置
您可以通过创建航点 (REST) 或航点 (gRPC) 对象来表示一个地点。在航点定义中,您可以通过以下任一方式指定位置:
您可以在请求中以相同的方式指定所有航点的位置,也可以混合使用。例如,您可以为起点航点使用纬度/经度坐标,为终点航点使用地点 ID。
为了提高效率和准确性,请使用地点 ID,而不是经纬度坐标或地址字符串。地点 ID 具有唯一性,可为路线规划提供地理编码优势,例如接入点和交通变量。它们有助于避免因通过其他方式指定位置而可能导致的以下情况:
- 使用纬度/经度坐标可能会导致位置被吸附到距离这些坐标最近的道路上,而该道路可能不是房源的入口,甚至可能不是能够快速或安全到达目的地的道路。
- 地址字符串必须先由 Routes API 进行地理编码,将其转换为纬度/经度坐标,然后才能计算路线。 此转化可能会影响效果。
将位置指定为地点 ID
您可以使用地点 ID 指定航点的位置。由于经纬度坐标会贴靠到道路,因此在某些情况下,您可能会发现地点 ID 提供的结果更准确。
从 Geocoding API 和新版 Places API(包括新版自动补全)中检索地点 ID。如需详细了解地点 ID,请参阅地点 ID 概览。
以下示例使用 placeId 属性为 origin 和 destination 传递地点 ID:
{ "origin":{ "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o" }, "destination":{ "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU" }, ... }
以经纬度坐标的形式指定位置
如需在航点中定义位置,请使用纬度/经度坐标指定位置 (REST) 或位置 (gRPC)。
例如,使用 latitude 和 longitude 坐标为路线 origin 和 destination 指定航点:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, ... }
将位置指定为地址字符串
地址字符串是由字符串表示的字面量地址(例如“1600 Amphitheatre Parkway, Mountain View, CA”)。地理编码是将地址字符串转换为纬度和经度坐标(例如纬度 37.423021 和经度 -122.083739)的过程。
当您将地址字符串作为航点的位置传递时,Routes API 会在内部对该字符串进行地理编码,将其转换为纬度和经度坐标。
例如,如需计算路线,您可以使用地址字符串为路线 origin 和 destination 指定航点:
{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "450 Serra Mall, Stanford, CA 94305, USA" }, ... }
在此示例中,Routes API 会对这两个地址进行地理编码,将其转换为经纬度坐标。
如果地址值不明确,Routes API 可能会调用搜索功能,以消除与类似地址的歧义。例如,“1st Street”可能是完整值,也可能是“1st street NE”或“1st St SE”的部分值。此结果可能与 Geocoding API 返回的结果不同。您可以使用地点 ID 来避免可能的误解。
设置地址的区域
如果您将不完整的地址字符串作为航点的位置传递,API 可能会使用错误的地理编码纬度/经度坐标。例如,您发出一个请求,指定“Toledo”作为出发地,“Madrid”作为目的地,并指定驾车路线:
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE" }
在此示例中,“Toledo”被解读为美国俄亥俄州的一个城市,而不是西班牙的一个城市。因此,请求会返回一个空数组,表示不存在任何路由:
{ [] }
您可以通过添加 regionCode 参数,将 API 配置为返回偏向特定地区的结果。此参数以 ccTLD(“顶级域名”)双字符值的形式指定地区代码。多数 ccTLD 代码都与 ISO 3166-1 代码相同,但也有一些需要注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(代表“大不列颠及北爱尔兰联合王国”)。
包含 regionCode 参数的“Toledo”到“Madrid”路线请求会返回适当的结果,因为“Toledo”会被解读为西班牙的一个城市:
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE", "regionCode": "es" }
现在,响应中包含从西班牙托莱多到西班牙马德里的路线:
{ "routes": [ { "distanceMeters": 75330, "duration": "4137s", ... } ] }
将位置指定为导航点令牌
导航点令牌是一个字符串,用于对位置和额外的路线上下文进行编码。导航点令牌可提供前往入口、装卸区或指定接送区附近特定出入点的精确路线。这在送餐或拼车等情况下非常有用,因为在这些情况下,上车点或下车点可能不明确。
您可以通过调用 Geocoding API 的 Destinations 方法来获取导航点令牌。
如需指定导航点令牌,请执行以下操作:
- 通过 Geocoding API 的
SearchDestinations方法获取navigationPointToken。如需了解详情,请参阅 Geocoding API 文档。 - 通过传入
navigationPointToken创建航点。
以下示例使用 navigation_point_token 属性为 origin 和 destination 传递导航点令牌:
{ "origin":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN" }, "destination":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION" }, ... }
将位置指定为 Plus Code
许多人没有精确的地址,这可能会导致他们难以接收快递。或者,有地址的用户可能更愿意在更具体的位置(例如后门或装卸区)接收递送。
Plus Code 就像是街道地址,适用于没有实际地址的人员或地点。Plus Code 基于纬度/经度坐标,以数字和字母的形式显示,而不是使用包含街道名称和门牌号的地址。
Google 开发了 Plus Codes,旨在让每个人和每个地点都能拥有地址。Plus Code 是经过编码的位置引用,衍生自纬度/经度坐标,表示面积不超过 1/8, 000 度 x 1/8, 000 度(在赤道处约为 14 米 x 14 米)的区域。在没有街道地址、建筑物未编号或街道未命名的地点,您可以使用 Plus Code 代替街道地址。
Plus Code 的格式必须为全局代码或混合代码:
- 全局代码由包含 4 个字符的区号和至少包含 6 个字符的区域代码组成。
例如,对于地址“1600 Amphitheatre Parkway, Mountain View, CA”,全球代码为“849V”,本地代码为“CWC8+R9”。然后,您可以使用完整的 10 字符 Plus Code 将位置值指定为“849VCWC8+R9”。
- 混合代码由至少包含 6 个字符的区域代码和明确的位置信息组成。
例如,地址“450 Serra Mall, Stanford, CA 94305, USA”的本地代码为“CRHJ+C3”。对于复合地址,请将本地代码与地址中的城市、州、邮政编码和国家/地区部分组合在一起,格式为“CRHJ+C3 Stanford, CA 94305, USA”。
例如,通过使用 Plus Code 为路线
origin和destination指定航点来计算路线:{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
Google Maps Platform API 支持 Plus Code,包括自动补全(新版)、地点详情(新版)和 Geocoding API。 例如,您可以使用 Geocoding API 对由纬度/经度坐标指定的位置进行反向地理编码,以确定该位置的 Plus Code。