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

Tổng quan

Dịch vụ Ma trận khoảng cách của Google tính toán khoảng cách và quãng đường di chuyển giữa nhiều điểm xuất phát và điểm đến bằng một phương thức di chuyển nhất định.

Dịch vụ này không trả về thông tin tuyến đường chi tiết. Bạn có thể lấy thông tin về tuyến đường (bao gồm cả nhiều đường và văn bản) bằng cách chuyển nguồn gốc 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 JavaScript cho Maps, 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 bạn thiết lập cho API JavaScript của Maps.

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

  1. Truy cập vào Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn dự án mà bạn đã thiết lập cho API JavaScript cho Maps và nhấp vào Mở.
  3. Trong danh sách API trên Trang tổng quan, hãy tìm API Ma trận khoảng cách.
  4. Nếu thấy API trong danh sách thì 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 ENABLE API (BẬT API) để hiện thẻ Library (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 API ma trận khoảng cách, sau đó chọn API đó từ danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này kết thúc, API ma trận khoảng cách sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Mức giá và các chính sách

Giá

Có hiệu lực từ ngày 16 tháng 7 năm 2018, kế hoạch trả tiền theo mức giá mới có hiệu lực đối với Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về hạn mức giá và mức sử dụng mới cho việc sử dụng dịch vụ Ma trận khoảng cách JavaScript, hãy xem phần Mức 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ụ Ma trận khoảng cách bị giới hạn bởi số lượng phần tử được phép, trong đó số lượng nguồn gốc nhân với số lượng đích xác định số lượng phần tử.

Chính sách

Việc sử dụng dịch vụ Ma trận khoảng cách phải tuân theo các chính sách được mô tả cho API Ma trận khoảng cách.

Yêu cầu ma trận khoảng cách

Việc truy cập dịch vụ Ma trận khoảng cách không đồng bộ vì API Google Maps cần thực hiện lệnh gọi đến một máy chủ bên ngoài. 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ụ Ma trận khoảng cách 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() sẽ bắt đầu yêu cầu đến dịch vụ Ma trận khoảng cách, chuyển yêu cầu đó là một đối tượng DistanceMatrixRequest chứa nguồn gốc, đích đến và chế độ di chuyển, cũng như 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 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 thức di chuyển để sử dụng khi tính toán đường đi. Hãy xem mục về phương tiện đi lại.
  • transitOptions (không bắt buộc) – Các tùy chọn chỉ áp dụng cho những yêu cầu có travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong phần về các tùy chọn 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 có travelMode là DRIVING. Các giá trị hợp lệ được mô tả trong phần về Tuỳ chọn lái xe.
  • unitSystem (không bắt buộc) — Hệ thống đơ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 true, các tuyến đường giữa điểm khởi hành và điểm đến sẽ được tính toán để tránh đường cao tốc nếu có thể.
  • avoidTolls (không bắt buộc) — Nếu true, thì đường đi giữa các điểm sẽ được tính toán bằng tuyến đường không tính phí (nếu có thể).

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

Khi tính thời gian và khoảng cách, bạn có thể chỉ định phương tiện đi lại để sử dụng. Hiện chúng tôi đã hỗ trợ các phương tiện đi lại sau đây:

  • BICYCLING yêu cầu chỉ đường đi xe đạp qua đường dành cho xe đạp và các đường phố ưa thích (hiện chỉ có tại Hoa Kỳ và một số thành phố của Canada).
  • DRIVING (mặc định) cho biết đường lái xe tiêu chuẩn bằng mạng lưới đường bộ.
  • TRANSIT yêu cầu chỉ đường thông qua các tuyến đường phương tiện công cộng. Bạn chỉ có thể chỉ định tùy chọn này nếu yêu cầu có chứa khóa API. Hãy xem phần về các lựa chọn 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 đường đi bộ và vỉa hè (nếu có).

Tùy chọn phương tiện công cộng

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

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

Yêu cầu về phương tiện công cộng có tính chất khẩn cấp. Các phép tính sẽ chỉ được trả về cho các thời điểm trong tương lai.

Hằng đối tượng TransitOptions chứa các trường sau:

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

Những 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 dự kiế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à bây giờ (nghĩa là thời gian hiện tại) nếu bạn chưa chỉ định giá trị nào 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. Trường này chỉ có thể được đưa vào nếu yêu cầu có chứa khóa API. Mỗi TransitMode chỉ định một phương thức di chuyển ưa thích. Các giá trị sau được phép:
    • BUS cho biết tuyến đường được tính toán nên ưu tiên đi xe buýt.
    • RAIL cho biết tuyến đường được tính toán này nên ưu tiên đi tàu hỏa, xe điện, tàu điện và tàu điện ngầm.
    • SUBWAY cho biết tuyến đường được tính toán nên ưu tiên đi tàu điện ngầm.
    • TRAIN cho biết tuyến đường được tính toán nên ưu tiên đi tàu hỏa.
    • TRAM cho biết 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 tùy chọn cho tuyến đường bằng phương tiện công cộng. Khi sử dụng tùy chọn này, bạn có thể ưu tiên các tùy chọn được trả về thay vì chấp nhận tuyến tốt nhất mặc định mà API chọn. Trường này chỉ có thể được chỉ định nếu yêu cầu có chứa khóa API. Các giá trị sau được phép:
    • FEWER_TRANSFERS cho biết tuyến đường được tính toán nên có số lần chuyển ít hơn.
    • LESS_WALKING cho biết tuyến đường đã tính toán nên có chỉ số đi bộ hạn chế.

Tùy chọn lái xe

Sử dụng đối tượng drivingOptions để chỉ định thời gian khởi hành để tính toán tuyến đường tốt nhất tới điểm đến 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 lưu lượng truy cập ước tính mang tính bi quan, lạc quan hay ước tính chính xác nhất dựa trên điều kiện lưu lượng truy cập trong quá khứ và lưu lượng truy cập trực tiếp.

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTime (bắt buộc để giá trị cố định của đối tượng drivingOptions hợp lệ) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. Giá trị này phải được đặt thành thời điểm hiện tại hoặc một thời điểm trong tương lai. Không được là ngày trong quá khứ. (API chuyển đổi tất cả các ngày thành UTC để đảm bảo việc xử lý nhất quán theo các múi giờ.) Nếu bạn đưa departureTime vào yêu cầu, thì API sẽ trả về tuyến đường tốt nhất dựa trên điều kiện lưu lượng truy cập dự kiến tại thời điểm đó, và bao gồm thời gian dự đoán trong lưu lượng truy cập (duration_in_traffic) trong phản hồi. Nếu bạn không chỉ định thời gian khởi hành (nghĩa 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 điều kiện giao thông.

    Lưu ý: Nếu bạn không xác định thời gian khởi hành, thì việc chọn tuyến đường và thời lượng sẽ dựa trên mạng lưới đường bộ và tình trạng giao thông trung bình không phụ thuộc vào thời gian. Kết quả cho một yêu cầu nhất định có thể thay đổi theo thời gian do những thay đổi trong mạng đường, điều kiện giao thông trung bình cập nhật và bản chất phân phối của dịch vụ. Kết quả cũng có thể khác nhau giữa các tuyến đường gần tương đương tại bất kỳ thời điểm hoặc tần suất nào.

  • trafficModel (không bắt buộc) chỉ định các giả định sẽ được sử dụng khi tính toán thời gian 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. Giá trị này chứa thời gian dự kiế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 được phép:
    • bestguess (mặc định) cho biết duration_in_traffic được trả về phải là ước tính thời gian di chuyển chính xác nhất dựa trên những gì đã biết về cả tình trạng giao thông trước đây và lưu lượng truy cập trực tiếp. Lưu lượng truy cập trực tiếp trở nên quan trọng hơn khi departureTime đến gần hơn.
    • 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 kém 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 những ngày có điều kiện giao thông đặc biệt tốt có thể nhanh hơn giá trị này.

Dưới đây là mẫu DistanceMatrixRequest 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 ma trận khoảng cách

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

Đối tượng DistanceMatrixResponse chứa thông tin khoảng cách và thời lượng cho mỗi cặp điểm xuất phát/đích 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ả ma trận khoảng cách

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

  • originAddresses là một mảng chứa các vị trí được truyền vào trường origins của yêu cầu Ma trận khoảng cách. Các địa chỉ được trả về vì chúng được định dạng bằng bộ mã hóa địa lý.
  • destinationAddresses là một mảng chứa các vị trí được chuyển vào trường destinations, ở định dạng do bộ mã hoá mã trả về.
  • rows là một mảng các đối tượng DistanceMatrixResponseRow, 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 cách ghép nối nguồn gốc của hàng với mỗi đích. Các thông tin này chứa trạng thái, thời lượng, khoảng cách và giá vé (nếu có) cho mỗi cặp điểm xuất phát/đích đến.
  • Mỗi element chứa các trường sau:
    • status: Xem Mã trạng thái để biết danh sách các mã trạng thái.
    • duration: Khoảng thời gian cần thiết để di chuyển 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 chỉ số, 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 đến tuyến đường này, có tính đến điều kiện 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 chỉ số, 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ề cho khách hàng sử dụng Gói cao cấp của Nền tảng Google Maps, trong đó có dữ liệu giao thông, mode được đặt thành driving và departureTime nằm trong trường distanceMatrixOptions trong yêu cầu.
    • distance: Tổng khoảng cách 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 chỉ số, 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ổng giá vé) của chặng bay này. Thuộc tính này chỉ được trả về cho các yêu cầu về phương tiện công cộng và chỉ dành cho những 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 ISO 4217 cho biết đơn vị tiền tệ mà số tiền được thể hiện.
      • value: Tổng số tiền giá vé, theo đơn vị tiền tệ nêu trên.

Mã trạng thái

Phản hồi ma trận khoảng cách 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

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 là hợp lệ. Trạng thái này có thể được trả về ngay cả khi không có tuyến đường nào được tìm thấy giữa bất kỳ điểm khởi hành và điểm đến nào. Hãy xem bài viết Mã trạng thái phần tử để biết thông tin về trạng thái cấp phần tử.
  • INVALID_REQUEST — Yêu cầu đã 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. Hãy xem danh sách các trường được hỗ trợ ở trên.
  • MAX_ELEMENTS_EXCEEDED – Sản phẩm của các nguồn gốc và đích đến vượt quá giới hạn cho mỗi truy vấn.
  • MAX_DIMENSIONS_EXCEEDED – Yêu cầu của bạn chứa hơn 25 nguồn gốc hoặc 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 cho 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ụ của bạn đã từ chối sử dụng dịch vụ Ma trận khoảng cách.
  • UNKNOWN_ERROR – Không thể xử lý yêu cầu 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ý nguồn gốc và/hoặc đích đến của cặp ghé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 nào 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 đã đượ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];
      }
    }
  }
}