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

ภาพรวม

บริการ ระยะทาง เมทริกซ์ของ 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 จะถูกจำกัดตามจำนวนองค์ประกอบที่อนุญาต โดยที่จำนวนต้นทางคูณจำนวนปลายทางเป็นตัวกำหนดจำนวนขององค์ประกอบ

นโยบาย

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

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

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

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

คำขอขนส่งสาธารณะต้องกำหนดเวลา ระบบจะแสดงผลการคำนวณสำหรับเวลาในอนาคตเท่านั้น

Object Literal ของ 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 ระบบจะส่งต่อไปยังฟังก์ชันเรียกกลับที่คุณระบุในคำขอ

ออบเจ็กต์ 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 ให้ลูกค้าแพ็กเกจพรีเมียมของแพลตฟอร์ม Google Maps เมื่อมีข้อมูลการจราจรเท่านั้น ระบบจะตั้งค่า 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 — บริการปฏิเสธการใช้บริการ Distance Matrix หน้าเว็บของคุณ
  • UNKNOWN_ERROR - ประมวลผลคำขอ Distance Matrix ไม่ได้เนื่องจากเกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ คำขออาจสำเร็จหากคุณลองอีกครั้ง

รหัสสถานะองค์ประกอบ

รหัสสถานะต่อไปนี้ใช้กับออบเจ็กต์ 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];
      }
    }
  }
}