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

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

ภาพรวม

บริการ Distance Matrix ของ 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 ต้องเป็นไปตาม นโยบายที่อธิบาย สำหรับ Distance Matrix API (เดิม)

คำขอ Distance Matrix

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

คุณเข้าถึงบริการ Distance Matrix ภายในโค้ดผ่าน ออบเจ็กต์ตัวสร้าง google.maps.DistanceMatrixService เมธอด DistanceMatrixService.getDistanceMatrix() จะเริ่มคำขอไปยังบริการ Distance Matrix โดยส่ง Object Literal 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 ออบเจ็กต์ หรือออบเจ็กต์ 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 เราจะ บังคับใช้ขีดจํากัดของคําค้นหาทั้งหมดต่อการโหลดแผนที่ในที่สุดตามการใช้งาน 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'
  }
}

การตอบกลับของเมทริกซ์ระยะทาง

การเรียกใช้บริการ 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 ของคำขอเมตริกซ์ระยะทาง ระบบจะแสดงที่อยู่ตามรูปแบบที่เข้ารหัสพิกัดภูมิศาสตร์
  • 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 หนึ่งรายการสำหรับแต่ละต้นทางที่ส่งผ่านในคำขอ แต่ละแถว มีฟิลด์ 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];
      }
    }
  }
}