บริการเมทริกซ์ระยะทาง

ภาพรวม

บริการ Distance Matrix ของ Google จะคำนวณระยะทางในการเดินทาง และระยะเวลาการเดินทางระหว่างต้นทางและปลายทางหลายแห่ง โดยใช้รูปแบบการเดินทางที่กำหนด

บริการนี้จะไม่แสดงข้อมูลเส้นทางแบบละเอียด คุณขอข้อมูลเส้นทาง ซึ่งรวมถึงโพลีไลน์และเส้นทางที่เป็นข้อความได้โดยส่งต้นทางและปลายทางเดียวที่ต้องการไปยัง Directions Service

เริ่มต้นใช้งาน

ก่อนใช้บริการเมทริกซ์ระยะทางใน Maps JavaScript API โปรดตรวจสอบก่อนว่าได้เปิดใช้ Distance Matrix API (เดิม) ใน Google Cloud Console ในโปรเจ็กต์เดียวกันกับที่ตั้งค่าไว้สำหรับ Maps JavaScript API

วิธีดูรายการ API ที่เปิดใช้

1. ไปที่ Google Cloud Console
2. คลิกปุ่มเลือกโปรเจ็กต์ จากนั้นเลือกโปรเจ็กต์เดียวกันกับที่คุณตั้งค่า สำหรับ Maps JavaScript API แล้วคลิกเปิด
3. จากรายการ API ในแดชบอร์ด ให้มองหา Distance Matrix API (เดิม)
4. หากเห็น API ในรายการ แสดงว่าคุณพร้อมใช้งานแล้ว หากไม่เห็น API ดังกล่าว ให้เปิดใช้ที่ https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

ราคาและนโยบาย

ราคา

ดูข้อมูลเกี่ยวกับนโยบายการกำหนดราคาและการใช้งานสำหรับบริการเมทริกซ์ระยะทาง JavaScript ได้ที่ การใช้งานและการเรียกเก็บเงิน สำหรับ Distance Matrix API (เดิม)

หมายเหตุ: คำค้นหาแต่ละรายการที่ส่งไปยังบริการ Distance Matrix จะถูกจำกัด ด้วยจำนวนองค์ประกอบที่อนุญาต โดยจำนวนต้นทางคูณด้วย จำนวนปลายทางจะเป็นตัวกำหนดจำนวนองค์ประกอบ

นโยบาย

การใช้บริการ Distance Matrix ต้องเป็นไปตาม นโยบายที่อธิบายไว้ สำหรับ Distance Matrix API (เดิม)

คำขอเมทริกซ์ระยะทาง

การเข้าถึงบริการเมทริกซ์ระยะทางเป็นแบบไม่พร้อมกัน เนื่องจาก Google Maps API ต้องทำการเรียกไปยังเซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอดการเรียกกลับเพื่อดำเนินการเมื่อคำขอเสร็จสมบูรณ์ เพื่อประมวลผลผลลัพธ์

คุณเข้าถึงบริการ Distance Matrix ภายในโค้ดผ่าน ออบเจ็กต์ตัวสร้าง google.maps.DistanceMatrixService DistanceMatrixService.getDistanceMatrix() เมธอด จะเริ่มคำขอไปยังบริการ Distance Matrix โดยส่งออบเจ็กต์ DistanceMatrixRequest ที่มีต้นทาง ปลายทาง และโหมดการเดินทาง รวมถึงเมธอดเรียกกลับเพื่อดำเนินการเมื่อ ได้รับคำตอบ

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

ดูตัวอย่าง

DistanceMatrixRequest มีช่องต่อไปนี้

• origins (ต้องระบุ) - อาร์เรย์ที่มีสตริงที่อยู่ google.maps.LatLng ออบเจ็กต์ หรือออบเจ็กต์ Place อย่างน้อย 1 รายการ ซึ่งใช้ในการคำนวณระยะทางและเวลา
• destinations (ต้องระบุ) - อาร์เรย์ที่มีสตริงที่อยู่ google.maps.LatLng ออบเจ็กต์ หรือออบเจ็กต์ Place อย่างน้อย 1 รายการที่จะใช้คำนวณระยะทางและเวลา
• travelMode (ไม่บังคับ) — รูปแบบการ เดินทางที่จะใช้เมื่อคำนวณเส้นทาง ดูส่วนเกี่ยวกับ รูปแบบการเดินทาง
• transitOptions (ไม่บังคับ) — ตัวเลือก ที่ใช้กับคำขอที่ travelMode เป็น TRANSIT เท่านั้น ค่าที่ถูกต้องจะอธิบายไว้ ในส่วนตัวเลือกการเดินทาง
• drivingOptions (ไม่บังคับ) ระบุ ค่าที่ใช้กับคำขอที่ travelMode เป็น DRIVING เท่านั้น ค่าที่ถูกต้องอธิบายไว้ ในส่วนตัวเลือกการขับขี่
• unitSystem (ไม่บังคับ) — ระบบหน่วยที่จะใช้เมื่อแสดงระยะทาง ค่าที่ยอมรับมีดังนี้
  • google.maps.UnitSystem.METRIC (ค่าเริ่มต้น)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (ไม่บังคับ) — หาก true ระบบจะคำนวณเส้นทางระหว่างต้นทางและปลายทาง เพื่อหลีกเลี่ยงทางหลวงหากเป็นไปได้
• avoidTolls (ไม่บังคับ) — หาก true ระบบจะคำนวณเส้นทางระหว่างจุดโดยใช้ เส้นทางที่ไม่ใช่ทางด่วน (หากเป็นไปได้)

โหมดการเดินทาง

เมื่อคำนวณเวลาและระยะทาง คุณจะระบุ โหมดการเดินทางที่จะใช้ได้ ปัจจุบันระบบรองรับโหมดการเดินทางต่อไปนี้

• BICYCLING คำขอ เส้นทางจักรยานผ่านเส้นทางจักรยานและถนนที่ต้องการ (ปัจจุบันมีให้บริการในสหรัฐอเมริกาและบางเมืองในแคนาดาเท่านั้น)
• DRIVING (ค่าเริ่มต้น) ระบุเส้นทางการขับขี่มาตรฐานโดยใช้เครือข่ายถนน
• TRANSIT ขอเส้นทางผ่าน เส้นทางขนส่งสาธารณะ คุณจะระบุตัวเลือกนี้ได้ก็ต่อเมื่อคำขอ มีคีย์ API เท่านั้น ดูส่วนตัวเลือกการขนส่งสาธารณะสำหรับตัวเลือกที่มีให้ในการขอประเภทนี้
• WALKING คำขอ เส้นทางเดินผ่านทางเท้าและทางเดินเท้า (หากมี)

ตัวเลือกขนส่งสาธารณะ

ขณะนี้บริการขนส่งสาธารณะยังอยู่ในขั้น "ทดลอง" ในระยะนี้ เราจะใช้การจำกัดอัตราเพื่อป้องกันการละเมิด API ในที่สุดเราจะ บังคับใช้ขีดจํากัดของคําค้นหาทั้งหมดต่อการโหลดแผนที่ 1 ครั้งตามการใช้งาน API อย่างเป็นธรรม

ตัวเลือกที่มีสำหรับคำขอเมทริกซ์ระยะทางจะแตกต่างกันไปตามโหมดการเดินทาง ในคำขอการเดินทาง ระบบจะไม่สนใจตัวเลือก avoidHighways และ avoidTolls คุณระบุตัวเลือกการกำหนดเส้นทางเฉพาะการขนส่งได้ผ่านออบเจ็กต์ลิเทอรัล TransitOptions

คำขอขนส่งเป็นคำขอเร่งด่วน ระบบจะแสดงผลการคำนวณสำหรับเวลาในอนาคตเท่านั้น

ออบเจ็กต์ลิเทอรัล TransitOptions มีฟิลด์ต่อไปนี้

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

โดยมีคำอธิบายฟิลด์ดังนี้

• arrivalTime (ไม่บังคับ) ระบุเวลาที่ต้องการ เมื่อมาถึงเป็นออบเจ็กต์ Date หากระบุเวลาถึง ระบบจะไม่สนใจเวลาออกเดินทาง
• departureTime (ไม่บังคับ) ระบุเวลาออกเดินทางที่ต้องการเป็นออบเจ็กต์ Date ระบบจะละเว้น departureTime หากมีการระบุ arrivalTime ค่าเริ่มต้นจะเป็นเวลาปัจจุบัน หากไม่ได้ระบุค่าสำหรับ departureTime หรือ arrivalTime
• modes (ไม่บังคับ) คืออาร์เรย์ที่มีออบเจ็กต์ลิเทอรัล TransitMode อย่างน้อย 1 รายการ ฟิลด์นี้จะรวมได้ก็ต่อเมื่อคำขอมีคีย์ API เท่านั้น TransitMode แต่ละรายการจะระบุรูปแบบการขนส่งที่ต้องการ ค่าที่อนุญาตมีดังนี้
  • BUS ระบุว่าเส้นทางที่คำนวณแล้วควรแนะนำให้เดินทางโดยรถประจำทาง
  • RAIL ระบุว่าเส้นทางที่คำนวณแล้วควรเลือกการเดินทางด้วยรถไฟ รถราง รถไฟฟ้ารางเบา และ รถไฟใต้ดิน
  • SUBWAY ระบุว่าเส้นทางที่คำนวณแล้ว ควรเลือกการเดินทางโดยรถไฟใต้ดิน
  • TRAIN แสดงว่าเส้นทางที่คำนวณแล้วควรเลือกการเดินทางโดยรถไฟ
  • TRAM แสดงว่าเส้นทางที่คำนวณแล้วควรเลือกการเดินทางด้วยรถรางและรถไฟฟ้ารางเบา
• routingPreference (ไม่บังคับ) ระบุค่ากำหนด สำหรับเส้นทางการขนส่ง การใช้ตัวเลือกนี้จะช่วยให้คุณเลือกตัวเลือกที่ต้องการได้ แทนที่จะยอมรับเส้นทางที่ดีที่สุดเริ่มต้นที่ API เลือก ระบุฟิลด์นี้ได้ก็ต่อเมื่อคำขอมีคีย์ API เท่านั้น ค่าที่อนุญาตมีดังนี้
  • FEWER_TRANSFERS ระบุว่าเส้นทางที่คำนวณแล้วควรเลือกการต่อรถจำนวนจำกัด
  • LESS_WALKING ระบุว่าเส้นทางที่คำนวณแล้วควรมีการเดินในระยะทางที่จำกัด

ตัวเลือกการขับขี่

ใช้ออบเจ็กต์ drivingOptions เพื่อระบุเวลาออกเดินทางสำหรับ การคำนวณเส้นทางที่ดีที่สุดไปยังจุดหมายปลายทางตามสภาพการจราจรที่คาดการณ์ไว้ นอกจากนี้ คุณยังระบุได้ด้วยว่าต้องการให้เวลาโดยประมาณในการจราจรเป็นแบบมองในแง่ร้าย มองในแง่ดี หรือ การคาดคะเนที่ดีที่สุดโดยอิงตามสภาพการจราจรในอดีตและการจราจรแบบเรียลไทม์

ออบเจ็กต์ drivingOptions มีช่องต่อไปนี้

{
  departureTime: Date,
  trafficModel: TrafficModel
}

โดยมีคำอธิบายฟิลด์ดังนี้

• departureTime (ต้องระบุเพื่อให้ ออบเจ็กต์ลิเทอรัล drivingOptions ใช้ได้) ระบุ เวลาออกเดินทางที่ต้องการเป็นออบเจ็กต์ Date ค่าต้อง ตั้งเป็นเวลาปัจจุบันหรือเวลาในอนาคต ต้องไม่ใช่วันที่ที่ผ่านมาแล้ว (API จะแปลงวันที่ทั้งหมดเป็น UTC เพื่อให้มั่นใจว่าการจัดการจะสอดคล้องกัน ในเขตเวลาต่างๆ) หากคุณใส่ departureTime ในคำขอ API จะแสดงเส้นทางที่ดีที่สุดตามสภาพการจราจรที่คาดไว้ในขณะนั้น และ รวมเวลาที่คาดการณ์ในการจราจร (duration_in_traffic) ในการตอบกลับ หากคุณไม่ได้ระบุเวลาออกเดินทาง (กล่าวคือ หากคำขอไม่มี drivingOptions) เส้นทางที่แสดง จะเป็นเส้นทางที่ดีโดยทั่วไปโดยไม่คำนึงถึงสภาพการจราจร
• trafficModel (ไม่บังคับ) ระบุสมมติฐานที่จะ ใช้เมื่อคำนวณเวลาในการเข้าชม การตั้งค่านี้จะส่งผลต่อค่า ที่แสดงในช่อง duration_in_traffic ในการตอบกลับ ซึ่งมีเวลาที่คาดการณ์ในการเดินทางตามค่าเฉลี่ยในอดีต ค่าเริ่มต้นคือ best_guess ค่าที่อนุญาตมีดังนี้
  • bestguess (ค่าเริ่มต้น) ระบุว่าค่าที่ส่งคืน duration_in_traffic ควรเป็นค่าประมาณที่ดีที่สุดของเวลา ในการเดินทางโดยพิจารณาจากสภาพการจราจรที่ผ่านมาและ การจราจรแบบเรียลไทม์ การจราจรแบบเรียลไทม์จะมีความสําคัญมากขึ้นเมื่อ departureTime ใกล้กับเวลาปัจจุบัน
  • pessimistic แสดงว่า duration_in_traffic ที่แสดงควรนานกว่าเวลาเดินทางจริง ในวันส่วนใหญ่ แม้ว่าบางวันที่มีสภาพการจราจรแย่เป็นพิเศษ อาจมีค่าเกินกว่านี้
  • optimistic แสดงว่า duration_in_traffic ที่แสดงควรสั้นกว่า เวลาเดินทางจริงในวันส่วนใหญ่ แม้ว่าในบางวันที่มีสภาพการจราจรดีเป็นพิเศษ อาจเร็วกว่าค่านี้

ด้านล่างนี้คือตัวอย่าง DistanceMatrixRequest สำหรับเส้นทางการขับรถ รวมถึงเวลาออกเดินทางและรูปแบบการจราจร

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

การตอบกลับของ Distance Matrix

การเรียกใช้บริการ Distance Matrix ที่สำเร็จจะแสดงผลออบเจ็กต์ DistanceMatrixResponse และออบเจ็กต์ DistanceMatrixStatus ระบบจะส่งค่าเหล่านี้ไปยังฟังก์ชัน Callback ที่คุณระบุในคำขอ

ออบเจ็กต์ DistanceMatrixResponse มีข้อมูลระยะทางและ ระยะเวลาสำหรับคู่ต้นทาง/ปลายทางแต่ละคู่ที่คำนวณเส้นทางได้

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

ผลลัพธ์ของเมทริกซ์ระยะทาง

ช่องที่รองรับในการตอบกลับมีคำอธิบายอยู่ด้านล่าง

• originAddresses คืออาร์เรย์ที่มีสถานที่ตั้ง ที่ส่งในฟิลด์ origins ของคำขอเมทริกซ์ระยะทาง ระบบจะแสดงที่อยู่ตามรูปแบบที่เข้ารหัสพิกัดภูมิศาสตร์
• destinationAddresses คืออาร์เรย์ที่มีสถานที่ตั้งที่ส่งในฟิลด์ destinations ในรูปแบบที่ตัวเข้ารหัสพิกัดภูมิศาสตร์แสดงผล
• rows คืออาร์เรย์ของออบเจ็กต์ DistanceMatrixResponseRow โดยแต่ละแถวจะสอดคล้องกับต้นทาง
• elements เป็นองค์ประกอบย่อยของ rows และสอดคล้อง กับการจับคู่ต้นทางของแถวกับปลายทางแต่ละแห่ง โดยจะมีข้อมูลสถานะ ระยะเวลา ระยะทาง และค่าโดยสาร (หากมี) สำหรับคู่ต้นทาง/ปลายทางแต่ละคู่
• element แต่ละรายการจะมีช่องต่อไปนี้
  • status: ดูรายการรหัสสถานะที่อาจเป็นไปได้ใน รหัสสถานะ
  • duration: ระยะเวลาที่ใช้ในการเดินทางในเส้นทางนี้ แสดงเป็นวินาที (ฟิลด์ value) และเป็น text ค่าข้อความจะได้รับการจัดรูปแบบตาม unitSystem ที่ระบุในคำขอ (หรือในเมตริก หากไม่มี การระบุค่ากำหนด)
  • duration_in_traffic: ระยะเวลาที่ใช้ในการ เดินทางในเส้นทางนี้โดยพิจารณาจากสภาพการจราจรในปัจจุบัน แสดงเป็นวินาที (ฟิลด์ value) และเป็น text ค่าข้อความจะได้รับการจัดรูปแบบตาม unitSystem ที่ระบุในคำขอ (หรือในเมตริก หากไม่มี การระบุค่ากำหนด) ระบบจะแสดง duration_in_traffic เมื่อมีข้อมูลการเข้าชมเท่านั้น โดยจะตั้งค่า mode เป็น driving และรวม departureTime เป็นส่วนหนึ่งของฟิลด์ distanceMatrixOptions ในคำขอ
  • distance: ระยะทางทั้งหมดของเส้นทางนี้ แสดงเป็นเมตร (value) และเป็น text ค่าข้อความ จะได้รับการจัดรูปแบบตามunitSystemที่ระบุไว้ใน คำขอ (หรือในเมตริก หากไม่ได้ระบุค่ากำหนด)
  • fare: มีค่าโดยสารทั้งหมด (นั่นคือค่าตั๋วทั้งหมด) ในเส้นทางนี้ ระบบจะแสดงพร็อพเพอร์ตี้นี้สําหรับคําขอการเดินทางด้วยขนส่งสาธารณะเท่านั้น และสําหรับผู้ให้บริการขนส่งสาธารณะที่มีข้อมูลค่าโดยสารเท่านั้น ข้อมูลประกอบด้วย
    • currency: รหัสสกุลเงิน ISO 4217 ที่ระบุสกุลเงินที่แสดงจำนวนเงิน
    • value: จำนวนค่าโดยสารทั้งหมดในสกุลเงินที่ระบุ ไว้ข้างต้น

รหัสสถานะ

การตอบกลับเมตริกซ์ระยะทางจะมีรหัสสถานะสำหรับการตอบกลับโดยรวม รวมถึงสถานะของแต่ละองค์ประกอบ

รหัสสถานะการตอบกลับ

รหัสสถานะที่ใช้กับ DistanceMatrixResponse จะ ส่งในออบเจ็กต์ DistanceMatrixStatus และมีดังนี้

• OK — คำขอถูกต้อง ระบบอาจแสดงสถานะนี้แม้ว่าจะไม่พบเส้นทางระหว่างต้นทางและ ปลายทางใดๆ ก็ตาม ดูข้อมูลสถานะระดับองค์ประกอบได้ที่รหัสสถานะขององค์ประกอบ
• INVALID_REQUEST — คำขอที่ระบุไม่ถูกต้อง ซึ่งมักเกิดจากการไม่ได้กรอกข้อมูลในช่องที่ต้องกรอก ดู รายการช่องที่รองรับด้านบน
• MAX_ELEMENTS_EXCEEDED — ผลิตภัณฑ์ของต้นทางและปลายทางเกินขีดจำกัดต่อการค้นหา
• MAX_DIMENSIONS_EXCEEDED — คำขอของคุณมีต้นทางมากกว่า 25 รายการ หรือมีปลายทางมากกว่า 25 รายการ
• OVER_QUERY_LIMIT — แอปพลิเคชันของคุณขอองค์ประกอบมากเกินไปภายในระยะเวลาที่อนุญาต คำขอควร สำเร็จหากคุณลองอีกครั้งหลังจากผ่านไประยะเวลาที่เหมาะสม
• REQUEST_DENIED — บริการปฏิเสธการใช้บริการ Distance Matrix โดยหน้าเว็บของคุณ
• UNKNOWN_ERROR — ประมวลผลคำขอเมทริกซ์ระยะทางไม่ได้เนื่องจากเซิร์ฟเวอร์เกิดข้อผิดพลาด คำขออาจสำเร็จหากคุณลองอีกครั้ง

รหัสสถานะขององค์ประกอบ

รหัสสถานะต่อไปนี้ใช้กับออบเจ็กต์ DistanceMatrixElement ที่เฉพาะเจาะจง

• NOT_FOUND — ระบบระบุพิกัดต้นทางและ/หรือปลายทางของ การจับคู่นี้ไม่ได้
• OK - การตอบกลับมีผลลัพธ์ที่ถูกต้อง
• ZERO_RESULTS — ไม่พบเส้นทางระหว่างต้นทางกับจุดหมาย

การแยกวิเคราะห์ผลลัพธ์

ออบเจ็กต์ DistanceMatrixResponse มี row หนึ่งรายการสำหรับแต่ละต้นทางที่ส่งผ่านในคำขอ แต่ละแถว มีฟิลด์ element สำหรับการจับคู่แต่ละรายการของต้นทางนั้นกับ ปลายทางที่ระบุ

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}