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

นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (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 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];
      }
    }
  }
}