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

ภาพรวม

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

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

ราคา

ตั้งแต่วันที่ 16 กรกฎาคม 2018 แพ็กเกจราคาแบบจ่ายตามการใช้งานใหม่มีผลกับแผนที่ เส้นทาง และสถานที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับราคาใหม่และขีดจํากัดการใช้งานสําหรับบริการเมทริกซ์ระยะทาง 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];
      }
    }
  }
}