指定位置和路線選項

如要計算路徑或路徑矩陣，您必須至少指定路徑起點的位置和路線目的地的位置。請將每個位置定義為路線上的「路線控點」。

除了位置之外，您可以指定許多不同的選項來控制路徑。舉例來說，您可以指定避開收費路段，或是路線為步行或機車。

指定位置

如為 Routes API，您必須建立 Waypoint (REST) 或 Waypoint (gRPC) 物件，以代表位置。在路線定義中，請使用以下方式指定位置：

您可以為要求中的所有路線控點使用相同的位置表示法，或是兩者搭配使用。舉例來說，您可以使用路線控點的經緯度座標，並將目的地 ID 設為目的地路線控點。

比起使用經緯度座標或地址字串，建議您優先使用地點 ID：

  • 使用經緯度座標，可以將位置資訊放置在距離這些座標最接近的位置，因為這可能不是房源的存取點，甚至是能快速或安全到達目的地的路線。

  • 地址字串通常是使用者輸入地址的方式。不過，Routes API 必須先對地址字串進行地理編碼，才能將其轉換為緯度/經度座標，以便計算路線。此轉換可能會影響效能。

Plus Code 就像是實際地址的商家或街道地址，沒有實際地址。Plus Codes 會以經緯度的形式顯示，而不是以街道名稱和數字的地址，並以數字和英文字母的形式顯示。

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」可以是完整值或「1th 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"
}

這個回應現在包含從西班牙 Toledo、西班牙到馬德里的路線：

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

將位置指定為 Plus Code

許多使用者都不知道設定精確地址，因此可能較難收到包裹。或者，擁有地址的使用者比較喜歡在特定地點 (如後車廂或載入座架) 接受配送。

Google 開發了 Plus Codes，讓所有人都能輕鬆使用地址。Plus Code 是經過編碼的位置參照，根據緯度座標和經度座標衍生，為一個區域：1/8000th 度 1/8000 度 (攝氏 14 公尺 x 14 公尺) 或更小。對於沒有詳細地址的地點，或是沒有編號的街道，您可以使用 Plus Codes 來取代街道地址。

Plus Codes 必須採用全域代碼或複合代碼的格式：

  • 全域代碼是由 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 Codes，包括 Place Autocomplete、Place Details、Directions API 和 Geocoding API。舉例來說，您可以使用 Geocoding API 對經緯度座標指定的位置進行地理編碼，以便決定該位置的 Plus Code。

指定路徑選項

除了指定起點與目的地之外，您也可以指定許多選項來控管路徑。下表列出了這些選項：

選項 說明
交通方式

交通方式，例如開車、騎腳踏車、步行或機車。

請參閱「規劃雙輪車」和「RouteTravelMode」。
設定路徑品質與延遲 是否將路況納入考量。 請參閱「設定品質與延遲」。
路徑修飾符 指定選項來避開收費路段、避開高速公路及其他選項。請參閱設定路徑修飾符一節。
計算過路費 估算路線的任何通行費。 請參閱計算過路費。
設定環保路徑 根據能源引擎類型，計算環保路線。顯示最省油或最節能路線。 請參閱「設定環保路徑」。
要求替代路線 最多使用三個替代路線和預設路徑。請參閱「要求替代路徑」。
其他選項 指定其他選項，例如出發時間、傳回回應的語言代碼 (僅限 Compute 路徑)，以及回應中的測量單位 (僅限 Compute 路徑)。請參閱要求主體。