Vehicle Routing Problem (VRP)¶
The Vehicle Routing Problem (VRP) is a type of optimization problem that involves finding the most efficient routes for a fleet of vehicles to travel to a set of destinations and return to their starting point while satisfying a number of constraints, such as capacity and time windows. The VRP is commonly used in transportation, logistics, and delivery applications.
A Vehicle Routing Problem (VRP) Maps API refers to a set of functions or tools provided by VIETMAP that help developers to solve the VRP for a given set of locations and constraints. These APIs may provide algorithms or heuristics for finding optimal or near-optimal solutions to the VRP, as well as visualization tools for displaying the resulting routes on a map. Developers can use VRP Maps APIs to create applications that help optimize fleet operations and delivery management, such as route planning, fleet tracking, and more.
URL¶
Method¶
POST
Parameters¶
| Key | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| jobs | array | yes | none | array of job objects describing the places to visit | |
| vehicles | array | yes | none | array of vehicle objects describing the available vehicles |
Job Object (accept goods | release goods)¶
| Key | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| id | integer | yes | none | 1 | an integer used as unique identifier |
| location | array, double | yes | none | [106.112456,10.684922] | coordinates array |
| service | integer | no | none | 1 | job service duration (defaults to 0) |
| delivery | array | no | none | [1,2] | an array of integers describing multidimensional quantities for delivery |
| pickup | array | no | none | [1,2] | an array of integers describing multidimensional quantities for pickup |
| skills | array | no | none | [1] | an array of integers defining mandatory skills |
| priority | integer | no | none | 1 | Values: [0,10]. Range describing priority level |
| time_windows | array | no | none | [0,1400] | an array of time_window objects describing valid slots for job service start |
Vehicle Object (type of the vehicle)¶
| Key | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| id | integer | yes | none | 1 | an integer used as unique identifier |
| start | array, double | yes | none | [106.112456,10.684922] | coordinates array |
| end | array | yes | none | [106.112456,10.684922] | coordinates array |
| capacity | array | no | none | [0,3] | an array of integers describing multidimensional quantities |
| skills | array | no | none | [1] | an array of integers defining skills |
| time_windows | array | no | none | [0,14400] | a time_window object describing working hours |
Note¶
- Key start and end are optional for a vehicle, as long as at least one of them is present.
- If end is omitted, the resulting route will stop at the last visited job, whose choice is determined by the optimization process.
- If start is omitted, the resulting route will start at the first visited job, whose choice is determined by the optimization process.
- To request a round trip, just specify both start and end with the same coordinates.
- Use amounts (capacity for vehicles, delivery and pickup for jobs) to describe a problem with capacity restrictions. Those arrays can be used to model custom restrictions for several metrics at once, e.g. number of items, weight, volume etc. A vehicle is only allowed to serve a set of jobs if the resulting load at each route step is lower than the matching value in capacity for each metric. When using multiple components for amounts, it is recommended to put the most important/limiting metrics first.
- It is assumed that all delivery-related amounts for jobs are loaded at vehicle start, while all pickup-related amounts for jobs are brought back at vehicle end.
- Use skills to describe a problem where not all jobs can be served by all vehicles. Job skills are mandatory, i.e. a job can only be served by a vehicle that has all its required skills. In other words: job j is eligible to vehicle v iff j.skills is included in v.skills.
- In order to ease modeling problems with no skills required, it is assumed that there is no restriction at all if no skills keys are provided.
- Useful in situations where not all jobs can be performed, to gain some control on which jobs are unassigned.
- Setting a high priority value for some jobs will tend as much as possible to have them included in the solution over lower-priority jobs.
It is up to users to decide how to describe time windows:
- Relative values, e.g. [0, 14400] for a 4 hours time window starting at the beginning of the planning horizon. In that case all times reported in output with the arrival key are relative to the start of the planning horizon;
- Absolute values, "real" timestamps. In that case all times reported in output with the arrival key can be interpreted as timestamps. The absence of a time window in input means no timing constraint applies.
- In particular, a vehicle with no time_window key will be able to serve any number of jobs, and a job with no time_windows key might be included at any time in any route, to the extent permitted by other constraints such as skills, capacity and other vehicles/jobs time windows.
Example¶
Body
{
"vehicles": [
{
"id": 1,
"start": [
106.5983012,
10.8879148
],
"end": [
106.5983012,
10.8879148
],
"profile": "bike",
"time_window": [
1685953800,
1686418200
],
"skills": [
1,
1000
],
"breaks": [
{
"id": 1000,
"time_windows": [
[
1685966400,
1685970000
]
],
"service": 3600
},
{
"id": 1,
"time_windows": [
[
1685986200,
1685988000
]
],
"service": 54000.0
},
{
"id": 2000,
"time_windows": [
[
1686052800,
1686056400
]
],
"service": 3600
},
{
"id": 2,
"time_windows": [
[
1686072600,
1686074400
]
],
"service": 54000.0
},
{
"id": 6000,
"time_windows": [
[
1686398400,
1686402000
]
],
"service": 3600
}
],
"speed_factor": 0.6
},
/// More objects should be add to here
{
"id": 7,
"start": [
106.7086064,
10.814915
],
"end": [
106.7086064,
10.814915
],
"profile": "bike",
"time_window": [
1685953800,
1686418200
],
"skills": [
1,
7000
],
"breaks": [
{
"id": 1000,
"time_windows": [
[
1685966400,
1685970000
]
],
"service": 3600
},
{
"id": 5,
"time_windows": [
[
1686331800,
1686333600
]
],
"service": 54000.0
},
{
"id": 6000,
"time_windows": [
[
1686398400,
1686402000
]
],
"service": 3600
}
],
"speed_factor": 0.6
}
],
"jobs": [
{
"id": 1001,
"description": "HOME",
"location": [
106.5983012,
10.8879148
],
"service": 0,
"priority": 3,
"time_windows": [
[
1685986200,
1685988000
]
],
"skills": [
1000
]
},
{
"id": 304,
"description": "CO.OP FOOD NGUYỄN VĂN QUÁ",
"location": [
106.6287481,
10.8362058
],
"service": 1800,
"time_windows": [
[
1685948400,
1685980800
],
[
1686034800,
1686067200
],
[
1686121200,
1686153600
],
[
1686207600,
1686240000
],
[
1686294000,
1686326400
],
[
1686380400,
1686412800
]
],
"skills": [
1
]
},
/// More objects should be add to here
{
"id": 337,
"description": "CO.OP FOOD TỈNH LỘ 15-1031",
"location": [
106.513876765966,
11.0885457429547
],
"service": 1800,
"time_windows": [
[
1685948400,
1685980800
],
[
1686034800,
1686067200
],
[
1686121200,
1686153600
],
[
1686207600,
1686240000
],
[
1686294000,
1686326400
],
[
1686380400,
1686412800
]
],
"skills": [
1
]
}
]
}
Request body description¶
Vehicles¶
| Parameter | Type | Description |
|---|---|---|
| id | number | The ID of the vehicle. |
| start | array | The starting location of the vehicle (longitude, latitude). |
| end | array | The ending location of the vehicle (longitude, latitude). |
| profile | string | The profile of the vehicle (e.g., "bike"). |
| time_window | array | The time window during which the vehicle is available for service. |
| skills | array | An array of skills required for the vehicle to perform a job. |
| breaks | array | An array containing information about breaks for the vehicle. |
| speed_factor | number | The speed factor of the vehicle. |
Jobs¶
| Parameter | Type | Description |
|---|---|---|
| id | number | The ID of the job. |
| description | string | A description of the job. |
| location | array | The location of the job (longitude, latitude). |
| service | number | The duration of the service at the job location in seconds. |
| priority | number | The priority of the job. |
| time_windows | array | An array of time windows during which the job can be serviced. |
| skills | array | An array of skills required for the job to be performed. |
Response
{
"code": 0,
"summary": {
"cost": 12400,
"unassigned": 0,
"service": 196200,
"duration": 12400,
"waiting_time": 237145,
"priority": 3,
"distance": 109272,
"computing_times": {
"loading": 37,
"solving": 61,
"routing": 11
}
},
"unassigned": [],
"routes": [
{
"vehicle": 1,
"cost": 12400,
"service": 196200,
"duration": 12400,
"waiting_time": 237145,
"priority": 3,
"distance": 109272,
"steps": [
{
"type": "start",
"location": [
106.5983012,
10.8879148
],
"arrival": 1685956255,
"duration": 0,
"distance": 0
},
/// More object will response here
{
"type": "break",
"id": 6000,
"service": 3600,
"waiting_time": 177741,
"arrival": 1686220659,
"duration": 12400,
"distance": 109272
},
{
"type": "end",
"location": [
106.5983012,
10.8879148
],
"arrival": 1686402000,
"duration": 12400,
"distance": 109272
}
],
"geometry": "ipmaA}|riSsAHGpB?\\ExC?l@CnBC`@OrAENK?EBCJ@FcBtBm@x@{B|CY^U`@GPG\\e@nCSp@uAlCWd@{C|F_AjBcAfB{AvCS^w@|A[j@Ub@INo@nAm@jAk@fAq@tAwBfEy@zAyAvCqAfCe@~@[j@c@z@mDxGs@vAOVw@dBw@xAi@fAOXs@rAKPyApCGLwA~CMXcUrNi@\\iHnEyBtAg[vRsCdBo[~RsCfB_CzA}BvAiC`BqBnAgEhCoMdIuAx@kNxIqAx@gAr@cDjBwDbCaF|CoBpA{@n@oAdAsCfCaDrC_FfEy@v@qApAc@f@i@t@g@r@w@~AQf@uGrP}IxUqFxNcBrEmB~EgCrGiCpGsAhDmDbJ{BpGwBtFkFhNgDzImC`H{@bBeCbE_BpCcAbBwDlG{FnJsDjGqH~LwFfJaC`EgDtFaEnHoAvCyBlFk@tAmAvCi@nA]v@eBfEeH~PwBxEgBpDgAzBaBhDqBbEmBzDkCzF_BbEwAbFoAfE{GnUSt@I`@w@fDOLKVoAfEc@lAM?MBQLELgAPaAg@eAk@eE_Cc@WqAu@uDsB_GcDaDeBuEkCwAu@}@i@kDkBkBeAy@e@aDcBcAk@uD{BgA`EgAfEfAgEfAaE_CsAqBgAcGeDQKmGkD}CcBtBuBTUlBkDfBcDbB{C`AcBl@}@NOVQ|BkAfDeBfD_B|C}AlDeBd@~@LIiB_EoEgJMYe@aAUc@{FsLqAcCoCyFwAaD[aAQy@WuAs@eE_@}Bc@iCc@mC]wBy@}E_@cC[oBi@_DMs@AKk@kDu@yEyA}IIk@CYAy@BSXmBXgBuBi@mAY{@QcAGkADyCReCNy@?}@IkAWs@GeD[iB]WSIMa@s@sAsCqAsCWc@KIUO[I_F{@qCiAgCgA{Ae@s@M_Eq@IGY]MSeAkCKSc@c@i@]{@m@kGwEgAs@c@W[MqLcDuA[cASwFi@oASyC]gC_@KEoBaAy@KkAAkILoE?]@wOLk@BQDkGhCyD|AyB|@mAj@_DpAkS~HcAh@_E~AoGjCqDxAgXzKsElB_G~BiMfFcEdBmAf@cCbA[LWHcKdEcBp@YLoHxCgFxBq`@~OwDxAgDvAwThJk@T[LqCjAsFrBiAd@}EtBkN~FcBp@qAj@c@Vo@`@kCnBqCpBuB\\u@NgA{AeE_HcBwBm@m@aFcE_DuCeFwFqA}AiKuPg@k@aCaC{D{DoCiCk@t@cA~@[VULmFfBw@Xo@TgBl@yBt@yMlEsGlB_Ct@uBl@kCh@cCl@eCj@m@LiEz@{Ev@q@JqG`AeDj@oDn@kDl@iAR^\\_@]hASjDm@nDo@dDk@pGaAp@KzEw@hE{@l@MdCk@bCm@jCi@tBm@~Bu@rGmBxMmExBu@fBm@n@Uv@YxDmAr@YTMZWbA_Aj@u@Xo@Va@hAaBlBeClHiJ`BmBtCsDnBiCb@g@d@_@bE{BxHmElBaAzB_AvIaDbAa@jHoCnE{AjJmDpCsAf@[d@a@jA_BpAqBfBgDtBqE|@gCn@cBr@aBv@cB|@kBlBqDfBcD~AsClE}HZg@zBoDNWxDkG|AkCj@gApB{DhAoBt@oAlBuDp@sAhAqB`C{DrB_DpCcEbBwCpAsBz@yAx@sApByCx@yAbCoDjAmB`EiGLS~CeFv@kAd@k@v@q@p@i@LOV_@x@wAFSFUD]Ac@]{DOmB?e@L{ALu@FOLQh@OlAQ`@GXKXOnCyCVSXITCT?d@Jp@\\bBpAXL`@N\\Df@@t@CrADvFP`@B~@HlEXhET`BJtCJf@BbFXv@Hx@JxIrAXDbFv@hANlFJ`IXrBFnBBrAHrAPpCb@dAHp@AnDSxAIzAKlAMl@M`LmEhH{CtCmA~@a@hBu@`EeBn@WbSiInCkAlEgBpAi@bCaA`Bk@|Bs@fCu@jBo@`H{BNGfA[vDgAjDiAlBm@zIoCfKcDpH_CxAc@dHyBdBi@pAa@pAa@xBw@`A]h@ObA[rAa@rAa@`Cy@bAa@~BsBvOwNfBaBvGgG~@_A~AwAlDcDdIkHzKgKdC}Bf@c@hC_Cn@m@RQnAgAd@e@`A_A`EsDvAsAzAwAhAeApCeCLMr@o@`B{AxCsCd@a@rF_FtBcB|E{DrAcArEuDnCwBhDkCt@c@jBy@p@[|@c@|CgBl@]pBgA|CgBrC_BdCuAz@i@@ArL_H~BsA|BsAhDuBLEb@?`AFTD`BXjBd@rA^fEhAl@Rz@^x@\\PJhAr@ZVRLPDZDZ@~@ClDc@fCGdE@rBB^BzE^`BNxIp@dE`@zFr@zCd@tIhApGv@pGz@hXrDpDh@lEh@~Ex@pANX@tEJpBBzLP`ABdBDtEJV@fCDpADhAFhBNhBRRBlALt@HxBTzAN^Dt@@rD@l@?|L@dVAl@ErCc@ZEfAOfBUp@ChAB~ATj@LdEhAtA^|Cx@b@LjDfAfGnBf@N`Bf@hA^NFjCx@t@VrBn@v@VfAZTD\\@|ABvED|A@nA@~@BDyC?]FqBrAInAIhDW~AMxAKrDYtBKz@FxANn@Dx@@VCVEb@Qn@U`DsA`@MdB_@NAl@?jE?rMB^F|Bl@La@b@{@r@mAJUh@{AVq@Jm@Hy@DiAFa@Pm@P_@vByDr@yA\\o@s@Ur@T]n@s@xAwBxDQ^Ql@G`@EhAIx@Kl@Wp@i@zAKTs@lAc@z@M`@dG|Ap@PzA^bHjB|@X\\J~DtAx@V~Ah@x@XJPzAaAFH`A`Bb@hAXvANnANzAJrA@f@EXKJc@Nn@fDT|AJzAHdBBX`@nA@JEP[r@CR@XRv@?TEx@Mz@qESS@IHGJ]zAMRGDWAwAYERDSvAXV@FELS\\{AFKHIRApER`ENV@xBDbBD`CHpDNrDLjFLj@?hAGfDQ`AUvAi@b@I`AMtF_@nBK`CKxAIfG_@v@AT?h@BvB^xAP`@BdBH`@Fj@N^Jv@VfBp@jBt@hA^XHhBf@fDtAl@\\}ApB]d@\\e@|AqBV[~@gA`AqA|BaDx@kAdAyARWlGwIf@u@r@aAj@s@zCsEfAyAVWjBgBdAaArEuEbA_AbAaA`@g@pAaCJOhAgBr@y@~AuBxAkB|AqBl@w@~@kAl@u@LOxAkB^e@tAgBp@_Aq@~@uAfB_@d@yAjBMNm@t@_AjAm@v@}ApByAjBsCnDgBkB_@[WOg@Se@QwAY}@EuCAmBL_A?gACy@Gy@IoBQa@IkAYsBi@OIeL~@c@FyALg@?kFu@yB]}AUs@KsBWsJyAUEWCuHmAmAQToALm@@Y?Q_@oAmAqBo@eAg@y@MSq@eAs@kAGIb@WrBqApCgBxBsAdEaCzJqFFH^t@GX@JdAfBLBLCr@a@fC{AhB}@VQ`Am@hCyALGZODCj@Y`DgBc@u@_@s@e@u@Sa@GIdMaHdE_CvAe@RM~EoC^SfBaArCyAbAe@NDP?REFENMFQBMC[IQMMQGYAy@w@]_@oC_DyAaBnBuA|DgCtDaC|CqBdAo@i@WF[GOYg@KO]aArA_@]mBBQmAwBVOf@_@dAq@TSRKP_@w@eAxBoApFmCJKP[F[`@mEH{@h@iGjADZ@~BJx@D@w@Ds@D]VuA^kBXFl@Jm@KYGk@KaBWs@MaAQq@Mk@IaBYsDo@KC_AMqAOq@Gm@G}C_A_AYkA_@iBk@yAe@iA]]Ue@c@c@_@aFeEk@e@q@m@USm@y@s@aAQSaAsA{@eAU_@]YQKm@_@iAm@}@g@}@g@|@f@|@f@hAl@l@^eIdMiAhBy@hA[b@o@nAYt@i@dBOt@QvAGf@cAlJE`@KZWr@SZe@b@g@XsAj@sDxAi@XkAp@aAv@_A|@_AhAa@l@{@~A_@~@c@Lm@Bs@g@a@P`@QkCeBeCeBK[IcBEyAG}B[_HCu@Y{DGCw@Im@O[Q_Au@uAmAw@q@YWw@s@wAoAyBkB{GyDkAzAjA{AkCqAi@Yo@[{@e@KEaB{@wAo@q@[SK[MqAi@w@Y_Bk@kC{@sAo@WIw@[qAe@cA_@UASGRFNNdA^BMNg@@[CuBKmBKmAm@oEAU@KH[T_@Zg@d@u@dAcBT_@zBeEYI{Aq@]OeAg@m@YCAc@UcCsAiAk@UK_@S}C}A{GgDyDoB{CqAcDsAgBq@}@]{@a@e@Wa@a@g@Oj@eIVmCoDFwFJkDHbACfBEOkEAq@MgDEuACyBAgAA_@Aw@AMM_@OWa@s@m@mAMo@EyAASq@_OMeDEcAEeBA}@SuP?OO{IKg@a@gBEYIeCBa@J{@V{ALa@X_@HMZaB?a@OsAa@uAIc@GcCEk@G]h@Ij@Il@Il@INAp@KNAjAOjBYT?Ra@H[?KC_@@YJyAC]EOGMMe@E_AE}@CmAT}ABU?QI[NMh@e@`@a@hAkApAuAFON[z@cAOMsAiAWUaAw@eDoCk@e@gAo@q@_@[Oi@YN]FG|Aw@zBcAhB}@r@_@BKGWg@qAaA}BWk@aAyBQ]QWOQGKc@cAkAcDOi@Me@q@}BcA{BOY_@yA??Ka@]L\\Mj@zBNXd@l@\\lAp@|BLd@Nh@jAbDb@bAFJNPPVP\\`AxBVj@`A|Bf@pAFVCJs@^iB|@{BbA}Av@GFO\\o@x@kAXaDl@{Bb@KFEH@TXl@FXH|@BfA?|CBxBJlCJfDZ`FB\\HbCBRTx@|@|BDRF\\Dj@FbCHb@`@tANrA?`@Ir@Ql@ILY^M`@WzAKz@C`@@fAF|@DX`@fBJf@Dh@HpH?NRtP@|@DdBDbALdDZlHTpEkH\\e@Hi@LmCz@mAb@sBp@DRHx@ZbCNn@j@fBX`BN`B{@@u@Cy@Mk@Mc@Kb@Jj@Lx@Lt@Bz@Al@AD|CJ~EAz@Kx@Cx@CTQz@Uj@GPKj@Gj@@JFJ?NCd@Kv@E\\rATJDVPb@\\LPTZRLjBf@BHCf@@FFHJBp@DETCv@Kx@?d@N@HBlAr@rAv@bAj@xChBdBdAXPb@ZfAf@IxAGbATF??VJnLhG~HvE|FdDrChBzBfANF{@~Ae@|@a@t@m@z@k@v@]|AWv@Yl@w@|Au@dBe@v@]j@[h@i@~@MRqAtBeBnDUlBIr@Kr@WzACNY~Ai@zCe@tCG~@s@Zq@^i@Z}BhA[PQTSd@cAbCmBaBL]M\\gByAq@k@_C{Ao@a@gCaBuAy@wA}@a@W{@g@_@Uk@]sBqAmCcBo@c@mCkBgC}AoA{@\\gA]fAUMeBoAKKi@i@e@_@e@]sA_AOMk@_@u@g@e@[OKo@e@oDcCm@_@OK}@o@gAu@oKiHm@_@GEcAs@wA_Aa@Ys@e@cH}EcDZmBZUDuAl@wAb@o@XqBjAWNy@b@Ua@Ya@YGu@CoAH{@Ro@J{@Jk@Js@RyCx@yCx@yCb@]Jq@PmAd@MWgBqD]u@\\t@fBpDLVLVvCrGl@rAh@jA^v@lDrHbD`Hn@pAd@dAzAbDrAvC`@v@t@pAl@bAj@|@lAjBFJbErGpApB`BjCrCtEl@~@n@bA`A|Az@tAXb@hAhBzBrDxA|B|BrDh@x@Vn@Hf@r@xDt@hEt@bEX|AV`Ah@vAjAjCzA`D`@`Af@rATfAt@vGBf@E~@GlCBlAFj@ThCT|ENpAL|@Tz@d@rAd@rAXl@JNa@`BGl@EXEnCAdAA`AMdCg@zDAd@Cr@rAI"
}
]
}
Response body description¶
| Parameter | Type | Description |
|---|---|---|
| code | number | A numeric code indicating the status of the response. |
| summary | object | An object containing summary information about the routes. |
| summary.cost | number | The total cost of the routes. |
| summary.unassigned | number | The number of unassigned items. |
| summary.service | number | The total service time for all routes. |
| summary.duration | number | The total duration of the routes. |
| summary.waiting_time | number | The total waiting time for all routes. |
| summary.priority | number | The priority of the routes. |
| summary.distance | number | The total distance covered by the routes. |
| summary.computing_times | object | An object containing computing times for different operations. |
| summary.computing_times.loading | number | The time taken for loading. |
| summary.computing_times.solving | number | The time taken for solving. |
| summary.computing_times.routing | number | The time taken for routing. |
| unassigned | array | An array containing information about unassigned items. |
| routes | array | An array containing information about each route. |
| routes[].vehicle | number | The ID of the vehicle associated with the route. |
| routes[].cost | number | The cost of the route. |
| routes[].service | number | The service time for the route. |
| routes[].duration | number | The duration of the route. |
| routes[].waiting_time | number | The waiting time for the route. |
| routes[].priority | number | The priority of the route. |
| routes[].distance | number | The distance covered by the route. |
| routes[].steps | array | An array containing steps of the route. |
| routes[].steps[].type | string | The type of step (e.g., "start", "break", "end"). |
| routes[].steps[].location | array | The geographical location of the step (longitude, latitude). |
| routes[].steps[].arrival | number | The arrival time at the step. |
| routes[].steps[].duration | number | The duration of the step. |
| routes[].steps[].distance | number | The distance covered during the step. |
| routes[].geometry | string | The geometry of the route. |
