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 quãng đường và thời gian hành trình 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 chi tiết về tuyến đường. Bạn có thể lấy thông tin tuyến đường, bao gồm cả hình nhiều đường và chỉ đường bằng văn bản bằng cách truyền một điểm 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 của Maps, trước tiên, hãy nhớ bật API ma trận khoảng cách trong Google Cloud Console, trong cùng dự án bạn thiết lập cho API JavaScript của Maps.

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

  1. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn chính dự án mà bạn đã thiết lập cho Maps JavaScript API rồi nhấp vào Open (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 này 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ị 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 kiếm Distance Matrix API (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.

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 có hiệu lực đối với Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về mức giá mới và giới hạn sử dụng khi 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ụ 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ố gốc nhân với số đí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 đượ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 là 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 phương thức callback để thực thi sau khi hoàn tất yêu cầu, nhằm xử lý kết quả.

Bạn có thể 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 một yêu cầu đến dịch vụ Ma trận khoảng cách, truyền cho dịch vụ đó một giá trị cố định của đối tượng DistanceMatrixRequest chứa điểm gốc, điểm đế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 (Địa điểm) để tính khoảng cách và thời gian từ đó.
  • 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 (Địa điểm) để tính khoảng cách và thời gian.
  • travelMode (không bắt buộc) – Phương thức vận tải sử dụng khi tính toán đường đi. Hãy xem nội dung về chế độ đ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 có travelModeTRANSIT. Các giá trị hợp lệ được mô tả trong phần về tuỳ 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ó travelModeDRIVING. 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ệ 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 là true, các tuyến đường giữa điểm xuất phát và đích đế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 là true, đường đi giữa các điểm sẽ được tính toán 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 thời gian và khoảng cách, bạn có thể chỉ định phương thức di chuyển sẽ sử dụng. Hiện chúng tôi hỗ trợ các chế độ đi lại sau đây:

  • BICYCLING yêu cầu chỉ đường 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ố của Canada).
  • DRIVING (mặc định) biểu thị thông tin đườ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 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ó khoá API. Vui lòng xem mục các cách thức phương tiện công cộng để biết các lựa chọn có 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à vỉa hè (nếu có).

Lựa chọn cho phương tiện công cộng

Dịch vụ phương tiện công cộng 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. Cuối cùng, chúng tôi sẽ áp dụng giới hạn cho tổng số lượt truy vấn cho mỗi lượt tải bản đồ dựa trên cách sử dụng hợp lý API.

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

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

Đối tượng cố định 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ờ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ể sử dụng trường này nếu yêu cầu có khoá API. Mỗi TransitMode chỉ định một phương thức chuyển tuyế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 đã tính toán nên ưu tiên đi bằng xe buýt.
    • RAIL cho biết rằng tuyến đường đã 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 đã 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 đã tính toán nên ưu tiên đi bằng tàu hoả.
    • TRAM cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng xe điện và xe đ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 chuyển tuyế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 mặc định tốt nhất mà API đã chọn. Bạn chỉ có thể chỉ định trường này nếu yêu cầu có khoá API. Bạn có thể sử dụng các giá trị sau:
    • FEWER_TRANSFERS cho biết tuyến đã tính toán nên có số lượt chuyển hạn chế.
    • LESS_WALKING cho biết rằng tuyến đường đã tính toán nên ưu tiên số lượng đi bộ hạn chế.

Tuỳ chọn lái xe

Hãy 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 tới điểm đến của bạn trong điều kiện 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 là bi quan, lạc quan hay ước tính phù hợp nhất dựa trên điều kiện giao thông trước đây 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
}

Các 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 phải hợp lệ) 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ị này thành thời điểm hiện tại hoặc một thời điểm nào đó trong tương lai. Ngày đó không được ở trong quá khứ. (API chuyển đổi tất cả các ngày sang giờ UTC để đảm bảo xử lý nhất quán giữa 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 giao thông dự kiến tại thời điểm đó và đưa thời gian lưu lượng truy cập dự đoán (duration_in_traffic) vào 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 trả về sẽ là tuyến đường thường phù hợp 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 tham gia 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 giá trị 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 rằng duration_in_traffic được trả về phải là thông tin ước tính chính xác nhất về thời gian di chuyển, dựa trên những 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 càng gần với departureTime 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ế trong hầu hết các ngày, mặc dù thỉnh thoảng những ngày có tình trạng 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ế trong hầu hết các ngày, mặc dù một số 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à DistanceMatrixRequest mẫu cho các tuyến đường lái xe, bao gồm cả 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 trong 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 đối tượng DistanceMatrixResponse và một đối tượng DistanceMatrixStatus. Các toán tử này sẽ được truyền đến hàm gọi lại mà bạn đã chỉ định trong yêu cầu.

Đối tượng DistanceMatrixResponse chứa thông tin về khoảng cách và thời lượng cho mỗi cặp điểm xuất phát/đ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 phản hồi đượ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ề theo đúng định dạng của 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, ở định dạng được bộ 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 điểm gốc của hàng với từng đích đến. Các thông tin này chứa thông tin về trạng thái, thời gian bay, quãng đường và giá vé (nếu có) của từng cặp điểm xuất phát/điểm đến.
  • Mỗi element chứa các trường sau:
    • status: Hãy xem Mã trạng thái để biết danh sách các mã trạng thái có thể có.
    • duration: Thời gian cần thiết để đi theo tuyến 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 cung cấp lựa chọn ưu tiên nào).
    • duration_in_traffic: Thời gian đi qua 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 chỉ số, nếu không cung cấp lựa chọn ưu tiên nào). duration_in_traffic chỉ được trả về cho những khách hàng sử dụng Gói Google Maps cao cấp khi có dữ liệu giao thông, mode được đặt thành drivingdepartureTime đượ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 trong 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 chi phí vé) trên chặng bay này. Cơ sở lưu trú này chỉ được trả về cho các yêu cầu về phương tiện công cộng và chỉ cho các nhà cung cấp dịch vụ phương tiện công cộng có thông tin về giá vé. Trong đó có:
      • 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 bằng đơn vị tiền tệ đó.
      • value: Tổng số tiền 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 toàn bộ phản hồi, cũng như trạng thái của từng phần tử.

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

Mã trạng thái áp dụng cho DistanceMatrixResponse sẽ đượ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ể được trả về ngay cả khi không tìm thấy tuyến nào giữa bất kỳ nguồn gốc và đích đến nào. Xem 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 đượ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 trường được hỗ trợ ở trên.
  • MAX_ELEMENTS_EXCEEDED – Tích 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ụ từ chối 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 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ử

Những 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 gốc và/hoặc điểm đến của quá trình ghép nối này.
  • OK – Phản hồi chứa một 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à đích đế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 ghép nối nguồn gốc đó với(các) đích đến đã cho.

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