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

ภาพรวม

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

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

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

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

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

1. ไปที่ คอนโซล Google Cloud
2. คลิกปุ่มเลือกโปรเจ็กต์ จากนั้นเลือกโปรเจ็กต์เดียวกันกับที่ตั้งค่าไว้สำหรับ Maps JavaScript API แล้วคลิกเปิด
3. จากรายการ API ในแดชบอร์ด ให้มองหา Distance Matrix API
4. หากเห็น API ในรายการ แสดงว่าทุกอย่างเรียบร้อยแล้ว หากไม่มี API อยู่ในรายการ ให้เปิดใช้โดยทำดังนี้
   1. ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API เพื่อแสดงแท็บคลัง หรือเลือกคลังจากเมนูด้านซ้าย
   2. ค้นหา Distance Matrix API แล้วเลือกรายการดังกล่าวจากรายการผลลัพธ์
   3. เลือกเปิดใช้ เมื่อกระบวนการเสร็จสิ้นแล้ว 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 รายการ รวมช่องนี้ได้เฉพาะเมื่อคำขอมีคีย์ 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 ซึ่งจะส่งต่อไปยังฟังก์ชัน 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];
      }
    }
  }
}