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

ภาพรวม

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

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

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

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

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

  1. ไปที่หน้า Google Cloud Console
  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 โปรดดู การใช้งานและการเรียกเก็บเงิน สำหรับ Distance Matrix API

หมายเหตุ: การค้นหาแต่ละครั้งที่ส่งไปยังบริการ Distance Matrix ตามจํานวนองค์ประกอบที่อนุญาต ซึ่งจํานวนต้นทางคูณ จำนวนของปลายทาง กำหนดจำนวนองค์ประกอบ

นโยบาย

การใช้บริการเมทริกซ์ระยะทางจะต้องเป็นไปตาม นโยบายที่อธิบาย สำหรับ Distance Matrix API

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

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

คุณเข้าถึงบริการเมทริกซ์ระยะทางภายในโค้ดของคุณผ่าน ออบเจ็กต์ตัวสร้าง google.maps.DistanceMatrixService เมธอด DistanceMatrixService.getDistanceMatrix() เริ่มคำขอไปยังบริการ Distance Matrix DistanceMatrixRequest Object Literal ที่มีต้นทาง ปลายทาง และโหมดการเดินทาง ตลอดจน Method ของ 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 รายการ หรือสถานที่ ที่จะคำนวณระยะทางและเวลา
  • destinations (ต้องระบุ) — อาร์เรย์ที่มีหรือ สตริงที่อยู่เพิ่มเติม ออบเจ็กต์ 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 เพิ่มเติม ฟิลด์นี้สามารถ ซึ่งจะรวมอยู่ด้วยหากคำขอมีคีย์ API แต่ละTransitMode ระบุรูปแบบการเดินทางที่ต้องการ ค่าที่ใช้ได้มีดังนี้
    • BUS บ่งชี้ว่า ที่ใช้คำนวณเส้นทางที่ควรจะต้องเดินทางโดยรถประจำทาง
    • RAIL บ่งชี้ว่า เส้นทางที่คำนวณแล้วควรเดินทางโดยรถไฟ รถราง รถไฟฟ้ารางเบา และ รถไฟใต้ดิน
    • SUBWAY บ่งชี้ว่า เส้นทางที่คำนวณควรเลือกใช้การเดินทางโดยรถไฟใต้ดิน
    • TRAIN บ่งชี้ว่า เส้นทางที่คำนวณควรเลือกใช้การเดินทางโดยรถไฟ
    • TRAM บ่งชี้ว่า เส้นทางที่คำนวณควรเลือกใช้การเดินทางโดยรถรางและรถไฟฟ้ารางเบา
  • routingPreference (ไม่บังคับ) ระบุค่ากำหนด สำหรับเส้นทางการขนส่งสาธารณะ เมื่อใช้ตัวเลือกนี้ คุณอาจให้น้ำหนักกับตัวเลือกที่แสดงผล แทนการยอมรับเส้นทางที่ดีที่สุดเริ่มต้นที่ API เลือกไว้ ช่องนี้ระบุได้เฉพาะเมื่อคำขอมี คีย์ API ค่าที่ใช้ได้มีดังนี้
    • FEWER_TRANSFERS ระบุว่าเส้นทางที่คำนวณควรต้องการ การโอน
    • LESS_WALKING ระบุว่าเส้นทางที่คำนวณนั้นต้องการเวลาที่จำกัด การเดิน

ตัวเลือกการขับขี่

ใช้ออบเจ็กต์ drivingOptions เพื่อระบุเวลาออกเดินทางสำหรับ คำนวณเส้นทางที่ดีที่สุดไปยังจุดหมายของคุณโดยพิจารณาจากสภาพการจราจรที่คาดหวัง คุณสามารถ และระบุว่าคุณต้องการให้เวลาโดยประมาณในการเข้าชมมีลักษณะเป็นแง่บวก มองโลกในแง่ดี หรือ ค่าประมาณที่ดีที่สุด ซึ่งพิจารณาจากสภาพการจราจรที่ผ่านมาและการเข้าชมสด

ออบเจ็กต์ drivingOptions มีช่องต่อไปนี้

{
  departureTime: Date,
  trafficModel: TrafficModel
}

ฟิลด์เหล่านี้จะอธิบายไว้ด้านล่าง

  • departureTime (ต้องระบุสำหรับ drivingOptions Object Literal ที่ถูกต้อง) ระบุ เวลาออกเดินทางเป็นออบเจ็กต์ 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: จำนวนเงินค่าโดยสารทั้งหมดในสกุลเงินที่ระบุ ที่ด้านบน

รหัสสถานะ

การตอบสนองของ Distance Matrix มีรหัสสถานะสำหรับการตอบสนองเป็น ทั้งหมด ตลอดจนสถานะของแต่ละองค์ประกอบ

รหัสสถานะการตอบกลับ

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