取得路線

路線是指從起點到終點的可導航路徑。你可以選擇取得不同交通方式的路線，例如步行、騎單車或不同類型的車輛。您也可以要求路線詳細資料，例如距離、預估導航時間、預期通行費，以及路線的逐步導航指示。

呼叫 computeRoutes() 方法，要求取得兩個地點之間的路線。以下範例說明如何定義要求，然後呼叫 computeRoutes() 取得路線。

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);

選擇要傳回的欄位

要求路線時，您必須使用欄位遮罩指定回應應傳回的資訊。您可以在欄位遮罩中指定路線類別屬性的名稱。

使用欄位遮罩也能確保您不會要求不必要的資料，進而縮短回應延遲時間，並避免傳回系統不需要的資訊。

設定 ComputeRoutesRequest.fields 屬性，指定所需欄位清單，如下方程式碼片段所示：

// Define a routes request.
const request = {
  origin: 'Mountain View, CA',
  destination: 'San Francisco, CA',
  fields: ['path'], // Request fields needed to draw polylines.
};

指定路線的地點

如要計算路線，您至少必須指定路線起點和路線目的地的位置，以及欄位遮罩。您也可以在路線中指定中途路線控點，並使用路線控點執行其他動作，例如在路線中新增停靠點或直通點。

在 ComputeRoutesRequest 中，可以透過下列任一方式指定位置：

您可以為要求中的所有中途點指定相同位置，也可以混用。 舉例來說，您可以為起點航點使用經緯度座標，並為目的地航點使用 Place 物件。

為提升效率和準確度，請使用 Place 物件，而非經緯度座標或地址字串。地點 ID 具有明確的唯一性，可提供地理編碼優勢，用於規劃路線，例如存取點和交通變數。這有助於避免因其他指定位置的方式而導致下列情況：

  • 使用經緯度座標可能會導致系統將位置資訊對應到最接近這些座標的道路，但這可能不是房源的入口，甚至不是能快速或安全抵達目的地的道路。
  • 地址字串必須先由 Routes API 進行地理編碼，轉換為經緯度座標，才能計算路徑。這項轉換可能會影響成效。

將地點指定為 Place 物件 (建議)

如要使用地點指定位置，請建立新的 Place 執行個體。下列程式碼片段顯示如何為 origin 和 destination 建立新的 Place 執行個體，然後在 ComputeRoutesRequest 中使用這些執行個體：

// Create a new Place for the origin.
const originPlace = new Place({
  id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

// Create a new Place for the destination.
const destinationPlace = new Place({
  id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

// Define a computeRoutes request.
const request = {
  origin: originPlace,
  destination: destinationPlace,
  fields: ['path'],
};

經緯度座標

如要將位置指定為經緯度座標，請建立新的 google.maps.LatLngLiteral、google.maps.LatLngAltitude 或 google.maps.LatLngAltitudeLiteral 例項。下列程式碼片段顯示如何為 origin 和 destination 建立新的 google.maps.LatLngLiteral 例項，然後在 computeRoutesRequest 中使用這些例項：

// Create new LatLngLiteral objects for the origin and destination.
// Mountain View, CA
const originLatLng = {lat: 37.422000, lng: -122.084058};
// San Francisco, CA
const destinationLatLng = {lat: 37.774929, lng: -122.419415};

// Define a computeRoutes request.
const request = {
  origin: originLatLng,
  destination: destinationLatLng,
  fields: ['path'],
};

地址字串

地址字串是字串表示的實際地址 (例如「1600 Amphitheatre Parkway, Mountain View, CA」)。地理編碼是指將地址字串轉換為經緯度座標 (例如緯度 37.423021 和經度 -122.083739)。

當您將地址字串做為路徑點的位置傳遞時，Routes 程式庫會在內部對字串進行地理編碼，將其轉換為經緯度座標。

下列程式碼片段顯示如何為 origin 和 destination 建立具有位址字串的 ComputeRoutesRequest：

// Define a computeRoutes request.
const request = {
  origin: '1600 Amphitheatre Parkway, Mountain View, CA',
  destination: '345 Spear Street, San Francisco, CA',
  fields: ['path'],
};

設定地址的區域

如果您傳遞不完整的地址字串做為中途點位置，API 可能會使用錯誤的地理編碼經緯度座標。舉例來說，您提出要求，將「Toledo」指定為行車路線的起點，並將「Madrid」指定為目的地： 

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};

在這個範例中，「Toledo」會解讀為美國俄亥俄州的城市，而非西班牙的城市。因此，要求會傳回空陣列，表示沒有任何路徑。

您可以加入 regionCode 參數，設定 API 優先傳回特定區域的結果。這個參數會指定區碼，採用 ccTLD (「頂層網域」) 的兩位字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」這個實體)。

如果從「Toledo」到「Madrid」的路線要求包含 regionCode 參數，系統會將「Toledo」解讀為西班牙的城市，並傳回適當結果：

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};

Plus Code

許多人沒有精確的地址，因此難以收到郵件。或者，有地址的使用者可能偏好在更明確的地點收貨，例如後門或裝卸碼頭。

Plus Code 就像是街道地址，適用於沒有實際地址的人或地點。 Plus code 是以經緯度座標為依據，並以數字和字母顯示，而非街道名稱和號碼。

Google 開發了 Plus Codes，讓所有人都能享有地址的便利性。Plus Code 是經過編碼的位置參照，衍生自經緯度座標，表示面積不超過 1/8000 度 x 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 Code 指定路線起點和目的地的途經點，藉此計算路線：

const request = {
  origin: '849VCWC8+R9', // Mountain View, CA
  destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
  fields: ['path'],
};