如要計算路線,您至少必須指定路線起點和路線目的地的位置。您將這些位置定義為路線上的「路線控點」。
除了起點和目的地之外,您還可以指定不同類型的路線控點,以及處理路線的路線控點。如需詳細資訊和範例,請參閱下列主題:
指定路線的位置
您可以建立 Waypoint (REST) 或 Waypoint (gRPC) 物件來表示位置。在路線點定義中,您可以透過下列任一方式指定位置:
您可以在要求中以相同的方式指定所有路線控點的位置,也可以混合這些路線控點。舉例來說,您可以使用起點/經度座標的起點路線,並為目的地路線控點使用地點 ID。
為提升效率和精確度,請使用地點 ID,不要使用經緯度座標或地址字串。地點 ID 具有唯一性,而且在轉送上 (例如存取點和流量變數) 具備地理編碼的好處。這些做法有助於避免透過其他指定位置的方式發生以下情況:
- 使用經緯度座標可能會導致地點對齊到最接近這些座標的道路 (這可能不是該屬性的存取點),甚至是可快速或安全導向目的地的道路。
- 地址字串必須先由 Routes API 進行地理編碼,才能將其轉換為經緯度座標,以便計算路線。這項轉換可能會影響成效。
指定特定地點做為地點 ID
您可以使用地點 ID 來指定路線點的位置。由於經緯度座標會對齊道路,因此在某些情況下,地點 ID 可能會提供較好的結果。
從 Geocoding API 和 Places API (包括 Place Autocomplete) 擷取地點 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", ... } ] }
將某個地點指定為 Plus Code
許多人沒有精確的地址,因此很難收到包裹。或者,知道地址的使用者可能偏好在更明確的地點接受貨品,例如後門或載入中的座架。
Plus Code 就像沒有實際地址的人物或地點的街道地址,Plus Codes 是以經緯度座標為依據,會以數字和字母的形式顯示,而非包含街道名稱和號碼的地址。
Google 開發了 Plus Codes,目的是讓所有人都能透過地址使用地址。Plus Code 是經過編碼的位置參照,衍生自經緯度座標,代表某區域:取得 1/8000 度的 1/8000 度 (在赤道上約 14 公尺 x 14 公尺) 或更小的範圍。對於沒有詳細地址或無編號建築物或無名街道的地點,您可以使用 Plus Codes 取代街道地址。
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 Codes 指定路線
origin
和destination
的路線點,藉此計算路線:{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
Google 地圖平台 API 支援 Plus Code,包括 Place Autocomplete、Place Details、Directions API 和 Geocoding API。舉例來說,您可以使用 Geocoding API 對經緯度座標指定的位置反向地理編碼,藉此判斷地點的 Plus Code。