路線矩陣是路線資訊的二維陣列，其中資料列對應起點，資料欄對應目的地。只要提供起點和目的地清單，Route Matrix 類別就會計算從每個起點出發，抵達每個目的地的路線距離和時間。使用 Route Matrix 類別計算多個起點和目的地的路線距離和時間。
查看完整範例原始碼
這個範例說明如何使用 Route Matrix 類別，計算多個起點和目的地之間的距離和時間。
TypeScript
// Initialize and add the map. let map; let markers: google.maps.marker.AdvancedMarkerElement[] = []; let center = { lat: 51.55, lng: -1.8 }; async function initMap(): Promise<void> { // Request the needed libraries. //@ts-ignore const [{Map}, {Place}, {AdvancedMarkerElement, PinElement}, {RouteMatrix}] = await Promise.all([ google.maps.importLibrary('maps') as Promise<google.maps.MapsLibrary>, google.maps.importLibrary('places') as Promise<google.maps.PlacesLibrary>, google.maps.importLibrary('marker') as Promise<google.maps.MarkerLibrary>, google.maps.importLibrary('routes') as Promise<google.maps.RoutesLibrary> ]); const bounds = new google.maps.LatLngBounds(); map = new Map(document.getElementById('map') as HTMLElement, { zoom: 8, center: center, mapId: 'DEMO_MAP_ID', }); // Build the request using Place instances. const origin1 = new Place({ id: "ChIJ83WZp86p2EcRbMrkYqGncBQ", // Greenwich, London, UK }); const origin2 = new Place({ id: "ChIJCSkVvleJc0gR8HHaTGpajKc", // Southampton, UK }); const destinationA = new Place({ id: "ChIJYdizgWaDcUgRH9eaSy6y5I4", // Bristol, UK }); const destinationB = new Place({ id: "ChIJ9VPsNNQCbkgRDmeGZdsGNBQ", // Cardiff, UK }); await Promise.all([ origin1.fetchFields({ fields: ['location', 'displayName']}), origin2.fetchFields({ fields: ['location', 'displayName']}), destinationA.fetchFields({ fields: ['location', 'displayName']}), destinationB.fetchFields({ fields: ['location', 'displayName']}), ]); const request = { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', units: google.maps.UnitSystem.METRIC, fields: ['distanceMeters', 'durationMillis', 'condition'], }; // Show the request. (document.getElementById("request") as HTMLDivElement).innerText = JSON.stringify(request, null, 2); // Get the RouteMatrix response. const response = await RouteMatrix.computeRouteMatrix(request); // Show the response. (document.getElementById("response") as HTMLDivElement).innerText = JSON.stringify(response, null, 2); // Add markers for the origins. for (const origin of request.origins) { if (origin.location) { const pin = new PinElement({ //@ts-ignore glyphText: "O", glyphColor: "white", background: "#137333", borderColor: "white", }); const marker = new AdvancedMarkerElement({ map, position: origin.location, content: pin.element, title: `Origin: ${origin.displayName}`, }); markers.push(marker); bounds.extend(origin.location); } } // Add markers for the destinations. for (let i = 0; i < request.destinations.length; i++) { const destination = request.destinations[i]; if (destination.location) { const pin = new PinElement({ //@ts-ignore glyphText: "D", glyphColor: "white", background: "#C5221F", borderColor: "white", }); const marker = new AdvancedMarkerElement({ map, position: destination.location, content: pin.element, title: `Destination: ${destination.displayName}`, }); markers.push(marker); bounds.extend(destination.location); } } // Fit the map to the bounds of all markers. map.fitBounds(bounds); } initMap();
JavaScript
// Initialize and add the map. let map; let markers = []; let center = { lat: 51.55, lng: -1.8 }; async function initMap() { // Request the needed libraries. //@ts-ignore const [{ Map }, { Place }, { AdvancedMarkerElement, PinElement }, { RouteMatrix }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('places'), google.maps.importLibrary('marker'), google.maps.importLibrary('routes') ]); const bounds = new google.maps.LatLngBounds(); map = new Map(document.getElementById('map'), { zoom: 8, center: center, mapId: 'DEMO_MAP_ID', }); // Build the request using Place instances. const origin1 = new Place({ id: "ChIJ83WZp86p2EcRbMrkYqGncBQ", // Greenwich, London, UK }); const origin2 = new Place({ id: "ChIJCSkVvleJc0gR8HHaTGpajKc", // Southampton, UK }); const destinationA = new Place({ id: "ChIJYdizgWaDcUgRH9eaSy6y5I4", // Bristol, UK }); const destinationB = new Place({ id: "ChIJ9VPsNNQCbkgRDmeGZdsGNBQ", // Cardiff, UK }); await Promise.all([ origin1.fetchFields({ fields: ['location', 'displayName'] }), origin2.fetchFields({ fields: ['location', 'displayName'] }), destinationA.fetchFields({ fields: ['location', 'displayName'] }), destinationB.fetchFields({ fields: ['location', 'displayName'] }), ]); const request = { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', units: google.maps.UnitSystem.METRIC, fields: ['distanceMeters', 'durationMillis', 'condition'], }; // Show the request. document.getElementById("request").innerText = JSON.stringify(request, null, 2); // Get the RouteMatrix response. const response = await RouteMatrix.computeRouteMatrix(request); // Show the response. document.getElementById("response").innerText = JSON.stringify(response, null, 2); // Add markers for the origins. for (const origin of request.origins) { if (origin.location) { const pin = new PinElement({ //@ts-ignore glyphText: "O", glyphColor: "white", background: "#137333", borderColor: "white", }); const marker = new AdvancedMarkerElement({ map, position: origin.location, content: pin.element, title: `Origin: ${origin.displayName}`, }); markers.push(marker); bounds.extend(origin.location); } } // Add markers for the destinations. for (let i = 0; i < request.destinations.length; i++) { const destination = request.destinations[i]; if (destination.location) { const pin = new PinElement({ //@ts-ignore glyphText: "D", glyphColor: "white", background: "#C5221F", borderColor: "white", }); const marker = new AdvancedMarkerElement({ map, position: destination.location, content: pin.element, title: `Destination: ${destination.displayName}`, }); markers.push(marker); bounds.extend(destination.location); } } // Fit the map to the bounds of all markers. map.fitBounds(bounds); } initMap();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ /* Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } #container { height: 100%; display: flex; } #sidebar { flex-basis: 15rem; flex-grow: 1; padding: 1rem; max-width: 30rem; height: 100%; box-sizing: border-box; overflow: auto; } #map { flex-basis: 0; flex-grow: 4; height: 100%; } #sidebar { flex-direction: column; }
HTML
<html>
<head>
<title>Route matrix</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div id="container">
<div id="map"></div>
<div id="sidebar">
<h3 style="flex-grow: 0">Request</h3>
<pre style="flex-grow: 1" id="request"></pre>
<h3 style="flex-grow: 0">Response</h3>
<pre style="flex-grow: 1" id="response"></pre>
</div>
</div>
<!-- prettier-ignore -->
<script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "beta"});</script>
</body>
</html>試用範例
要求限制
computeRouteMatrix 方法會對使用地址或地點例項的航點，以及項目強制執行下列要求限制。項目是指路線矩陣中每個起點和目的地之間的路線，因此項目數量等於起點數量乘以目的地數量。舉例來說，如果您有 10 個出發地和 10 個目的地，就會有 100 個項目：
- 如果不是
TRANSIT路線，項目數量不得超過 625 個。 - 如果指定
TRANSIT路徑，項目數量不得超過 100 個。 - 如果您指定
TRAFFIC_AWARE_OPTIMAL，項目數量不得超過 100 個。 - 如果您使用地址或地點執行個體指定來源或目的地，最多可以指定 50 個。
詳情請參閱「取得大眾運輸路線」。
路線矩陣要求範例
以下範例顯示 ComputeRouteMatrixRequest。這個範例會執行下列操作：
- 顯示指定兩個起點和兩個目的地路線控點的陣列。這個方法會計算從每個起點到每個目的地的路線，因此回應會包含四條路線。
在陣列中，第一個元素的索引為 0，第二個元素的索引為 1，以此類推。 - 指定要傳回的欄位。在這個範例中，要求已設定為針對每條路線傳回
durationMillis、distanceMeters和condition。
TypeScript
const request = { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', units: google.maps.UnitSystem.METRIC, fields: ['distanceMeters', 'durationMillis', 'condition'], };
JavaScript
const request = { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', units: google.maps.UnitSystem.METRIC, fields: ['distanceMeters', 'durationMillis', 'condition'], };
回應包含所有起點和目的地中途點組合的四條可能路線，如下列範例所示：
"matrix": { "rows": [ { "items": [ { "condition": "ROUTE_EXISTS", "distanceMeters": 202587, "durationMillis": 10040000 }, { "condition": "ROUTE_EXISTS", "distanceMeters": 252734, "durationMillis": 12240000 } ] }, { "items": [ { "condition": "ROUTE_EXISTS", "distanceMeters": 166135, "durationMillis": 6596000 }, { "condition": "ROUTE_EXISTS", "distanceMeters": 216282, "durationMillis": 8797000 } ] } ] }
使用起點和目的地索引，在 2D 陣列中找出對應的 RouteMatrixItem，即可識別結果中的每條路線。舉例來說，描述從要求中索引 1 的起點和目的地 0 計算出的路線，會位於 RouteMatrix.rows 陣列的第 2 個元素，以及 RouteMatrixRow.items 陣列的第 1 個元素。
RouteMatrixItem
下列程式碼片段說明如何找出 RouteMatrixItem，以便尋找特定起點和目的地的路線：
// Find the route for origin 'x' and destination 'y'. const {matrix} = await RouteMatrix.computeRouteMatrix(request); const myRouteMatrixItem = matrix.rows[x].items[y];
選擇要傳回的欄位
要求路徑矩陣時，您必須使用欄位遮罩指定回應應傳回的資訊。
使用欄位遮罩也能確保您不會要求不必要的資料，進而縮短回應延遲時間，並避免傳回系統不需要的資訊。
設定
ComputeRoutesMatrixRequest.fields 屬性，指定所需欄位清單，如下方程式碼片段所示：
fields: ['durationMillis', 'distanceMeters', 'condition'],
決定要使用的欄位遮罩
以下說明如何判斷要使用的欄位，並為這些欄位建構欄位遮罩：
- 使用
['*']的欄位遮罩要求所有欄位。 - 查看您所需欄位的
RouteMatrixItem類別中欄位的階層。 使用下列格式，根據上一步顯示的欄位階層建構欄位遮罩：
topLevelField[.secondLevelField][.thirdLevelField][...]
舉例來說，如果是以下 RouteMatrixItem：
"travelAdvisory": { "fuelConsumptionMicroliters": 0, "tollInfo": { "estimatedPrices": [ { "currencyCode": "USD", "units": 4, "nanos": 400000000 } ] } },
如要只傳回 RouteMatrixItem 的 tollInfo 欄位，欄位遮罩如下：
fields: ['travelAdvisory.tollInfo']
如要改為要求預估燃料消耗量，您的欄位遮罩如下所示：
fields: ['travelAdvisory.fuelConsumptionMicroliters']
如要同時要求這兩項資訊，欄位遮罩如下：
fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']
如要要求完整的一組旅遊警示，欄位遮罩如下所示：
fields: ['travelAdvisory']
要求大眾運輸路線矩陣
取得大眾運輸路線矩陣，其中會使用該區域提供的大眾運輸選項。大眾運輸選項可能包括公車、地鐵和火車等。如要要求大眾運輸路線矩陣：
- 將
travelMode設定為TRANSIT - 要求
travelAdvisory欄位。
進一步瞭解大眾運輸路線。