ภาพรวม
บริการ ระยะทาง เมทริกซ์ของ Google จะคำนวณระยะทางและระยะเวลาการเดินทางระหว่างต้นทางและปลายทางหลายแห่งโดยใช้รูปแบบการเดินทางที่ระบุ
บริการนี้จะไม่แสดงข้อมูลเส้นทางโดยละเอียด คุณจะดูข้อมูลเส้นทาง รวมถึงเส้นประกอบและเส้นทางแบบข้อความได้โดยการส่งต้นทางและปลายทางเดียวที่ต้องการไปยังบริการเส้นทาง
การเริ่มต้นใช้งาน
ก่อนใช้บริการ Distance Matrix ใน Maps JavaScript API ก่อนอื่นให้ตรวจสอบว่าได้เปิดใช้ Distance Matrix API ใน Google Cloud Console ในโปรเจ็กต์เดียวกันกับที่คุณตั้งค่าไว้สำหรับ Maps JavaScript API
วิธีดูรายการ API ที่เปิดใช้
- ไปที่ Google Cloud Console
- คลิกปุ่มเลือกโปรเจ็กต์ จากนั้นเลือกโปรเจ็กต์เดียวกับที่คุณตั้งค่าสำหรับ 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 โปรดดูการใช้งานและการเรียกเก็บเงินสำหรับ Distance Matrix API
หมายเหตุ: การค้นหาแต่ละรายการที่ส่งไปยังบริการ Distance Matrix จะถูกจำกัดตามจำนวนองค์ประกอบที่อนุญาต โดยที่จำนวนต้นทางคูณจำนวนปลายทางเป็นตัวกำหนดจำนวนขององค์ประกอบ
นโยบาย
การใช้บริการ Range Matrix ต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Distance Matrix API
คำขอเมทริกซ์ระยะทาง
การเข้าถึงบริการ Distance Matrix คือระบบอะซิงโครนัส เนื่องจาก Google Maps API ต้องเรียกไปยังเซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอด callback มาดําเนินการเมื่อดำเนินการตามคำขอเสร็จสมบูรณ์ เพื่อประมวลผลผลลัพธ์
คุณเข้าถึงบริการ 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
(จำเป็น) — อาร์เรย์ที่มีสตริงที่อยู่อย่างน้อย 1 รายการ ออบเจ็กต์google.maps.LatLng
รายการ หรือออบเจ็กต์Place ที่ใช้คำนวณระยะทางและเวลาdestinations
(จำเป็น) — อาร์เรย์ที่มีสตริงที่อยู่อย่างน้อย 1 รายการ ออบเจ็กต์google.maps.LatLng
รายการ หรือออบเจ็กต์สถานที่ที่จะคำนวณระยะทางและเวลา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
ในคำขอขนส่งสาธารณะ คุณระบุตัวเลือกการกําหนดเส้นทางเฉพาะการขนส่งได้ผ่าน Object Litel ของ TransitOptions
คำขอขนส่งสาธารณะต้องกำหนดเวลา ระบบจะแสดงผลการคำนวณสำหรับเวลาในอนาคตเท่านั้น
Object Literal ของ 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 แบบสำเร็จจะส่งกลับออบเจ็กต์ DistanceMatrixResponse
และออบเจ็กต์ DistanceMatrixStatus
ระบบจะส่งต่อไปยังฟังก์ชันเรียกกลับที่คุณระบุในคำขอ
ออบเจ็กต์ 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
ให้ลูกค้าแพ็กเกจพรีเมียมของแพลตฟอร์ม Google Maps เมื่อมีข้อมูลการจราจรเท่านั้น ระบบจะตั้งค่าmode
เป็นdriving
และรวมdepartureTime
ไว้เป็นส่วนหนึ่งของช่องdistanceMatrixOptions
ในคำขอdistance
: ระยะทางรวมของเส้นทางนี้ แสดงเป็น เมตร (value
) และtext
ค่าข้อความจะมีการจัดรูปแบบตามunitSystem
ที่ระบุในคำขอ (หรือในเมตริก ถ้าไม่ได้ระบุค่ากำหนด)fare
: รวมค่าโดยสารทั้งหมด (ซึ่งเป็นราคารวมของตั๋ว) สำหรับเส้นทางนี้ ที่พักนี้จะแสดงสำหรับคำขอขนส่งสาธารณะเท่านั้นและเฉพาะสำหรับผู้ให้บริการขนส่งสาธารณะที่มีข้อมูลค่าโดยสาร ซึ่งประกอบด้วยcurrency
: รหัสสกุลเงินในรูปแบบ ISO 4217 ที่ระบุสกุลเงินที่ใช้แสดงจำนวนเงินvalue
: จำนวนเงินค่าโดยสารทั้งหมดในสกุลเงินที่ระบุไว้ข้างต้น
รหัสสถานะ
การตอบกลับ Distance Matrix จะมีรหัสสถานะของการตอบกลับโดยรวม พร้อมสถานะของแต่ละองค์ประกอบ
รหัสสถานะการตอบสนอง
ระบบจะส่งรหัสสถานะที่ใช้กับ DistanceMatrixResponse
ในออบเจ็กต์ DistanceMatrixStatus
และมีรายการต่อไปนี้
OK
— คำขอถูกต้อง คุณจะแสดงผลสถานะนี้ได้แม้ว่าจะไม่พบเส้นทางระหว่างต้นทางและปลายทางใดๆ ดูรหัสสถานะองค์ประกอบสำหรับข้อมูลสถานะระดับองค์ประกอบINVALID_REQUEST
— คำขอที่ระบุ ไม่ถูกต้อง ปัญหานี้มักเกิดจากการขาดช่องที่ต้องกรอก ดูรายการช่องที่รองรับด้านบนMAX_ELEMENTS_EXCEEDED
— ผลิตภัณฑ์ของต้นทางและปลายทางเกินขีดจำกัดต่อการค้นหาMAX_DIMENSIONS_EXCEEDED
คำขอของคุณมีต้นทางมากกว่า 25 แห่ง หรือปลายทางมากกว่า 25 แห่งOVER_QUERY_LIMIT
— แอปพลิเคชันของคุณขอองค์ประกอบมากเกินไปภายในระยะเวลาที่อนุญาต คำขอควรจะประสบความสำเร็จหากคุณลองอีกครั้งหลังจากผ่านไประยะหนึ่งREQUEST_DENIED
— บริการปฏิเสธการใช้บริการ Distance Matrix หน้าเว็บของคุณUNKNOWN_ERROR
- ประมวลผลคำขอ Distance Matrix ไม่ได้เนื่องจากเกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ คำขออาจสำเร็จหากคุณลองอีกครั้ง
รหัสสถานะองค์ประกอบ
รหัสสถานะต่อไปนี้ใช้กับออบเจ็กต์ 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]; } } } }