ภาพรวม
บริการ Distance Matrix ของ Google จะคำนวณระยะทาง และระยะเวลาเดินทางระหว่างต้นทางและปลายทาง โดยใช้รูปแบบการเดินทางหนึ่งๆ
บริการนี้จะไม่แสดงผลข้อมูลเส้นทางโดยละเอียด รับข้อมูลเส้นทาง รวมถึงเส้นประกอบและเส้นทางแบบข้อความได้โดยการส่งผ่านต้นทางและปลายทางที่ต้องการไปยังบริการเส้นทาง
เริ่มต้นใช้งาน
ก่อนที่จะใช้บริการ Distance Matrix ใน Maps JavaScript API ก่อนอื่นให้ตรวจสอบว่าได้เปิดใช้งาน Distance Matrix API ใน Google Cloud Console ในโปรเจ็กต์เดียวกับที่คุณตั้งค่าสำหรับ Maps JavaScript API
วิธีดูรายการ API ที่เปิดใช้มีดังนี้
- ไปที่ คอนโซล Google Cloud
- คลิกปุ่มเลือกโปรเจ็กต์ จากนั้นเลือกโปรเจ็กต์เดียวกันกับที่ตั้งค่าไว้สำหรับ Maps JavaScript API แล้วคลิกเปิด
- จากรายการ API ในแดชบอร์ด ให้มองหา Distance Matrix API
- หากเห็น API ในรายการ แสดงว่าทุกอย่างเรียบร้อยแล้ว หากไม่มี API อยู่ในรายการ ให้เปิดใช้โดยทำดังนี้
- ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API เพื่อแสดงแท็บคลัง หรือเลือกคลังจากเมนูด้านซ้าย
- ค้นหา Distance Matrix API แล้วเลือกรายการดังกล่าวจากรายการผลลัพธ์
- เลือกเปิดใช้ เมื่อกระบวนการเสร็จสิ้นแล้ว Distance Matrix API จะปรากฏในรายการ API ในแดชบอร์ด
ราคาและนโยบาย
ราคา
ตั้งแต่วันที่ 16 กรกฎาคม 2018 แพ็กเกจราคาแบบจ่ายเมื่อใช้ใหม่มีผลกับ Maps, Routes และ Places หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับราคาใหม่และขีดจำกัดการใช้งานสำหรับการใช้บริการ JavaScript Distance Matrix API โปรดดูการใช้งานและการเรียกเก็บเงินสำหรับ Distance Matrix API
หมายเหตุ: การค้นหาแต่ละรายการที่ส่งไปยังบริการเมทริกซ์ระยะทางจะถูกจำกัดด้วยจำนวนองค์ประกอบที่อนุญาต โดยจำนวนต้นทางคูณกับจำนวนปลายทางจะกำหนดจำนวนองค์ประกอบ
นโยบาย
การใช้บริการ Distance Matrix API ต้องเป็นไปตามนโยบายที่อธิบาย สำหรับ Distance Matrix API
คำขอเมทริกซ์ระยะทาง
การเข้าถึงบริการ Distance Matrix ไม่พร้อมกัน เนื่องจาก Google Maps API จำเป็นต้องทำการเรียกไปยังเซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอด callback เพื่อเรียกใช้เมื่อคำขอเสร็จสมบูรณ์เพื่อประมวลผลผลลัพธ์
คุณเข้าถึงบริการเมทริกซ์ระยะทางภายในโค้ดผ่านออบเจ็กต์ตัวสร้าง google.maps.DistanceMatrixService
เมธอด DistanceMatrixService.getDistanceMatrix()
จะเริ่มต้นคำขอไปยังบริการ Distance Matrix โดยส่งลิเทอรัลออบเจ็กต์ DistanceMatrixRequest
ที่มีต้นทาง จุดหมาย และโหมดการเดินทาง รวมถึงวิธี Callback ที่จะทำงานเมื่อได้รับการตอบสนอง
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
(ต้องระบุ) — อาร์เรย์ที่มีสตริงที่อยู่อย่างน้อย 1 รายการ, ออบเจ็กต์google.maps.LatLng
รายการ หรือออบเจ็กต์ Place ซึ่งใช้คำนวณระยะทางและเวลาdestinations
(ต้องระบุ) — อาร์เรย์ที่มีสตริงที่อยู่อย่างน้อย 1 รายการ, ออบเจ็กต์google.maps.LatLng
รายการ หรือออบเจ็กต์ Place เพื่อคำนวณระยะทางและเวลา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 ท้ายที่สุดแล้ว เราจะบังคับใช้ขีดจำกัดการค้นหาทั้งหมดต่อการโหลดแผนที่ตามการใช้งานที่เหมาะสมของ API
ตัวเลือกที่ใช้ได้กับคำขอเมทริกซ์ระยะทางจะแตกต่างกันไปตามรูปแบบการเดินทาง
ระบบจะไม่สนใจตัวเลือก avoidHighways
และ avoidTolls
ในคำขอขนส่งสาธารณะ คุณระบุตัวเลือกการกำหนดเส้นทางเฉพาะขนส่งสาธารณะได้ผ่านลิเทอรัลของออบเจ็กต์ TransitOptions
คำขอขนส่งสาธารณะขึ้นอยู่กับเวลา ระบบจะแสดงผลการคำนวณสำหรับเวลาในอนาคตเท่านั้น
ลิเทอรัลออบเจ็กต์ TransitOptions
มีช่องต่อไปนี้
{ arrivalTime: Date, departureTime: Date, modes: [transitMode1, transitMode2] routingPreference: TransitRoutePreference }
ฟิลด์เหล่านี้จะอธิบายไว้ด้านล่าง
arrivalTime
(ไม่บังคับ) ระบุเวลาถึงที่ต้องการเป็นออบเจ็กต์Date
หากระบุเวลาถึง ระบบจะไม่สนใจเวลาออกเดินทางdepartureTime
(ไม่บังคับ) ระบุเวลาออกเดินทางที่ต้องการเป็นออบเจ็กต์Date
ระบบจะไม่สนใจdepartureTime
หากระบุarrivalTime
ค่าเริ่มต้นคือปัจจุบัน (ซึ่งก็คือเวลาปัจจุบัน) หากไม่ได้ระบุค่าสำหรับdepartureTime
หรือarrivalTime
modes
(optional) คืออาร์เรย์ที่มีอ็อบเจกต์ลิเทอรัลTransitMode
อย่างน้อย 1 รายการ รวมช่องนี้ได้เฉพาะเมื่อคำขอมีคีย์ APITransitMode
แต่ละรายการจะระบุรูปแบบการเดินทางที่ต้องการ อนุญาตให้ใช้ค่าต่อไปนี้ได้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 ที่สำเร็จจะแสดงออบเจ็กต์ 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
ของคำขอ Distance Matrix ที่อยู่จะถูกส่งคืนตามที่มีการจัดรูปแบบโดยโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์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
จำนวน 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]; } } } }