Vehicle Routing Problem API

Vehicle Routing Problem (VRP) API phục vụ bài toán định tuyến phương tiện, là một loại bài toán tối ưu hóa liên quan đến việc tìm các tuyến đường hiệu quả nhất cho một đội phương tiện di chuyển đến một tập hợp các điểm đến và quay trở lại điểm xuất phát trong khi đáp ứng một số ràng buộc, chẳng hạn như công suất và thời gian. VRP thường được sử dụng trong các ứng dụng vận chuyển, hậu cần và giao hàng.

Các nhà phát triển có thể sử dụng Vehicle Routing Problem (VRP) API để tạo các ứng dụng giúp tối ưu hóa hoạt động của đội xe và quản lý phân phối, chẳng hạn như lập kế hoạch tuyến đường, theo dõi đội xe, v.v.

Bạn có thể tham khảo ví dụ sử dụng Vehicle Routing Problem (VRP) API với JavaScript

Chú thích

Đối tượng tọa độ có giá trị [{longitude},{latitude}]
Giá trị thời gian có đơn vị giây
Giá trị độ dài có đơn vị mét
Đối tượng time_window là một mốc thời gian có giá trị [{time_start}, {time_end}]
Các giá trị cost trong dữ liệu trả về là chi phí sử dụng với mục tiêu tối ưu hóa chi phí (mặc định bằng với duration)
Một công việc là job, pickup hoặc delivery

URL

URL: /navigation/vrp/

Method

Method: POST

Parameters

* tham số yêu cầu.

Tham số	Mô tả	Giá trị
`api_key*`	Key xác thực để cho gọi dịch vụ	`YOUR_API_KEY`

$ curl "https://api.ekgis.vn/navigation/vrp?api_key={YOUR_API_KEY}"

Body

* tham số yêu cầu.

Tham số	Mô tả
`jobs` (array)*	Mảng các đối tượng `job` mô tả các địa điểm cần tới.
`vehicles` (array)*	Mảng các đối tượng `vehicle` mô tả các phương tiện có sẵn.
`shipments` *(array)*	Mảng các đối tượng `shipment` mô tả công việc nhận và giao hàng.

Jobs

Một đối tượng job có các thuộc tính sau:

* tham số yêu cầu.

Tham số	Mô tả	Giá trị
`id` (integer)*	id của công việc Một đối tượng `job` chỉ có một `id` duy nhất	Ví dụ: `1`
`location` (array)*	Tọa của công việc	`[{longitude},{latitude}]` Ví dụ:`[105.836, 21.043]`
`description` *(string)*	Mô tả công việc
`setup` *(number)*	Thời gian chuẩn bị công việc (Mặc định là 0) Lưu ý `setup`
`service` *(number)*	Thời gian phục vụ công việc (Mặc định là 0)
`skills` *(array)*	Mảng các số nguyên xác định xác định các kỹ năng yêu cầu Lưu ý `skills`	Ví dụ:`[1, 2, 8]`
`priority` *(integer)*	Thứ tự ưu tiên của công việc. Giá trị từ 0 đến 100 (Mặc định là 0) Lưu ý `priority`
`time_windows` *(array)*	Mảng các mốc thời gian thực hiện công việc Lưu ý `time_window`	`[{time_start}, {time_end}]`

Vehicles

Một đối tượng vehicle có các thuộc tính sau:

* tham số yêu cầu.

Tham số	Mô tả	Giá trị
`id` (integer)*	id của phương tiện	Ví dụ: `5`
`profile` (string)*	Loại phương tiện di chuyển: `driving-car`: Đi bằng ô tô `cycling-regular`: Đi bằng xe đạp/xe máy `foot-walking`: Đi bộ	Ví dụ: `driving-car`
`description` *(string)*	Mô tả phương tiện
`start` *(array)*	Tọa độ điểm bắt đầu Lưu ý vị trí `vehicle`	`[{longitude},{latitude}]` Ví dụ:`[105.43272, 21.83641]`
`end` *(array)*	Tọa độ điểm kết thúc Lưu ý vị trí `vehicle`	`[{longitude},{latitude}]` Ví dụ:`[105.83641, 21.04303]`
`costs` *(object)*	Chi phí hoạt động của phương tiện. Đối tượng `cost` có tham số: `fixed`*(integer): Chi phí sử dụng phương tiện (mặc định là 0) `per_hour`(integer): Chi phí cho một giờ sử dụng phương tiện (mặc định là 3600) Thay đổi giá trị `per_hour` mặc định có nghĩa là chi phí được xác định dựa trên hệ số nhân với thời gian di chuyển*
`skills` *(array)*	Mảng các số nguyên xác định xác định các kỹ năng yêu cầu Lưu ý `skills`	Ví dụ:`[1, 2, 8]`
`time_window` *(object)*	Mốc thời gian hoạt động của phương tiện Lưu ý `time_window`	`[{time_start}, {time_end}]`
`breaks` *(array)*	Danh sách các đối tượng `break` mô tả thời gian nghỉ của phương tiện Mỗi đối tượng `break` có tham số: `id`*(integer)* `time_windows`*(array): Mảng các mốc thời gian hợp lệ `service`(number): Thời gian thực hiện (mặc định là 0) `description`(string): Mô tả công việc `max_load`(array): Mảng số nguyên mô tả tải trọng tối đa của xe Một đối tượng `break` chỉ có một `id` duy nhất với cùng phương tiện*
`max_tasks` *(integer)*	Số lượng công việc tối đa trên một tuyến đường của phương tiện
`max_travel_time` *(integer)*	Thời gian di chuyển tối đa của phương tiện

Shipments

Một đối tượng shipment có các thuộc tính sau:

* tham số yêu cầu.

Tham số	Mô tả	Giá trị
`pickup` (object)*	Đối tượng `shipment_step` mô tả việc nhận hàng
`delivery` (object)*	Đối tượng `shipment_step` mô tả việc giao hàng
`skills` *(array)*	Mảng các số nguyên xác định xác định các kỹ năng yêu cầu Lưu ý `skills`
`priority` *(integer)*	Thứ tự ưu tiên của công việc. Giá trị từ 0 đến 100 (Mặc định là 0) Lưu ý `priority`

Shipment_step

* tham số yêu cầu.

Tham số	Mô tả	Giá trị
`id` (integer)*	id của công việc Một đối tượng `shipment_step` chỉ có một `id` duy nhất	Ví dụ: `1`
`location` (array)*	Tọa độ của công việc	`[{longitude},{latitude}]` Ví dụ:`[105.836, 21.043]`
`description` *(string)*	Mô tả công việc
`setup` *(number)*	Thời gian chuẩn bị công việc (Mặc định là 0) Lưu ý `setup`
`service` *(number)*	Thời gian phục vụ công việc (Mặc định là 0)
`time_windows` *(array)*	Mảng các mốc thời gian thực hiện công việc	`[{time_start}, {time_end}]`

Ví dụ

Ví dụ body gửi lên dạng JSON như sau:

{
"jobs": [
{
"id": 1,
"location": [105.83641, 21.04303]
},
{
"id": 2,
"location": [105.84888, 21.03171]
},
...
],
"vehicles": [
{
"id": 1,
"start": [105.83641, 21.04303],
"end": [105.83641, 21.04303],
"profile": "driving-car"
},
...
],
}

Lưu ý

`Vehicle`

Vị trí của Vehicle:

Tham số start và end là tùy chọn cho một vehicles, miễn là có ít nhất một trong hai tham số
Nếu end bỏ trống, tuyến đường trả về sẽ dừng lại tại điểm cuối của jobs
Nếu start bỏ trống, tuyến đường trả về sẽ bắt đầu tại điểm đầu tiên của jobs
Để tuyến đường trả về là khứ hồi, chỉ cần tham số start và end có cùng tọa độ

`Skills`

Sử dụng skills để mô tả công việc cần phải phục vụ bằng phương tiện chuyên biệt. Khi skills công việc được định nghĩa tức là công việc này chỉ có thể xử lý bởi phương tiện có toàn bộ các skills yêu cầu. Nói cách khác: công việc j có thể giao cho phương tiện v nếu j.skills có trong v.skills.

skills có ý nghĩa:

Một công việc không có skills có thể xử lý bởi bất kỳ phương tiện.
Một phương tiện không có skills chỉ có thể xử lý công việc không có skills.

`Priority`

Trong tình huống khi không thể thực hiện tất cả các công việc được giao, để kiểm soát các công việc unassigned. Tăng giá trị priority của công việc, kết quả trả về sẽ ưu tiên công việc có giá trị priority lớn hơn.

`Setup`

Thời gian setup là thời gian cần để bắt đầu công việc tại địa điểm của công việc đó. Vậy nên "thời gian thực hiện" cho một công việc là setup + service từ khi đến một địa điểm mới, hoặc chỉ service nếu thực hiện công việc mới tại vị trí trước đó.

`Time windows`

Người dùng quyết định cách mô tả các khoảng thời gian:

relative values (giá trị tương đối). VD: [0, 14400] trong 4 giờ kể từ khi bắt đầu thức hiện kế hoạch. Trong trường hợp này, các giá trị trả về của tham số arrival được hiểu là thời gian tính khi bắt đầu kế hoạch.
absolute values (giá trị tuyệt đối) - mốc thời gian "thực". Trong trường hợp này, các giá trị trả về của tham số arrival được hiểu là mốc thời gian thực tính theo Unix timestamp (Thời gian Unix).

Việc không định nghĩa time_window tại đầu vào đồng nghĩa với việc không áp dụng hạn chế về thời gian. Cụ thể, một phương tiện không có giá trị time_window có thể xử lý bất kỳ số lượng công viêc, và một công việc không có giá trị time_windows có thể được xử lý bất cứ lúc nào, bất kỳ tuyến đường cùng kết hợp với các điều kiện bổ sung khác.

Response

Đối tượng trả về ma trận với các thông tin sau:

Tham số	Mô tả
`code`	Trạng thái dịch vụ trả về, nếu yêu cầu thành công giá trị là `0`
`summary`	Kết quả tổng hợp các chỉ số
`unassigned`	Danh sách các đối tượng chưa được phục vụ
`routes`	Danh sách các tuyến đường

Summary

Đối tượng summary có các thông tin sau:

Tham số	Mô tả
`cost`	Tổng chi phí cho toàn lộ trình
`routes`	Tổng lộ trình phù hợp
`unassigned`	Tổng các đối tượng chưa được phục vụ
`duration`	Tổng thời gian di chuyển cho toàn lộ trình
`violations`	Danh sách các đối tượng `violation` toàn lộ trình

Routes

Đối tượng route có các thông tin sau:

Tham số	Mô tả
`vehicle`	id của phương tiện trên tuyến đường
`steps`	Danh sách các bước cho tuyến đường
`cost`	Chi phí cho tuyến đường
`duration`	Tổng thời gian di chuyển cho tuyến đường
`violations`	Danh sách các đối tượng `violation` cho tuyến đường

Steps

Đối tượng step có các thông tin sau:

Tham số	Mô tả
`type`	Loại công việc (có thể là `start`, `job`, `pickup`, `delivery`, `break` hoặc `end`)
`id`	id công việc của bước (chỉ khi giá trị `type` là `job`, `pickup`, `delivery` hoặc `break`)
`arrival`	Thời gian ước tính di chuyển đến bước
`duration`	Thời gian di chuyển tích lũy khi đến bước
`location`	Tọa độ của bước (nếu được cung cấp trong đầu vào)
`violations`	Danh sách các đối tượng `violation`

Violations

Đối tượng violation có các thông tin sau:

Tham số	Mô tả
`cause`	Nguyên nhân
`duration`	Sớm hơn (hoặc Muộn hơn) nếu `cause` là `lead_time` (hoặc `delay`)

Nguyên nhân violation:

delay: nếu thời gian thực hiện công việc kết thúc trễ hơn mốc thời gian công việc ban đầu
lead_time: nếu thời gian thực hiện công việc bắt đầu sớm hơn mốc thời gian công việc ban đầu
load: nếu phương tiện vượt quá tải trọng
max_tasks: nếu phương tiện vượt quá giá trị max_tasks
precedence: nếu shipment không theo quy tắc (pickup không delivery, delivery trước hoặc không pickup)
missing_break: nếu bỏ qua công việc break của phương tiện
max_travel_time: nếu thời gian di chuyển phương tiện vượt quá giá trị max_travel_time
max_load: nếu vượt quá giá trị max_load

Ví dụ

Ví dụ dữ liệu trả về dạng JSON:

{
"code": 0,
"summary": {
"cost": 1398,
"routes": 1,
"unassigned": 0,
"setup": 0,
"service": 0,
"duration": 1398,
"waiting_time": 0,
"priority": 0,
"violations": [],
"computing_times": {
"loading": 21,
"solving": 0
}
},
"unassigned": [],
"routes": [
{
"vehicle": 0,
"cost": 1398,
"setup": 0,
"service": 0,
"duration": 1398,
"waiting_time": 0,
"priority": 0,
"steps": [
{
"type": "start",
"location": [
105.83641,
21.04303
],
"setup": 0,
"service": 0,
"waiting_time": 0,
"arrival": 0,
"duration": 0,
"violations": []
},
...
{
"type": "job",
"location": [
105.84888,
21.03171
],
"id": 2,
"setup": 0,
"service": 0,
"waiting_time": 0,
"job": 2,
"arrival": 322,
"duration": 322,
"violations": []
}
...
],
"violations": []
}
]
}

Tài liệu này có hữu ích với bạn không?