Dịch vụ ma trận khoảng cách

Tổng quan

Dịch vụ Distance Matrix của Google tính toán quãng đường và thời gian di chuyển giữa nhiều điểm xuất phát và điểm đến bằng một phương tiện di chuyển nhất định.

Dịch vụ này không trả về thông tin chi tiết về tuyến đường. Bạn có thể lấy thông tin tuyến đường, bao gồm cả đường đa tuyến và chỉ đường dạng văn bản bằng cách truyền điểm xuất phát và điểm đến mong muốn đến Dịch vụ chỉ đường.

Bắt đầu

Trước khi sử dụng dịch vụ Ma trận khoảng cách trong API Maps JavaScript, trước tiên, hãy đảm bảo rằng bạn đã bật API Ma trận khoảng cách trong Google Cloud Console, trong cùng một dự án mà bạn đã thiết lập cho API Maps JavaScript.

Cách xem danh sách API đã bật:

1. Chuyển đến Google Cloud Console.
2. Nhấp vào nút Chọn dự án, sau đó chọn chính dự án mà bạn đã thiết lập cho API Maps JavaScript rồi nhấp vào Mở.
3. Trong danh sách API trên Trang tổng quan, hãy tìm Distance Matrix API.
4. Nếu thấy API trong danh sách, tức là bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API đó:
   1. Ở đầu trang, hãy chọn BẬT API để hiển thị thẻ Thư viện. Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
   2. Tìm Distance Matrix API, sau đó chọn API đó trong danh sách kết quả.
   3. Chọn BẬT. Khi quá trình này hoàn tất, Distance Matrix API (API ma trận khoảng cách) sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Giá và chính sách

Giá

Kể từ ngày 16 tháng 7 năm 2018, một gói giá mới theo phương thức trả phí khi sử dụng sẽ có hiệu lực đối với Maps, Routes và Places. Để tìm hiểu thêm về mức giá mới và hạn mức sử dụng khi bạn sử dụng dịch vụ Ma trận khoảng cách JavaScript, hãy xem phần Sử dụng và thanh toán cho API Ma trận khoảng cách.

Lưu ý: Mỗi truy vấn được gửi đến dịch vụ Distance Matrix (Bảng khoảng cách) đều bị giới hạn số lượng phần tử được phép, trong đó số lượng điểm xuất phát nhân với số lượng điểm đến xác định số lượng phần tử.

Chính sách

Việc sử dụng dịch vụ Distance Matrix phải tuân thủ các chính sách được mô tả cho Distance Matrix API.

Yêu cầu về Distance Matrix

Việc truy cập vào dịch vụ Ma trận khoảng cách là không đồng bộ, vì API Maps của Google cần thực hiện lệnh gọi đến một máy chủ bên ngoài. Vì lý do đó, bạn cần truyền một phương thức lệnh gọi lại để thực thi sau khi hoàn tất yêu cầu, nhằm xử lý kết quả.

Bạn truy cập vào dịch vụ Distance Matrix trong mã của mình thông qua đối tượng hàm khởi tạo google.maps.DistanceMatrixService. Phương thức DistanceMatrixService.getDistanceMatrix() khởi tạo một yêu cầu đến dịch vụ Distance Matrix (Bảng khoảng cách), truyền cho dịch vụ đó một đối tượng DistanceMatrixRequest cố định chứa điểm xuất phát, điểm đến và phương thức di chuyển, cũng như một phương thức gọi lại để thực thi khi nhận được phản hồi.

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.
}

Xem ví dụ

DistanceMatrixRequest chứa các trường sau:

• origins (bắt buộc) – Một mảng chứa một hoặc nhiều chuỗi địa chỉ, đối tượng google.maps.LatLng hoặc đối tượng Place để tính toán khoảng cách và thời gian.
• destinations (bắt buộc) – Một mảng chứa một hoặc nhiều chuỗi địa chỉ, đối tượng google.maps.LatLng hoặc đối tượng Place để tính khoảng cách và thời gian.
• travelMode (không bắt buộc) – Phương tiện di chuyển cần sử dụng khi tính toán đường đi. Xem phần về phương tiện đi lại.
• transitOptions (không bắt buộc) – Các tuỳ chọn chỉ áp dụng cho các yêu cầu mà travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong phần các lựa chọn đi phương tiện công cộng.
• drivingOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho các yêu cầu mà travelMode là DRIVING. Các giá trị hợp lệ được mô tả trong phần Tuỳ chọn lái xe.
• unitSystem (không bắt buộc) – Hệ đơn vị để sử dụng khi hiển thị khoảng cách. Các giá trị được chấp nhận là:
  • google.maps.UnitSystem.METRIC (mặc định)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (không bắt buộc) – Nếu là true, các tuyến đường giữa điểm xuất phát và điểm đến sẽ được tính toán để tránh xa đường cao tốc nếu có thể.
• avoidTolls (không bắt buộc) – Nếu true, đường đi giữa các điểm sẽ được tính bằng cách sử dụng các tuyến đường không có thu phí, bất cứ khi nào có thể.

Phương tiện đi lại

Khi tính toán thời gian và khoảng cách, bạn có thể chỉ định phương tiện di chuyển sẽ sử dụng. Các phương tiện di chuyển sau đây hiện được hỗ trợ:

• BICYCLING yêu cầu chỉ đường đi xe đạp qua đường dành cho xe đạp và đường ưu tiên (hiện chỉ có ở Hoa Kỳ và một số thành phố ở Canada).
• DRIVING (mặc định) cho biết đường đi tiêu chuẩn bằng ô tô sử dụng mạng lưới đường bộ.
• TRANSIT yêu cầu chỉ đường qua các tuyến phương tiện công cộng. Bạn chỉ có thể chỉ định tuỳ chọn này nếu yêu cầu có chứa khoá API. Hãy xem phần các lựa chọn về phương tiện công cộng để biết các lựa chọn có sẵn trong loại yêu cầu này.
• WALKING yêu cầu chỉ đường đi bộ qua các lối đi bộ và vỉa hè (nếu có).

Phương tiện công cộng

Dịch vụ phương tiện công cộng hiện đang ở giai đoạn "thử nghiệm". Trong giai đoạn này, chúng tôi sẽ triển khai giới hạn tốc độ để ngăn chặn hành vi sử dụng sai mục đích API. Cuối cùng, chúng tôi sẽ áp dụng giới hạn về tổng số truy vấn mỗi lần tải bản đồ dựa trên mức sử dụng hợp lý của API.

Các tuỳ chọn hiện có cho yêu cầu về ma trận khoảng cách sẽ khác nhau tuỳ theo phương thức di chuyển. Trong các yêu cầu chuyển tiếp, các tuỳ chọn avoidHighways và avoidTolls sẽ bị bỏ qua. Bạn có thể chỉ định các tuỳ chọn định tuyến dành riêng cho phương tiện công cộng thông qua giá trị cố định đối tượng TransitOptions.

Yêu cầu chuyển đổi có giới hạn về thời gian. Chỉ có thể trả về kết quả tính toán cho các thời điểm trong tương lai.

Biểu thức cố định đối tượng TransitOptions chứa các trường sau:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Các trường này được giải thích dưới đây:

• arrivalTime (không bắt buộc) chỉ định thời gian đến mong muốn dưới dạng đối tượng Date. Nếu bạn chỉ định thời gian đến, thì thời gian khởi hành sẽ bị bỏ qua.
• departureTime (không bắt buộc) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. departureTime sẽ bị bỏ qua nếu bạn chỉ định arrivalTime. Giá trị mặc định là hiện tại (tức là thời gian hiện tại) nếu không có giá trị nào được chỉ định cho departureTime hoặc arrivalTime.
• modes (không bắt buộc) là một mảng chứa một hoặc nhiều giá trị cố định đối tượng TransitMode. Bạn chỉ có thể đưa trường này vào nếu yêu cầu có chứa khoá API. Mỗi TransitMode chỉ định một phương thức đi lại ưu tiên. Các giá trị sau đây được phép:
  • BUS cho biết rằng tuyến đường được tính toán sẽ ưu tiên đi bằng xe buýt.
  • RAIL cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng tàu, xe điện, tàu điện nhẹ và tàu điện ngầm.
  • SUBWAY cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng tàu điện ngầm.
  • TRAIN cho biết rằng tuyến đường được tính toán sẽ ưu tiên đi bằng tàu.
  • TRAM cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng xe điện và tàu điện.
• routingPreference (không bắt buộc) chỉ định các lựa chọn ưu tiên cho tuyến đường công cộng. Khi sử dụng tuỳ chọn này, bạn có thể thiên vị các tuỳ chọn được trả về thay vì chấp nhận tuyến đường tốt nhất mặc định do API chọn. Bạn chỉ có thể chỉ định trường này nếu yêu cầu có chứa khoá API. Các giá trị sau đây được phép:
  • FEWER_TRANSFERS cho biết tuyến đường được tính toán nên ưu tiên số lượng chuyến chuyển bị giới hạn.
  • LESS_WALKING cho biết tuyến đường được tính toán nên ưu tiên đi bộ ở mức hạn chế.

Các lựa chọn khi lái xe

Sử dụng đối tượng drivingOptions để chỉ định thời gian khởi hành nhằm tính toán tuyến đường tốt nhất đến đích của bạn dựa trên tình trạng giao thông dự kiến. Bạn cũng có thể chỉ định xem bạn muốn thời gian ước tính trong tình trạng giao thông là bi quan, lạc quan hay ước tính tốt nhất dựa trên tình trạng giao thông trước đây và tình trạng giao thông trực tiếp.

Đối tượng drivingOptions chứa các trường sau:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Các trường này được giải thích dưới đây:

• departureTime (bắt buộc đối với đối tượng cố định drivingOptions) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. Bạn phải đặt giá trị thành thời gian hiện tại hoặc một thời điểm trong tương lai. Ngày này không được là ngày trong quá khứ. (API chuyển đổi tất cả ngày thành UTC để đảm bảo việc xử lý nhất quán trên các múi giờ.) Nếu bạn đưa departureTime vào yêu cầu, API sẽ trả về tuyến đường tốt nhất dựa trên tình trạng giao thông dự kiến tại thời điểm đó và bao gồm thời gian dự đoán trong giao thông (duration_in_traffic) trong phản hồi. Nếu bạn không chỉ định thời gian khởi hành (tức là nếu yêu cầu không bao gồm drivingOptions), thì tuyến đường được trả về thường là tuyến đường tốt mà không tính đến tình trạng giao thông.
• trafficModel (không bắt buộc) chỉ định các giả định cần sử dụng khi tính thời gian trong lưu lượng truy cập. Chế độ cài đặt này ảnh hưởng đến giá trị được trả về trong trường duration_in_traffic trong phản hồi, chứa thời gian dự đoán trong lưu lượng truy cập dựa trên mức trung bình trước đây. Giá trị mặc định là best_guess. Các giá trị sau đây được phép:
  • bestguess (mặc định) cho biết rằng duration_in_traffic được trả về phải là thời gian di chuyển ước tính tốt nhất dựa trên những gì đã biết về cả tình trạng giao thông trước đây và giao thông hiện tại. Lưu lượng truy cập trực tiếp càng quan trọng khi departureTime càng gần thời điểm hiện tại.
  • pessimistic cho biết rằng duration_in_traffic được trả về phải dài hơn thời gian di chuyển thực tế vào hầu hết các ngày, mặc dù đôi khi những ngày có điều kiện giao thông đặc biệt xấu có thể vượt quá giá trị này.
  • optimistic cho biết rằng duration_in_traffic được trả về phải ngắn hơn thời gian di chuyển thực tế vào hầu hết các ngày, mặc dù đôi khi vào những ngày có điều kiện giao thông đặc biệt tốt, thời gian di chuyển có thể nhanh hơn giá trị này.

Dưới đây là DistanceMatrixRequest mẫu cho các tuyến đường lái xe, bao gồm thời gian khởi hành và mô hình giao thông:

{
  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'
  }
}

Phản hồi của Distance Matrix

Lệnh gọi thành công đến dịch vụ Distance Matrix (Mảng khoảng cách) sẽ trả về một đối tượng DistanceMatrixResponse và một đối tượng DistanceMatrixStatus. Các giá trị này được truyền đến hàm callback mà bạn đã chỉ định trong yêu cầu.

Đối tượng DistanceMatrixResponse chứa thông tin về quãng đường và thời lượng cho mỗi cặp điểm xuất phát/điểm đến mà bạn có thể tính toán tuyến đường.

{
  "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"
      }
    } ]
  } ]
}

Kết quả của Distance Matrix

Các trường được hỗ trợ trong phản hồi được giải thích bên dưới.

• originAddresses là một mảng chứa các vị trí được truyền trong trường origins của yêu cầu Bảng khoảng cách. Địa chỉ được trả về theo định dạng của trình mã hoá địa lý.
• destinationAddresses là một mảng chứa các vị trí được truyền vào trường destinations, ở định dạng do trình mã hoá địa lý trả về.
• rows là một mảng các đối tượng DistanceMatrixResponseRow, trong đó mỗi hàng tương ứng với một nguồn gốc.
• elements là phần tử con của rows và tương ứng với một cặp nguồn gốc của hàng với mỗi đích đến. Các tuyến đường này chứa thông tin về trạng thái, thời lượng, quãng đường và giá vé (nếu có) cho từng cặp điểm xuất phát/điểm đến.
• Mỗi element chứa các trường sau:
  • status: Xem phần Mã trạng thái để biết danh sách các mã trạng thái có thể có.
  • duration: Khoảng thời gian cần thiết để đi theo tuyến đường này, được biểu thị bằng giây (trường value) và dưới dạng text. Giá trị văn bản được định dạng theo unitSystem được chỉ định trong yêu cầu (hoặc theo đơn vị đo lường, nếu không có lựa chọn ưu tiên nào được cung cấp).
  • duration_in_traffic: Khoảng thời gian cần thiết để đi theo tuyến đường này, có tính đến tình trạng giao thông hiện tại, được biểu thị bằng giây (trường value) và dưới dạng text. Giá trị văn bản được định dạng theo unitSystem được chỉ định trong yêu cầu (hoặc theo đơn vị đo lường, nếu không có lựa chọn ưu tiên nào được cung cấp). duration_in_traffic chỉ được trả về khi có dữ liệu lưu lượng truy cập, mode được đặt thành driving và departureTime được đưa vào trường distanceMatrixOptions trong yêu cầu.
  • distance: Tổng quãng đường của tuyến đường này, được biểu thị bằng mét (value) và dưới dạng text. Giá trị văn bản được định dạng theo unitSystem được chỉ định trong yêu cầu (hoặc theo đơn vị đo lường, nếu không có lựa chọn ưu tiên nào được cung cấp).
  • fare: Chứa tổng giá vé (tức là tổng chi phí vé) trên tuyến đường này. Thuộc tính này chỉ được trả về cho các yêu cầu đi phương tiện công cộng và chỉ dành cho các nhà cung cấp phương tiện công cộng có thông tin về giá vé. Thông tin này bao gồm:
    • currency: Mã đơn vị tiền tệ theo tiêu chuẩn ISO 4217 cho biết đơn vị tiền tệ mà số tiền được thể hiện.
    • value: Tổng số tiền vé, tính bằng đơn vị tiền tệ được chỉ định ở trên.

Mã trạng thái

Phản hồi của Distance Matrix bao gồm một mã trạng thái cho toàn bộ phản hồi, cũng như trạng thái cho từng phần tử.

Mã trạng thái phản hồi

Các mã trạng thái áp dụng cho DistanceMatrixResponse được truyền trong đối tượng DistanceMatrixStatus và bao gồm:

• OK – Yêu cầu hợp lệ. Hệ thống có thể trả về trạng thái này ngay cả khi không tìm thấy tuyến đường nào giữa điểm xuất phát và điểm đến. Xem Mã trạng thái phần tử để biết thông tin trạng thái cấp phần tử.
• INVALID_REQUEST – Yêu cầu được cung cấp không hợp lệ. Điều này thường là do thiếu các trường bắt buộc. Xem danh sách các trường được hỗ trợ ở trên.
• MAX_ELEMENTS_EXCEEDED – Sản phẩm của nguồn gốc và đích đến vượt quá giới hạn trên mỗi truy vấn.
• MAX_DIMENSIONS_EXCEEDED – Yêu cầu của bạn chứa nhiều hơn 25 nguồn gốc hoặc nhiều hơn 25 đích đến.
• OVER_QUERY_LIMIT – Ứng dụng của bạn đã yêu cầu quá nhiều phần tử trong khoảng thời gian được phép. Yêu cầu sẽ thành công nếu bạn thử lại sau một khoảng thời gian hợp lý.
• REQUEST_DENIED – Dịch vụ từ chối việc trang web của bạn sử dụng dịch vụ Ma trận khoảng cách.
• UNKNOWN_ERROR – Không thể xử lý yêu cầu về Ma trận khoảng cách do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.

Mã trạng thái phần tử

Các mã trạng thái sau đây áp dụng cho các đối tượng DistanceMatrixElement cụ thể:

• NOT_FOUND – Không thể mã hoá địa lý điểm xuất phát và/hoặc điểm đến của cặp này.
• OK – Phản hồi chứa kết quả hợp lệ.
• ZERO_RESULTS – Không tìm thấy tuyến đường giữa điểm khởi hành và điểm đến.

Phân tích cú pháp kết quả

Đối tượng DistanceMatrixResponse chứa một row cho mỗi nguồn gốc được truyền trong yêu cầu. Mỗi hàng chứa một trường element cho mỗi cặp nguồn gốc đó với(các) đích đến được cung cấp.

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];
      }
    }
  }
}