Distance Matrix APIs

API Distance Matrix đem lại cho ứng dụng của bạn khả năng tính toán khoảng cách và thời gian giữa một cặp tọa độ và trả về cho bạn bảng kết quả ma trận.

mẹo

Hãy sử dụng Enterprise Dashboard hoặc hướng dẫn API Key để tạo API Key và trải nghiệm miễn phí!

Base URL

Mã URL chung cho tất các yêu cầu API: https://mapapis.openmap.vn/v1

API Distance Matrix

API Distance matrix sử dụng các điểm xuất phát sources và điểm đến targets để liệt kê các vị trí. Điều này cho phép bạn thiết lập các vị trí xuất phát (origin) tách biệt với các vị trí đích (destination). Tập hợp các điểm xuất phát có thể không trùng lặp với tập hợp các điểm đến. Có thể hiểu, các vị trí đích không nhất thiết phải bao gồm bất kỳ vị trí nào từ các điểm xuất phát. API này cho phép trả về ma trận hàng, ma trận cột hoặc ma trận tổng quát về thời gian và khoảng cách đã tính toán, tùy thuộc vào thông số đầu vào của bạn cho các điểm xuất phát và điểm đến.

Ma trận tổng quát là một ma trận hàng, với thời gian và khoảng cách từ mỗi điểm xuất phát đến từng điểm đến. Với ma trận hàng là kiểu ma trận thời gian-khoảng cách "one_to_many", với một điểm xuất phát và nhiều điểm đến. Ma trận dạng này sẽ tính và trả về thời gian và khoảng cách từ điểm xuất phát đến tất cả các điểm đến. Còn với ma trận cột sẽ cho ra ma trận thời gian-khoảng cách "many_to_one", nơi có nhiều điểm xuất phát và một điểm đến.

Một trường hợp đặc biệt khác là khi danh sách các điểm xuất phát giống với danh sách các điểm đến. Khi đó, một ma trận chéo sẽ được trả về (ma trận vuông với [0, 0.00] trên các phần tử đường chéo). Trường hợp đặc biệt này thường được sử dụng làm đầu vào cho các bài toán tối ưu hóa lộ trình.

Đầu vào cho API Distance Matrix

Khi yêu cầu API Distance Matrix ở hệ thống cục bộ thì sẽ có dạng /distancematrix?json={}, trong đó các đầu vào JSON bên trong bao gồm ít nhất một vị trí cho cả điểm xuất phát (sources) và điểm đến (targets), các tham số costing và directions_options cũng cần được điền vào để nêu rõ loại hình phương tiện

Ví dụ, khi bạn đang ở văn phòng và muốn biết thời gian và khoảng cách đi bộ đến một số nhà hàng để ăn tối, cũng như thời gian và khoảng cách từ mỗi nhà hàng này đến ga tàu để về nhà. API này sẽ giúp bạn quyết định lựa chọn nhà hàng nào để dùng bữa.

one-to-many using /distancematrix?json=

{
  "sources": [
    {
      "lat": "21.0327830",
      "lon": "105.7879150"
    }
  ],
  "targets": [
    {
      "lat": "21.0463",
      "lon": "105.794"
    },
    {
      "lat": "21.07278",
      "lon": "105.76922"
    },
    {
      "lat": "21.03443",
      "lon": "105.7372"
    },
    {
      "lat": "21.09053",
      "lon": "105.78181"
    },
    {
      "lat": "21.05397",
      "lon": "105.72142"
    }
  ]
}

many-to-one using /distancematrix?json=

{
  "sources": [
    {
      "lat": "21.0327830",
      "lon": "105.7879150"
    },
    {
      "lat": "21.0266570",
      "lon": "105.7891160"
    },
    {
      "lat": "21.0388177",
      "lon": "105.7967898"
    },
    {
      "lat": "21.0441325",
      "lon": "105.8034620"
    },
    {
      "lat": "21.0398450",
      "lon": "105.8059000"
    }
  ],
  "targets": [
    {
      "lat": "21.0463",
      "lon": "105.794"
    }
  ]
}

many-to-many using /distancematrix?json=

{
  "sources": [
    {
      "lat": "21.0327830",
      "lon": "105.7879150"
    },
    {
      "lat": "21.0266570",
      "lon": "105.7891160"
    },
    {
      "lat": "21.0388177",
      "lon": "105.7967898"
    },
    {
      "lat": "21.0441325",
      "lon": "105.8034620"
    },
    {
      "lat": "21.0398450",
      "lon": "105.8059000"
    }
  ],
  "targets": [
    {
      "lat": "21.0463",
      "lon": "105.794"
    },
    {
      "lat": "21.07278",
      "lon": "105.76922"
    },
    {
      "lat": "21.03443",
      "lon": "105.7372"
    },
    {
      "lat": "21.09053",
      "lon": "105.78181"
    },
    {
      "lat": "21.05397",
      "lon": "105.72142"
    }
  ]
}

Tham số điểm bắt đầu (source) và điểm cuối (target)

Khi sử dụng Distance Matrix API, bạn cần chỉ định các điểm xuất phát (sources) và điểm đến (targets) dưới dạng danh sách có thứ tự gồm một hoặc nhiều vị trí trong một mảng JSON, tùy thuộc vào loại kết quả ma trận mà bạn mong đợi.

Mỗi điểm xuất phát và điểm đến phải bao gồm vĩ độ và kinh độ dưới dạng số thập phân. Các tọa độ này có thể được lấy từ nhiều nguồn đầu vào khác nhau, chẳng hạn như vị trí GPS, một điểm hoặc chọn địa điểm trên bản đồ, thông qua dịch vụ truy xuất địa chỉ (geocoding), v.v.

Tham số source and target	Mô tả
`lat`	Vĩ độ của source/target dưới dạng thập phân.
`lon`	Kinh độ của source/target dưới dạng thập phân.
`date_time`	Thời gian/ngày dự kiến người dùng sẽ có mặt tại địa điểm được sử dụng theo định dạng ISO 8601 (YYYY-MM-DDThh:mm) trong múi giờ địa phương của thời gian khởi hành hoặc thời gian khi đến nơi. Việc sử dụng date_time làm đầu vào cho địa điểm cung cấp mức độ chi tiết cao hơn trong việc thiết lập thời gian so với đối tượng date_time theo giờ quốc tế (xem bên dưới).

Ngoài ra khi sử dụng loại địa điểm type thay cho vĩ độ lat và kinh độ lon trong tham số vị trí thì sẽ không có ý nghĩa đối với ma trận.

Tham số loại hình phương tiện (Costing)

The Time-Distance Matrix service uses the auto, bicycle, pedestrian and bikeshare and other costing models available in the route service. Exception: multimodal costing is not supported for the time-distance matrix service at this time. Refer to the [route costing models] and [costing options] documentation for more on how to specify this input.

API Distance Matrix sử dụng các kiểu phương tiện như auto, bicycle, pedestrian, bikeshare và các kiểu khác có sẵn trong API Directions.

Các tùy chọn yêu cầu khác

Options	Description
`id`	Đặt tên cho yêu cầu ma trận của bạn. Nếu `id` đã được nhận diện, việc đặt tên sẽ được thông qua trong phần trả về.
`matrix_locations`	Đối với loại yêu cầu "one-to-many" hoặc "many-to-one", lựa chọn này sẽ xác định số lượng tối thiểu của các tọa độ có thể thỏa mãn điều kiện của một trong hai loại yêu cầu trên. Tuy nhiên, khi đã được xác định, lựa chọn này cho phép trả về một phần của kết quả. Điều này tương đương với việc "lọc ra được `matrix_locations`(ma trận tọa độ) phù hợp/gần nhất trong toàn bộ tọa độ".
`verbose`	Nếu được đặt là `true`, nó sẽ xuất ra một danh sách phẳng của các đối tượng cho khoảng cách `distances` & thời gian để hoàn thành khoảng cách này `durations`, trong đó điểm bắt đầu (source) và điểm đến (target) được liệt kê rõ ràng. Nếu đặt là `false`, nó sẽ trả về dưới dạng các mảng `distances` & `durations` với cấu trúc gọn hơn được lồng với nhau theo hàng và không hiển thị lại `sources` & `targets`.Mặc định sẽ là `true`.
`shape_format`	Tùy chọn này sẽ chỉ định hình dạng của đường đi kết nối giữa mỗi điểm. Bạn có thể chọn một trong các tùy chọn sau: `polyline6`, `polyline5`, `geojson`, hoặc để mặc định là `no_shape`.

Các ma trận có sự phụ thuộc vào thời gian.

Có thể kiểm soát các ràng buộc về thời gian bằng cách thiết lập một chuỗi date_time trong từng điểm xuất phát (source) hoặc điểm đến (target).Khi sử dụng đối tượng date_time (theo giờ quốc tế) như một phím tắt, Openmap.vn sẽ dựa trên đó và chuyển đổi date_time.value trong tất cả tọa độ điểm bắt đầu khi date_time.type = 0/1 và trong tất cả tọa độ điểm đến khi date_time.type = 2.

Tuy nhiên, có một số hạn chế bạn cần lưu ý đối với khả năng nhận biết thời gian của dịch vụ Distance Matrix. Do sự phức tạp của thuật toán, Chúng tôi sẽ không cho phép một số tổ hợp của date_timetrong các tọa độ phụ thuộc vào yếu tố thời gian nếu:

date_time.type = 0/1 hoặc date_time trên bất kỳ điểm xuất phát nào, khi có nhiều điểm xuất phát (sources) hơn điểm đến (target)
date_time.type = 2 hoặc date_time trên bất kỳ điểm đến nào, khi số lượng điểm đến nhiều hơn hoặc bằng số lượng điểm xuất phát

Các thông tin đầu ra của API Distance Matrix

Nếu một yêu cầu của API Distance Matrix được đặt tên bằng cách sử dụng tham số tùy chọn &id=, thì tên đó sẽ được trả về dưới dạng chuỗi id.

Dưới đây là các kết quả trả về cho một lần yêu cầu của API Distance Matrix.

Các mục	Mô tả
`sources_to_targets`	Trả về một mảng được sắp xếp theo hàng bao gồm thời gian và khoảng cách giữa các điểm xuất phát (sources) và điểm đến (targets). Các hàng này có thể hiểu là thời gian và khoảng cách từ vị trí đầu tiên đến tất cả các vị trí khác sẽ tạo thành hàng đầu tiên của mảng, hàng tiếp theo là thời gian và khoảng cách từ vị trí xuất phát thứ hai đến tất cả các vị trí đích, và cứ tiếp tục như vậy đối với các điểm còn lại.
`distance`	Khoảng cách được tính giữa mỗi cặp điểm. Khoảng cách sẽ luôn ở dạng 0.00 cho phần tử đầu tiên của mảng thời gian-khoảng cách trong trường hợp `one_to_many`, phần tử cuối cùng trong trường hợp `many_to_one`, và cả phần tử đầu tiên lẫn cuối cùng trong trường hợp `many_to_many`.
`time`	Thời gian được tính giữa mỗi cặp điểm. Thời gian sẽ luôn ở dạng 0 cho phần tử đầu tiên của mảng thời gian-khoảng cách trong trường hợp `one_to_many`, phần tử cuối cùng trong trường hợp `many_to_one`, và cả phần tử đầu tiên lẫn cuối cùng trong trường hợp `many_to_many`.
`to_index`	điểm đến đã được index trong vị trí array.
`from_index`	điểm đến đã được index trong vị trí mảng.
`date_time`	(không bắt buộc) nếu date_time hợp lệ cho một điểm xuất phát, `date_time` sẽ trả về thời gian theo giờ địa phương tại điểm đến.
`locations`	Mảng vĩ độ (lat) và kinh độ (lng) đã được chỉ định tại đầu vào khi yêu cầu.
`units`	Đơn vị khoảng cách cho kết quả đầu ra. Các loại đơn vị cho phép là mi (dặm) và km (kilomet). Nếu không chỉ định loại đơn vị, đơn vị mặc định sẽ là kilômét.
`warnings` (không bắt buộc)	Mảng này có thể chứa các đối tượng cảnh báo nhằm thông tin về các tham số yêu cầu đã không còn được hỗ trợ, các giá trị bị giới hạn, v.v.

Diễn giải trực quan

Xem diễn giải trực quan tại đây.

Distance Matrix APIs

Base URL​

API Distance Matrix​

Đầu vào cho API Distance Matrix​

Tham số điểm bắt đầu (source) và điểm cuối (target)​

Tham số loại hình phương tiện (Costing)​

Các tùy chọn yêu cầu khác​

Các ma trận có sự phụ thuộc vào thời gian.​

Các thông tin đầu ra của API Distance Matrix​

Diễn giải trực quan​