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

นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (EEA)
หมายเหตุ: ไลบรารีฝั่งเซิร์ฟเวอร์

ภาพรวม

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

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

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

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

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

  1. ไปที่ คอนโซล Google Cloud
  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 API (เดิม)

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

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

คุณเข้าถึงบริการตารางเมตริกระยะทางภายในโค้ดผ่านออบเจ็กต์คอนสตรัคเตอร์ google.maps.DistanceMatrixService เมธอด DistanceMatrixService.getDistanceMatrix() จะเริ่มต้นคําขอไปยังบริการตารางระยะทาง โดยส่งออบเจ็กต์ 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'   } }

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

การเรียกใช้บริการตารางเมตริกระยะทางที่สำเร็จจะแสดงผลออบเจ็กต์ 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 — บริการปฏิเสธการใช้บริการตารางระยะทางโดยหน้าเว็บของคุณ
  • UNKNOWN_ERROR — ประมวลผลคำขอตารางระยะทางไม่ได้เนื่องจากข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ คำขออาจสำเร็จหากคุณลองอีกครั้ง

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

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

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

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

ออบเจ็กต์ DistanceMatrixResponse มี row 1 รายการสําหรับต้นทางแต่ละรายการที่ส่งในคําขอ แต่ละแถวจะมีช่อง 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];       }     }   } }