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

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)
หมายเหตุ: ไลบรารีฝั่งเซิร์ฟเวอร์

ภาพรวม

บริการเมทริกซ์ระยะทางของ 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 ดังกล่าว ให้เปิดใช้ที่ https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

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

ราคา

ดูข้อมูลเกี่ยวกับนโยบายราคาและการใช้งานสำหรับบริการเมทริกซ์ระยะทาง JavaScript ได้ที่การใช้งานและการเรียกเก็บเงินสำหรับ Distance Matrix API (เดิม)

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

นโยบาย

การใช้บริการ Distance Matrix ต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Distance Matrix API (เดิม)

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

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

คุณเข้าถึงบริการเมทริกซ์ระยะทางภายในโค้ดผ่านออบเจ็กต์คอนสตรัคเตอร์ google.maps.DistanceMatrixService เมธอด DistanceMatrixService.getDistanceMatrix() จะเริ่มส่งคำขอไปยังบริการเมทริกซ์ระยะทาง โดยส่งออบเจ็กต์นิยามคู่ 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 (ต้องระบุ) — อาร์เรย์ที่มีสตริงที่อยู่ google.maps.LatLng ออบเจ็กต์ หรือออบเจ็กต์ Place อย่างน้อย 1 รายการเพื่อใช้คำนวณระยะทางและเวลา
  • destinations (จำเป็น) — อาร์เรย์ที่มีสตริงที่อยู่, ออบเจ็กต์ google.maps.LatLng หรือออบเจ็กต์สถานที่อย่างน้อย 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 ในที่สุดเราจะบังคับใช้ขีดจำกัดของคำค้นหาทั้งหมดต่อการโหลดแผนที่โดยอิงตามการใช้งาน 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 (ต้องระบุเพื่อให้ Object Literal ของ 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];
      }
    }
  }
}