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 di chuyển khoảng cách và thời gian hành trình giữa nhiều điểm xuất phát và điểm đến thông qua một phương thức đi lại nhất định.

Dịch vụ này không trả về thông tin tuyến đường chi tiết. Thông tin tuyến đường, bao gồm hình nhiều đường và hướng dẫn bằng văn bản, có thể lấy được bằng cách truyền phương thức điểm khởi hành và điểm đến mong muố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 Maps JavaScript API, trước tiên, hãy đảm bảo rằng bạn đã bật Distance Matrix API (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 Maps JavaScript API.

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

1. Chuyển đến Bảng điều khiển Google Cloud.
2. Nhấp vào nút Select a project (Chọn dự án), rồi 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 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, bật:
   1. Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị Thẻ Thư viện. Ngoài ra, từ trình đơn bên trái, hãy chọn Thư viện.
   2. Tìm Distance Matrix API (API Ma trận khoảng cách), rồi chọn API đó khỏi 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 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, gói giá mới trả tiền theo mức dùng đã bắt đầu áp dụng cho Bản đồ, Tuyến đường và Địa điểm. Để tìm hiểu thêm về mức giá mới và hạn mức sử dụng cho việc sử dụng dịch vụ Ma trận khoảng cách JavaScript, xem Việc sử dụng và thanh toán cho API Ma trận khoảng cách.

Lưu ý: Mỗi truy vấn gửi đến dịch vụ Ma trận khoảng cách sẽ bị giới hạn theo số lượng phần tử được phép, trong đó số nguồn gốc nhân với số số lượng đích đến 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 thủ các chính sách nêu trên 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 là không đồng bộ, vì API Maps cần thực hiện lệnh gọi đến máy chủ bên ngoài. Vì lý do đó, bạn cần truyền phương thức callback để thực thi sau khi hoàn thành để 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() bắt đầu yêu cầu đến dịch vụ Ma trận khoảng cách, truyền nó Đối tượng DistanceMatrixRequest chứa các nguồn gốc, điểm đến và phương thức đi lại, cũng như phương pháp gọi lại để thực thi 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 Địa điểm để 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 các chuỗi địa chỉ khác, đối tượng google.maps.LatLng hoặc Địa điểm để tính khoảng cách và thời gian.
• travelMode (không bắt buộc) — Chế độ của phương tiện giao thông công cộng để sử dụng khi tính toán chỉ đường. Xem phần này trên phương tiện đi lại.
• transitOptions (không bắt buộc) — Tuỳ chọn chỉ áp dụng cho các yêu cầu trong đó travelMode TRANSIT. Có mô tả các giá trị hợp lệ trong mục về các 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 trong đó travelMode DRIVING. Có mô tả các giá trị hợp lệ trong phần về Tùy chọn lái xe.
• unitSystem (không bắt buộc) – Hệ thống đơn vị để 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 giữa điểm gốc và đích đến sẽ là để tránh đường cao tốc khi có thể.
• avoidTolls (không bắt buộc) – Nếu true, chỉ đường giữa các điểm sẽ được tính bằng cách sử dụng các tuyến đường không 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 loại phương tiện giao thông cần sử dụng. Chuyến du lịch sau đây các chế độ hiện được hỗ trợ:

• BICYCLING yêu cầu chỉ đường đi xe đạp qua đường dành cho xe đạp & đường phố ưa thích (hiện chỉ có ở Hoa Kỳ và một số thành phố của Canada).
• DRIVING (mặc định) biểu thị chỉ đường lái xe tiêu chuẩn bằng cách sử dụng mạng lưới đường.
• TRANSIT yêu cầu chỉ đường qua tuyến đường phương tiện công cộng. Bạn chỉ có thể chỉ định lựa chọn này nếu yêu cầu có khoá API. Xem phần phương tiện công cộng để có 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 dành cho người đi bộ & 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 ở trạng thái 'thử nghiệm'. Trong giai đoạn này , chúng tôi sẽ triển khai giới hạn số lượng yêu cầu để ngăn chặn hành vi sử dụng API sai mục đích. Chúng tôi sẽ cuối cùng sẽ áp dụng giới hạn cho tổng số truy vấn cho mỗi lượt tải bản đồ dựa trên việc sử dụng hợp lý API.

Các lựa chọn có sẵn cho yêu cầu ma trận khoảng cách sẽ khác nhau tuỳ theo phương tiện đi lại. Trong yêu cầu vận chuyển, avoidHighways và Bỏ qua avoidTolls tuỳ chọn. 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 TransitOptions giá trị của đối tượng.

Yêu cầu về phương tiện công cộng có giới hạn thời gian. Kết quả tính toán sẽ chỉ được trả về cho lần trong tương lai.

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

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

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

• arrivalTime (không bắt buộc) chỉ định thông số mong muốn thời gian đến dưới dạng đối tượng Date. Nếu thời gian đến là đã chỉ định, thời gian khởi hành sẽ bị bỏ qua.
• departureTime (không bắt buộc) chỉ định thông số mong muốn thời gian khởi hành dưới dạng đối tượng Date. Chiến lược phát hành đĩa đơn departureTime sẽ bị bỏ qua nếu arrivalTime được chỉ định. Mặc định là bây giờ (tức là thời gian hiện tại) nếu không có giá trị nào là đượ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 các giá trị cố định khác của đối tượng TransitMode. Trường này chỉ có thể nếu yêu cầu có chứa khoá API. Mỗi TransitMode chỉ định phương thức di chuyển ưu tiên. Bạn có thể sử dụng các giá trị sau:
  • BUS cho biết rằng tuyến đường được tính toán nên ư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 hoả, xe điện, tàu điện 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 di chuyển bằng tàu điện ngầm.
  • TRAIN cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng tàu hoả.
  • 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 các tuyến đường phương tiện. Khi sử dụng tuỳ chọn này, bạn có thể làm sai lệch 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 bao gồm Khoá API. Bạn có thể sử dụng các giá trị sau:
  • FEWER_TRANSFERS cho biết rằng tuyến đường được tính toán sẽ ưu tiên số lượng chuyển cuộc gọi.
  • LESS_WALKING chỉ ra rằng tuyến đường được tính toán nên ưu tiên số lượng đi bộ.

Lựa chọn lái xe

Sử dụng đối tượng drivingOptions để chỉ định thời gian khởi hành cho tính toán tuyến đường tốt nhất tới điểm đến của bạn dựa trên điều kiện giao thông dự kiến. Bạn có thể cũng cho biết liệu bạn muốn thời gian lưu lượng truy cập ước tính là bi quan, lạc quan hay số liệu ước tính chính xác nhất dựa trên tình trạng giao thông trước đây và 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 bên dưới:

• departureTime (bắt buộc cho Đối tượng drivingOptions là hợp lệ) chỉ định thời điểm khởi hành mong muốn dưới dạng đối tượng Date. Giá trị phải là đặt thành thời gian hiện tại hoặc thời điểm nào đó trong tương lai. Quảng cáo không được nằm trong quá khứ. (API chuyển đổi tất cả các ngày sang giờ UTC để đảm bảo quy trình xử lý nhất quán theo 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 khi tham gia giao thông (duration_in_traffic) trong câu trả lờ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), tuyến được trả về thường là tuyến đường tốt mà không cần tính đến tình trạng giao thông.
• trafficModel (không bắt buộc) chỉ định các giả định cho dùng khi tính toán thời gian tham gia giao thông. 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 lưu lượng truy cập dự đoán dựa trên mức trung bình trước đây. Giá trị mặc định là best_guess. Bạn có thể sử dụng các giá trị sau:
  • bestguess (mặc định) cho biết hàm được trả về duration_in_traffic phải là số liệu ước tính chính xác nhất về thời gian di chuyển dựa trên thông tin đã 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. Giao thông trực tiếp trở nên quan trọng hơn, departureTime đến thời điểm hiện tại..
  • pessimistic cho biết hàm được trả về duration_in_traffic phải dài hơn quãng đường thực tế thời gian vào hầu hết các ngày, mặc dù đôi khi có lưu lượng truy cập đặc biệt kém điều kiện có thể vượt quá giá trị này.
  • optimistic cho biết hàm được trả về duration_in_traffic phải ngắn hơn kích thước thực tế thời gian đi lại vào hầu hết các ngày, mặc dù thỉnh thoảng những ngày có thời gian đặc biệt tốt tình trạng giao thông 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 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ề một giá trị Đối tượng DistanceMatrixResponse và một Đối tượng DistanceMatrixStatus. Các hàm này được chuyển đến lệnh gọi lại mà bạn đã chỉ định trong yêu cầu.

Đối tượng DistanceMatrixResponse chứa khoảng cách và thông tin về thời lượng của mỗi cặp điểm khởi hành/điểm đến mà một tuyến đường có thể được tính toán.

{
  "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 câu trả lờ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 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ề khi chúng được định dạng bằng bộ mã hoá địa lý.
• destinationAddresses là một mảng chứa các vị trí được chuyển vào trường destinations, theo định dạng được bộ mã hoá địa lý trả về.
• rows là một mảng DistanceMatrixResponseRow các đối tượng, với 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 thành một cặp điểm gốc của hàng với từng đích đến. Chúng chứa thông tin về trạng thái, thời gian bay, quãng đường và giá vé (nếu có) cho mỗi chuyến đi cặp điểm khởi hành/đích.
• Mỗi element chứa các trường sau:
  • status: Xem Mã trạng thái cho danh sách các mã trạng thái có thể có.
  • duration: Khoảng thời gian cần thiết để đi tuyến đường, đượ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 trong chỉ số, nếu không có tùy chọn đã được cung cấp).
  • duration_in_traffic: Khoảng thời gian cần thiết để đi theo tuyến đường này khi xét đế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 trong chỉ số, nếu không có tùy chọn đã được cung cấp). Chiến lược phát hành đĩa đơn 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ó 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ị dạng 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ức là tổng cộng chi phí vé) trên chặng bay này. Cơ sở lưu trú này chỉ được trả về để vận chuyển và chỉ dành cho các nhà cung cấp phương tiện công cộng có thông tin giá vé sẵn có. Thông tin này bao gồm:
    • currency: Một Đơn vị tiền tệ theo ISO 4217 mã cho biết đơn vị tiền tệ mà số tiền được dùng.
    • value: Tổng giá vé, theo đơn vị tiền tệ được chỉ định ở trên.

Mã trạng thái

Phản hồi của Ma trận khoảng cách bao gồm một mã trạng thái cho phản hồi dưới dạng một toàn bộ cũng như trạng thái cho mỗi phần tử.

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

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

• OK — Yêu cầu hợp lệ. Trạng thái này có thể là trả về ngay cả khi không tìm thấy tuyến nào giữa mọi nguồn gốc và đích đến. Xem phần Thành phần Mã trạng thái cho thông tin trạng thái ở cấp phần tử.
• INVALID_REQUEST — Yêu cầu đã cung cấp là không hợp lệ. Điều này thường xảy ra 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 — Tích của 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 thêm nội dung khác hơn 25 nguồn gốc, hoặc nhiều hơn 25 điểm đến.
• OVER_QUERY_LIMIT — Đơn đăng ký của bạn đã yêu cầu có quá nhiều phần tử trong khoảng thời gian cho phép. Yêu cầu phải 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ụ bị từ chối sử dụng Dịch vụ Ma trận khoảng cách theo trang web của bạn.
• UNKNOWN_ERROR — Yêu cầu Ma trận khoảng cách không thể được xử lý do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử một lần nữa.

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

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

• NOT_FOUND – Nguồn gốc và/hoặc đích đến của nội dung này ghép nối không thể được mã hoá địa lý.
• 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 gốc được truyền trong yêu cầu. Mỗi hàng chứa trường element cho mỗi cặp nguồn gốc đó với (các) điểm đế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];
      }
    }
  }
}