Optimize
Optimize REST API
The Optimize REST API provides endpoints for performing route optimization within the Fleet Management system.
All operations are stateless — no data is stored in the database — making them ideal for real-time route planning and what-if scenarios.
Key Functionalities
1. Full Route Optimization
- A comprehensive optimization that generates complete routing solutions.
- Considers multiple constraints such as:
- Vehicle capabilities
- Time windows
- Capacity limits
- Vehicle constraints
- Configuration parameters
2. Landmark Optimization
- A lightweight optimization that takes a list of coordinates and reorders them into an optimal sequence.
- Best suited for simple route planning needs.
3. Solution Retrieval
- Dedicated
/optimize/{id}/solutionendpoint for retrieving optimization results - Request tracking with status monitoring
- Support for polling mechanism to check completion status
Benefits
- Minimize travel time and distance with advanced optimization algorithms
- Respect all operational constraints including vehicle capabilities and time windows
- Flexible execution models:
- Asynchronous processing for complex multi-vehicle scenarios
- Synchronous processing for simple coordinate optimization
- Enhanced customization:
- Custom distance matrices for specialized routing needs
- Order sequencing for pickup/delivery operations
- Improved reliability with better error handling and validation
- Stateless operations ideal for real-time planning and what-if scenarios
Endpoints
1. Optimize with full details
Description: Receives a set of locations, vehicles, vehicle constraints, and configuration parameters, solves the Vehicle Routing Problem (VRP) in a stateless manner using asynchronous background execution. Returns a request tracking object that allows you to monitor the optimization process status. Once processing is complete, retrieve the solution using the /optimize/{id}/solution endpoint. The solution consists of one or more routes, where each route represents the trip that a vehicle travels to visit the assigned orders. The maximum number of routes returned equals the number of vehicles provided in the optimization request.
Workflow
After submitting an optimization request, you'll receive a request tracking object. Use the returned ID to monitor status and retrieve the final solution once processing is complete.
- Method:
POST - Endpoint:
/optimize - Headers:
Authorization: YOUR_API_KEYContent-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/optimize - Returned error codes:
| Error Code | Description |
|---|---|
200 Successful | Successful operation. |
400 Bad Request | Invalid input or missing required fields. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | No solution found, please try changing the constraints, or adding more vehicles, there may be more possibilities. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
warning
Input Requirements for Optimization
When sending a request for route optimization, the following constraints must be respected:
Orders
- Each order must include a valid set of coordinates.
- For each order’s
timeWindows, the end time must be greater than the start time. - RoundRoute: requires at least 1 order and 1 departure.
- CustomEnd: requires at least 1 order, 1 departure, and 1 destination.
- EndAnywhere: requires at least 2 orders and 1 departure.
More details on
route type: Configuration Parameters
Vehicles
- At least 1 vehicle must be defined.
- Vehicle type is mandatory and cannot be empty.
- Each vehicle’s
startTimemust always be less than itsendTime. - Vehicle constraints must be provided either:
- One globally (applies to all vehicles), or
- Individually for each vehicle (same number of constraints as vehicles). More details: Vehicle Constraints
⚠️ If any of these requirements are not met, the solver will return an input error:
400 - Bad Request (Invalid input or missing required fields).
Example:
- Request Body:
- Schema View
- JSON Example
- JSON View
- ▶
configurationParameters(object)Configuration parameters for the optimization. - ▶
departures(array[object])List of departure locations for the optimization. - ▶
destinations(array[object])List of destination locations for the optimization (optional). - ▶
orders(array[object])List of orders to optimize. - ▶
vehicles(array[object])List of vehicles assigned to the optimization. - ▶
vehiclesConstraints(array[object])List of vehicle constraints applied in the optimization. matrixBuildType(integer)Defines how the distance matrix is built. Possible values:0- Set by user using 'matrices' fieldmatricesfield1- Real road map distances and times (default) distances and times
matrices(array[object])Contains distance and time matrices, required when matrixBuildType is set to 0 (optional).
{
"configurationParameters": {
"name": "Paris - test optimization",
"ignoreTimeWindow": false,
"allowDroppingOrders": false,
"groupingOrders": false,
"balancedRoutes": 0,
"optimizationCriterion": 0,
"arrangeCriterion": 0,
"optimizationQuality": 2,
"maxTimeToOptimize": 300,
"maxWaitTime": 18000,
"routeType": 0,
"restrictions": 0,
"distanceUnit": 0,
"orderSequenceOptions": []
},
"orders": [
{
"alias": "Customer 1",
"location": [
48.870852,
2.356148
],
"type": 0,
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"revenue": 0,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 2",
"location": [
48.827327,
2.342267
],
"type": 0,
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"revenue": 0,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 3",
"location": [
48.88025,
2.299601
],
"type": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"timeWindow": [
770,
1020
],
"serviceTime": 0,
"revenue": 12,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 4",
"location": [
48.845198,
2.402896
],
"type": 1,
"numberOfPackages": 8,
"weight": 15.4,
"cube": 5.8,
"timeWindow": [
753,
1036
],
"serviceTime": 0,
"revenue": 2.7,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 5",
"location": [
48.897163,
2.292865
],
"type": 0,
"numberOfPackages": 9,
"weight": 16.2,
"cube": 8.4,
"timeWindow": [
736,
1086
],
"serviceTime": 0,
"revenue": 7.5,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 6",
"location": [
48.90092,
2.400039
],
"type": 1,
"numberOfPackages": 9,
"weight": 16.5,
"cube": 9.7,
"timeWindow": [
786,
1053
],
"serviceTime": 0,
"revenue": 10,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 7",
"location": [
48.860914,
2.310625
],
"type": 0,
"numberOfPackages": 5,
"weight": 7.5,
"cube": 2.6,
"timeWindow": [
820,
1020
],
"serviceTime": 0,
"revenue": 13.4,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 8",
"location": [
48.827865,
2.379216
],
"type": 1,
"numberOfPackages": 11,
"weight": 12.1,
"cube": 4.6,
"timeWindow": [
753,
1086
],
"serviceTime": 0,
"revenue": 14.7,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 9",
"location": [
48.887096,
2.283513
],
"type": 1,
"numberOfPackages": 6,
"weight": 5.2,
"cube": 1.5,
"timeWindow": [
770,
1070
],
"serviceTime": 0,
"revenue": 2.9,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 10",
"location": [
48.896894,
2.321586
],
"type": 0,
"numberOfPackages": 13,
"weight": 6.3,
"cube": 7.5,
"timeWindow": [
836,
1053
],
"serviceTime": 0,
"revenue": 8.1,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 11",
"location": [
48.870449,
2.342204
],
"type": 0,
"numberOfPackages": 10,
"weight": 8,
"cube": 4.1,
"timeWindow": [
903,
1020
],
"serviceTime": 0,
"revenue": 6.2,
"priority": 0,
"customData": ""
},
{
"alias": "Customer 12",
"location": [
48.895658,
2.344043
],
"type": 0,
"numberOfPackages": 6,
"weight": 4.8,
"cube": 11.5,
"timeWindow": [
870,
1020
],
"serviceTime": 0,
"revenue": 2.3,
"priority": 0,
"customData": ""
}
],
"departures": [
{
"alias": "Depot 1",
"location": [
48.870569,
2.356448
]
},
{
"alias": "Depot 2",
"location": [
48.82674,
2.342116
]
}
],
"destinations": [],
"vehicles": [
{
"name": "Car vehicle 1",
"type": 0,
"maxLoadWeight": 60,
"maxLoadCube": 50,
"startTime": 420,
"endTime": 1439,
"licensePlate": "AA-123-AA",
"consumption": 6.5
},
{
"name": "Car vehicle 2",
"type": 0,
"maxLoadWeight": 60,
"maxLoadCube": 50,
"startTime": 420,
"endTime": 1439,
"licensePlate": "AA-124-AA",
"consumption": 6.5
}
],
"vehiclesConstraints": [
{
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 99999999,
"maxRevenue": 85
}
],
"matrixBuildType": 1
}
{
"configurationParameters": {
"name": "string",
"ignoreTimeWindow": false,
"allowDroppingOrders": false,
"groupingOrders": false,
"balancedRoutes": 0,
"optimizationCriterion": 0,
"arrangeCriterion": 0,
"optimizationQuality": 0,
"maxTimeToOptimize": 0,
"maxWaitTime": 0,
"routeType": 0,
"restrictions": 0,
"distanceUnit": 0,
"orderSequenceOptions": []
},
"orders": [
{
"alias": "string",
"location": [
0,
0
],
"type": 0,
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"timeWindow": [
0,
0
],
"serviceTime": 0,
"revenue": 0,
"priority": 0,
"customData": "string"
}
],
"departures": [
{
"alias": "string",
"location": [
0,
0
]
}
],
"destinations": [
{
"alias": "string",
"location": [
0,
0
]
}
],
"vehicles": [
{
"name": "string",
"type": 0,
"maxLoadWeight": 0,
"maxLoadCube": 0,
"startTime": 0,
"endTime": 1439,
"licensePlate": "string",
"consumption": 0
}
],
"vehiclesConstraints": [
{
"startDate": 0,
"maxNumberOfPackages": 0,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 0,
"minDistance": 0,
"maxDistance": 0,
"maxRevenue": 0
}
],
"matrixBuildType": 1
}
- Response Body: (error code
200)
- Schema View
- JSON Example
- JSON View
id(integer)Unique identifier for the request.optimizationId(integer)The ID of the associated optimization. Only present for optimization requests.routeId(integer)The ID of the associated route. Only present for route requests.status(integer)Current status of the request:0- Created1- Pending2- Finished3- Canceledmessage(string)Status message for the request.creationTimestamp(integer)Timestamp when the request was created.
{
"id": 23567,
"solutionId": 46587,
"status": 0,
"message": "Operation running...please wait!",
"creationTimestamp": 1747786578
}
{
"id": 0,
"solutionId": 0,
"status": 0,
"message": "string",
"creationTimestamp": 0
}
2. Get Solution
Description: Retrieves the solution for a previously submitted /optimize request using the request ID. This endpoint is used after submitting an optimization request to get the final routing solution once processing is complete.
-
Method:
GET -
Endpoint:
/optimize/{id}/solution -
Headers:
Authorization: YOUR_API_KEYContent-Type: application/json
-
URL:
https://fleetmanagement.magiclaneapis.com/v1/optimize/{id}/solution -
Path Parameter:
id(integer, *required) - The ID returned from the initial/optimizereq
-
Returned error codes:
| Error Code | Description |
|---|---|
200 Successful | Successful operation, solution retrieved. |
400 Bad Request | Invalid requestId or missing required parameters. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Request ID not found or optimization not completed. |
405 Method Not Allowed | Incorrect method type. |
425 Too Early | Request not finished. |
500 Internal Server Error | Database error occurred. |
Note
This endpoint is used in conjunction with the /optimize endpoint. After submitting an optimization request, use the returned requestId to retrieve the solution once processing is complete.
Example:
- Response Body: (error code
200)
- Schema View
- JSON Example
- JSON View
- ▶
drpppedOrders(array[object])List of orders excluded from the optimization because no feasible solution was found. - ▶
routes(array[object])List of optimized routes
{
"droppedOrders": [],
"routes": [
{
"orders": [
{
"alias": "Customer 11",
"location": [
48.870852,
2.356148
],
"matchedLocation": [
48.8701825,
2.3423565625
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 10,
"weight": 8,
"cube": 4.1,
"revenue": 6.2,
"serviceTime": 0,
"timeWindow": [
903,
1020
],
"indexInRoute": 0,
"indexInOptimization": 10,
"arrivalTime": 1596812580000,
"waitTime": 0,
"numberOfPackagesAtArrival": 34,
"weightAtArrival": 49.2,
"cubeAtArrival": 21.6,
"traveledDistance": 1.4171849,
"revenueAtArrival": 0,
"deliveredNumberOfPackages": 10,
"deliveredWeight": 8,
"deliveredCube": 4.1,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 6",
"location": [
48.827327,
2.342267
],
"matchedLocation": [
48.9005959375,
2.4000475
],
"type": 1,
"priority": 0,
"customData": "",
"numberOfPackages": 9,
"weight": 16.5,
"cube": 9.7,
"revenue": 10,
"serviceTime": 0,
"timeWindow": [
786,
1053
],
"indexInRoute": 1,
"indexInOptimization": 5,
"arrivalTime": 1596813655241,
"waitTime": 0,
"numberOfPackagesAtArrival": 44,
"weightAtArrival": 57.2,
"cubeAtArrival": 25.7,
"traveledDistance": 7.2696328,
"revenueAtArrival": 6.2,
"collectedNumberOfPackages": 9,
"collectedWeight": 16.5,
"collectedCube": 9.7,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 4",
"location": [
48.88025,
2.299601
],
"matchedLocation": [
48.8452625,
2.4027009375
],
"type": 1,
"priority": 0,
"customData": "",
"numberOfPackages": 8,
"weight": 15.4,
"cube": 5.8,
"revenue": 2.7,
"serviceTime": 0,
"timeWindow": [
753,
1036
],
"indexInRoute": 2,
"indexInOptimization": 3,
"arrivalTime": 1596814512563,
"waitTime": 0,
"numberOfPackagesAtArrival": 35,
"weightAtArrival": 40.7,
"cubeAtArrival": 16,
"traveledDistance": 13.1220808,
"revenueAtArrival": 16.2,
"collectedNumberOfPackages": 8,
"collectedWeight": 15.4,
"collectedCube": 5.8,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 8",
"location": [
48.845198,
2.402896
],
"matchedLocation": [
48.82792,
2.3791415625
],
"type": 1,
"priority": 0,
"customData": "",
"numberOfPackages": 11,
"weight": 12.1,
"cube": 4.6,
"revenue": 14.7,
"serviceTime": 0,
"timeWindow": [
753,
1086
],
"indexInRoute": 3,
"indexInOptimization": 7,
"arrivalTime": 1596815042263,
"waitTime": 0,
"numberOfPackagesAtArrival": 27,
"weightAtArrival": 25.3,
"cubeAtArrival": 10.2,
"traveledDistance": 18.9745293,
"revenueAtArrival": 18.9,
"collectedNumberOfPackages": 11,
"collectedWeight": 12.1,
"collectedCube": 4.6,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 7",
"location": [
48.897163,
2.292865
],
"matchedLocation": [
48.86112,
2.310630625
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 5,
"weight": 7.5,
"cube": 2.6,
"revenue": 13.4,
"serviceTime": 0,
"timeWindow": [
820,
1020
],
"indexInRoute": 4,
"indexInOptimization": 6,
"arrivalTime": 1596816069637,
"waitTime": 0,
"numberOfPackagesAtArrival": 16,
"weightAtArrival": 13.2,
"cubeAtArrival": 5.6,
"traveledDistance": 24.8269768,
"revenueAtArrival": 33.6,
"deliveredNumberOfPackages": 5,
"deliveredWeight": 7.5,
"deliveredCube": 2.6,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 3",
"location": [
48.90092,
2.400039
],
"matchedLocation": [
48.8802215625,
2.2997153125
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"serviceTime": 0,
"timeWindow": [
770,
1020
],
"indexInRoute": 5,
"indexInOptimization": 2,
"arrivalTime": 1596816563007,
"waitTime": 0,
"numberOfPackagesAtArrival": 21,
"weightAtArrival": 20.7,
"cubeAtArrival": 8.2,
"traveledDistance": 30.6794243,
"revenueAtArrival": 47,
"deliveredNumberOfPackages": 3,
"deliveredWeight": 5.1,
"deliveredCube": 2.5,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 9",
"location": [
48.860914,
2.310625
],
"matchedLocation": [
48.886894375,
2.2838003125
],
"type": 1,
"priority": 0,
"customData": "",
"numberOfPackages": 6,
"weight": 5.2,
"cube": 1.5,
"revenue": 2.9,
"serviceTime": 0,
"timeWindow": [
770,
1070
],
"indexInRoute": 6,
"indexInOptimization": 8,
"arrivalTime": 1596816932267,
"waitTime": 0,
"numberOfPackagesAtArrival": 24,
"weightAtArrival": 25.8,
"cubeAtArrival": 10.7,
"traveledDistance": 36.5318718,
"revenueAtArrival": 59,
"collectedNumberOfPackages": 6,
"collectedWeight": 5.2,
"collectedCube": 1.5,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 5",
"location": [
48.827865,
2.379216
],
"matchedLocation": [
48.89706375,
2.29247
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 9,
"weight": 16.2,
"cube": 8.39,
"revenue": 7.5,
"serviceTime": 0,
"timeWindow": [
736,
1086
],
"indexInRoute": 7,
"indexInOptimization": 4,
"arrivalTime": 1596817262381,
"waitTime": 0,
"numberOfPackagesAtArrival": 18,
"weightAtArrival": 20.6,
"cubeAtArrival": 9.2,
"traveledDistance": 42.3843193,
"revenueAtArrival": 61.9,
"deliveredNumberOfPackages": 9,
"deliveredWeight": 16.2,
"deliveredCube": 8.39,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 10",
"location": [
48.887096,
2.283513
],
"matchedLocation": [
48.8971759375,
2.321263125
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 13,
"weight": 6.3,
"cube": 7.5,
"revenue": 8.1,
"serviceTime": 0,
"timeWindow": [
836,
1053
],
"indexInRoute": 8,
"indexInOptimization": 9,
"arrivalTime": 1596817690016,
"waitTime": 0,
"numberOfPackagesAtArrival": 27,
"weightAtArrival": 36.8,
"cubeAtArrival": 17.59,
"traveledDistance": 48.2367668,
"revenueAtArrival": 69.4,
"deliveredNumberOfPackages": 13,
"deliveredWeight": 6.3,
"deliveredCube": 7.5,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 12",
"location": [
48.896894,
2.321586
],
"matchedLocation": [
48.8958034375,
2.3440403125
],
"type": 0,
"priority": 0,
"customData": "",
"numberOfPackages": 6,
"weight": 4.8,
"cube": 11.5,
"revenue": 2.3,
"serviceTime": 0,
"timeWindow": [
870,
1020
],
"indexInRoute": 9,
"indexInOptimization": 11,
"arrivalTime": 1596817984460,
"waitTime": 0,
"numberOfPackagesAtArrival": 40,
"weightAtArrival": 43.1,
"cubeAtArrival": 25.09,
"traveledDistance": 54.0892143,
"revenueAtArrival": 77.5,
"deliveredNumberOfPackages": 6,
"deliveredWeight": 4.8,
"deliveredCube": 11.5,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
},
{
"alias": "Customer 1",
"location": [
48.870449,
2.342204
],
"matchedLocation": [
48.8707784375,
2.3565665625
],
"type": 1,
"priority": 0,
"customData": "",
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
420,
1086
],
"indexInRoute": 10,
"indexInOptimization": 0,
"arrivalTime": 1596818617911,
"waitTime": 0,
"numberOfPackagesAtArrival": 46,
"weightAtArrival": 47.9,
"cubeAtArrival": 36.59,
"traveledDistance": 59.9416618,
"revenueAtArrival": 79.8,
"collectedNumberOfPackages": 0,
"collectedWeight": 0,
"collectedCube": 0,
"distanceToNextOrder": 5.8524479866,
"timeToNextOrder": 972
}
],
"departure": {
"alias": "Depot 2",
"location": [
48.82679375,
2.3420853125
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 1596783600000,
"timeToNext": 12122,
"distanceToNext": 1.1342
},
"destination": {
"alias": "Depot 2",
"location": [
48.82679375,
2.3420853125
],
"matchedLocation": [
48.82679375,
2.3420853125
],
"arrivalTime": 1596818617911
},
"vehicle": {
"name": "Car vehicle 1",
"type": 0,
"maxLoadWeight": 60,
"maxLoadCube": 50,
"startTime": 420,
"endTime": 1439,
"licensePlate": "AA-123-AA",
"consumption": 6.5
},
"vehicleConstraints": {
"startDate": 1596758400000,
"maxNumberOfPackages": 53,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 99999999,
"minDistance": 0,
"maxDistance": 99999999,
"maxRevenue": 85
},
"totalDistance": 65.7941,
"totalTime": 1597135480,
"totalServiceTime": 0,
"totalWaitTime": 0,
"creationTimestamp": 1756296705030,
"neededFuel": 4.2766175,
"matrixBuildType": 1
}
]
}
{
"droppedOrders": [
{
"alias": "string",
"location": [
0,
0
],
"type": 0,
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"timeWindow": [
0,
0
],
"serviceTime": 0,
"revenue": 0,
"priority": 0,
"customData": "string"
}
],
"routes": [
{
"orders": [
{
"alias": "string",
"location": [
0,
0
],
"matchedLocation": [
0,
0
],
"type": 0,
"priority": 0,
"customData": "string",
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"revenue": 0,
"serviceTime": 0,
"timeWindow": [
0,
0
],
"indexInRoute": 0,
"indexInOptimization": 0,
"arrivalTime": 0,
"waitTime": 0,
"numberOfPackagesAtArrival": 0,
"weightAtArrival": 0,
"cubeAtArrival": 0,
"traveledDistance": 0,
"revenueAtArrival": 0,
"deliveredNumberOfPackages": 0,
"deliveredWeight": 0,
"deliveredCube": 0,
"distanceToNextOrder": 0,
"timeToNextOrder": 0
}
],
"departure": {
"alias": "string",
"location": [
0,
0
],
"matchedLocation": [
0,
0
],
"numberOfPackages": 0,
"weight": 0,
"cube": 0,
"departureTime": 0,
"timeToNext": 0,
"distanceToNext": 0
},
"destination": {
"alias": "string",
"location": [
0,
0
],
"matchedLocation": [
0,
0
],
"arrivalTime": 0
},
"vehicle": {
"name": "string",
"type": 0,
"maxLoadWeight": 0,
"maxLoadCube": 0,
"startTime": 0,
"endTime": 1439,
"licensePlate": "string",
"consumption": 0
},
"vehicleConstraints": {
"startDate": 0,
"maxNumberOfPackages": 0,
"minNumberOfOrders": 0,
"maxNumberOfOrders": 0,
"minDistance": 0,
"maxDistance": 0,
"maxRevenue": 0
},
"totalDistance": 0,
"totalTime": 0,
"totalServiceTime": 0,
"totalWaitTime": 0,
"creationTimestamp": 0,
"neededFuel": 0,
"matrixBuildType": 1
}
]
}
3. Optimize landmarks
Description: Receives a list of coordinates and a vehicle type, then optimizes them by creating a route for the given coordinates.
- Method:
POST - Endpoint:
/optimize/landmarks - Headers:
Authorization: YOUR_API_KEYContent-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/optimize/landmarks - Returned error codes:
| Error Code | Description |
|---|---|
200 Successful | Successful operation. |
400 Bad Request | Invalid input or missing required fields. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | No solution found, please try changing the constraints, or adding more vehicles, there may be more possibilities. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
warning
Input Requirements for Landmark Optimization
When sending a request for a landmark optimization, the following constraints must be respected:
- A minimum of 3 points is required.
- The first point is always treated as the starting point (departure).
- The route type is
EndAnywhere, the last point in the optimized route is treated as destination. - Vehicle type is mandatory for route calculation and must not be empty.
More details on route type: Configuration Parameters
⚠️ If any of these requirements are not met, the solver will return an input error:
400 - Bad Request (Invalid input or missing required fields).
Example:
- Request Body:
- Schema View
- JSON Example
- JSON View
vehicleType(integer)Vehicle type - Specifies the vehicle's type.0- Car1- Pedestrian2- E-Bike3- Truck4- Bike- ▶
locations(array[object])List of coordinates that will be optimized to determine the best route.
{
"vehicleType": 1,
"locations": [
[48.869900, 2.344389],
[48.870214, 2.358400],
[48.868321, 2.341789],
[48.873201, 2.350999],
[48.867842, 2.351328],
[48.866749, 2.354210],
[48.869123, 2.357890],
[48.865234, 2.346721],
[48.872830, 2.360402],
[48.871567, 2.349012]
]
}
{
"vehicleType": 0,
"locations": [
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0],
[0.0, 0.0]
]
}
- Response Body: (error code
200)
- Schema View
- JSON Example
- JSON View
locationIndexes(array[integer])Array of reordered indexes representing the optimized sequence.
Values:
• Non-negative integers (0 to n-1): Position in optimized sequence
•-1: Unassigned/dropped locationdroppedIndexes(array[integer])List of indexes of the orders excluded from the optimization because no feasible solution was found.
{
"locationIndexes": [9, 3, 0, 2, 7, 4, 5, 6, 1, 8]
"droppedIndexes": []
}
{
"locationIndexes": [-1, -1, -1, -1, -1, -1, -1, -1],
"droppedIndexes": [-1, -1]
}