# Documentation Export Generated from MDX files in docs Export date: 2025-07-08 10:40:00 Total files: 14 This file contains the complete documentation converted from MDX format to a single text file optimized for LLM consumption. ================================================================================ # 1_Introduction/01_Introduction.mdx # Fleet Management RestAPI [ReadingTime] [br] ## Introduction **The Fleet Management RestAPI**, is a powerful and flexible solution for optimizing and managing your fleet operations. This API is designed to streamline route planning, order fulfillment, and vehicle assignments by leveraging **Vehicle Routing Problem (VRP)** optimization. Whether you are managing deliveries, service operations, or logistics, our API provides all the tools you need to maximize efficiency and minimize costs. ## Feature list **The Fleet Management RestAPI** is designed to handle a wide variety of logistics, routing, and optimization tasks, providing robust support for fleet operations. Below is an overview of the key features: ### 1. Customers and Orders - **Customer Management**: - Add, retrieve, update, and delete customer profiles. - Manage customer contact information, such as email, phone number, and address. - Associate custom data with customers for additional information. - **Order Management**: - Add, retrieve, update, and delete orders. - Support for order types: **Pickup** and **Delivery**. - Define order attributes: - Time windows (start and end times). - Priority levels: **Low** or **High**. - Parcel details: weight, volume and number of packages. - Customizable service times per order. - Sequence orders into specific routes or enforce delivery sequences. ### 2. Vehicles - **Vehicle Management**: - Add, retrieve, update, and delete vehicles. - Define vehicles by type: **Car**, **Truck**, **Bike**, **E-bike**, or **Pedestrian**. - Manage vehicle attributes: - Maximum load weight and volume. - Fuel type and consumption rates. - Physical dimensions: height, width, length, and axle load. (only for truck) - Operating costs (fixed and hourly). - Track vehicle availability and statuses (e.g., Available, En Route). - Assign vehicles to routes based on constraints and optimization results. - **Vehicle Constraints**: - Specify start and end times for vehicle operations. - Define maximum distance, number of orders, or packages for all vehicles or for each vehicle. ### 3. Territories - **Territory Management**: - Add, retrieve, update, and delete territories. - Define operational territories with different shapes: **Polygon**, **Circle**, or **Rectangle**. - Retrives orders inside territories, helps territory-based routing. - Customize territory colors for easier visualization. ### 4. Fleet Optimization - **Optimization Goals**: - Optimize routes based on distance or time. - **Route Types**: - Round routes (start and end at the same location). - End-anywhere routes (routes that end at the most efficient destination). - Custom endpoints for routes. - **Configuration Options**: - Set optimization quality: **Unoptimized**, **Fast**, **Optimized**, or **Best**. - Define matrix-building types for distance and time calculations: - User-defined or real-world driving metrics. - Specify road restrictions: - Avoid toll roads or highways "TBD". - **Fuel and Cost Efficiency**: - Incorporate fuel prices for multiple fuel types: Diesel Standard/Premium, Gasoline Standard/Premium, LPG, Electric. - Calculate route costs based on vehicle consumption and distance. - **Order Sequencing**: - Group orders into fixed or flexible sequences. - Enforce pickup and delivery pairings for specific use cases. - **Real-Time Operations**: - Reoptimize routes dynamically in response to changes. - Monitor vehicle progress, arrival times, and wait times. - **Custom Constraints**: - Allow dropped orders if no feasible solution is found. - Enable grouping of nearby orders for clustering efficiency. - Balance routes by time or the number of orders. ### 5. Reporting and Insights - **Performance Metrics**: - Total travel distance, duration, and service times per route. - Fuel consumption and cost estimations for each route. - Order-level details: delivery statuses, waiting times, and package counts. - **Export Options**: - Export routes in multiple formats, such as GPX or database files. ### 6. API Flexibility - **Async Operations**: - Perform asynchronous optimizations, order updates, and route reassignments. - **Error Handling**: - Detailed error messages and codes for debugging failed requests. - **Customization**: - Flexible configuration parameters to tailor optimizations to your business needs. ### 🚀 Step-by-Step Guide: Creating an Optimization --- :::info 📌 **Order of Operations: Visual Flow** ```mermaid graph LR A[👤 Customers] --> B[📦 Orders] B --> C[🚚 Vehicles] C --> D[⚙️ Optimization] D --> E[📊 Solution] ``` ::: --- ### Step 1: Add Customers and Orders Before optimizing routes, you need to define *who* is involved and *what* needs to be delivered or picked up. #### 🧑‍💼 Create Customers Customers are the people or organizations placing orders. Each order must be linked to a customer using their `customerId`. * **API Endpoint:** `POST /customers` * **Request:** An array of customer objects * **Response:** Returns customer objects with system-generated `id`s #### 📦 Create Orders Orders define what is being delivered or picked up, and include location, time windows, priorities, and a `customerId`. * **API Endpoint:** `POST /orders` * **Request:** An array of order objects * **Response:** Returns order objects with system-generated `id`s --- ### Step 2: Add Vehicles and Constraints Vehicles represent your delivery or pickup fleet. Each vehicle can have specific limits or rules, known as constraints. #### 🚚 Create Vehicles Each vehicle will be used in route planning and must be created before optimization. * **API Endpoint:** `POST /vehicles` * **Request:** An array of vehicle objects * **Response:** Returns vehicle objects with system-generated `id`s #### 📏 Define Vehicle Constraints These rules ensure routes stay within each vehicle’s capabilities, such as: * Maximum capacity * Maximum distance * Revenue or delivery limitations --- ### Step 3: Set Optimization Parameters Define settings that control how the optimization engine works. These can include: * Optimization goals (e.g., minimize distance, time) * Maximum search time * Flexibility options This step fine-tunes how the system balances different priorities. --- ### Step 4: Define Departures and Destinations Set the start and end points for each vehicle’s route. * **Departures:** Starting locations for vehicles. Affect travel time and routing logic. * **Destinations:** Final stops for vehicles. Help ensure the most efficient route end-points. These can be specific locations or rules (e.g., return to depot). --- ### Step 5: Create the Optimization This is where everything comes together — customers, orders, vehicles, and parameters — to define the full routing problem. * **API Endpoint:** `POST /optimizations` * **Request:** An object that includes orders, vehicles, constraints, and optimization settings * **Response:** Returns an `optimizationId` and `requestId` to track the process --- ### Step 6: Retrieve the Optimized Solution Once the system has finished processing, fetch the optimized routes. * **API Endpoint:** `GET /optimizations/{id}/solution` * **Response:** A list of optimized routes for the fleet, based on the submitted data --- # 1_Introduction/02_Get_started.mdx # Get Started [ReadingTime] [br][br] This section will guide you on how to interact with the **Fleet Management RestAPI** by explaining what an API request is, how to include an API key, and what a request looks like. ## What is an API Request? An API request is how you interact with the Fleet Management API. It's a structured HTTP message that allows your application to retrieve or send data to the server. Each request typically consists of: - **Endpoint URL**: The specific address of the resource you are interacting with, such as `/customers` or `/vehicles`. - **HTTP Method**: The action you want to perform (e.g., GET, POST, PUT, DELETE). - **Headers**: Information like your API key for authentication and content types. - **Request Body (for POST/PUT)**: Data sent to the API in JSON format. ## How to Use an API Key The Fleet Management API requires an API key to authenticate requests. Without it, the server will respond with a `401 Unauthorized` error. The API key is sent in the request headers as follows: - **Header Name**: `Authorization` - **Header Value**: `` ## Example Request with API Key Here's a simple example of a request to retrieve all customers: ### Request Details: - **Endpoint**: `https://fleetmanagement.magiclaneapis.com/v1/customers` - **Method**: `GET` - **Headers**: - `Authorization: ` - `Content-Type: application/json` ### Request Example (cURL): ```sh curl -X GET "https://fleetmanagement.magiclaneapis.com/v1/customers" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` ## Authentication with API Key Every Magic Lane SDK instance requires a unique API Key for authentication. Here's how to create an account, generate an API key, and integrate it into your requests. :::danger[Warning] Ensure that the API key remains secure and is not exposed. If the key is compromised or its integrity is uncertain, promptly revoke it and generate a new one to maintain security and prevent unauthorized usage that may incur additional costs. ::: ### Create your account Go to the Magic Lane [registration/sign up page](https://developer.magiclane.com/api/login) to create a free account. You only need to type in your email address and choose a new password. Optionally, you can also enter your name and company.\ ![Register image](_images/register.png "Register") Click the `Get started` button after reviewing the terms of service and privacy policy. You will get a confirmation email with a link to activate your account. After you activate your account by clicking on the link you received, you can sign in! ![Sign in image](_images/signin.png "Sign in") Go to the Magic Lane [login page](https://developer.magiclane.com/api/login) to sign in to your new account. Type your complete email address, which you used to create the account, and the password you created when you signed up in the previous step. ## Create a project Once logged in, you are on your [Dashboard](https://developer.magiclane.com/api/dashboard) page. Click the [Projects](https://developer.magiclane.com/api/projects) tab. ![Navbar My Projects image](_images/private-navbar-projects-selected.png "Projects") On the My Projects page, click the `Create project` button from the top-right side of the page. A dialog appears, where you can type a name for the new project, and a short description. When done, click `Create project`. ![Create project modal image](_images/create-project-modal.png "Create project modal") ## Create an API Key The project is created with an API key with a short expiration date. ![Project API Keys image](_images/project-api-keys.png "Project API Keys") Click `Generate additional API Key` to create another key for your project, where you can set an expiration date further into the future. ![Generate API Key modal image](_images/generate-api-key-modal.png "Generate API Key modal") You can give the new API key a different name, and set any expiration date you want. Click `Generate` to generate the API key. :::danger[Warning] Ensure that key management is properly planned and that the key on the client’s device is updated before its expiration date. Failure to do so will result in a watermark being displayed on the map and certain features becoming limited once the key has expired. ::: ![Project page image](_images/project-page.png "Project page") You just created your first project and Magic Lane API Key! You can click on the copy button to the right of the API Key to copy it, and then paste it in your code. # 2_Core_Concepts/011_Template.mdx # Template Parameters [ReadingTime] [br] ## Overview The **Template RestAPI** allows you to manage templates within the Fleet Management system. You can create, retrieve, update, and delete templates. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. **Template Parameters** are used solely for **storing configuration data** as reusable templates. These templates can later be retrieved and applied to operations, enabling consistent and efficient reuse of pre-defined settings. ### Template Parameters Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the template.** **name** **String** **Name of the template.** **ignoreTimeWindow** **Boolean** **Whether to ignore the time window. Default: false.** **balancedRoutes** **Boolean** **Whether the routes should have a similar number of orders.** **optimizationCriterion** **Integer** **arrangeCriterion** **Integer** **optimizationQuality** **Integer** **maxTimeToOptimize** **Integer** **Maximum time (seconds) for optimization (only used if optimization quality is Best). Default: 300.** **maxWaitTime** **Integer** **Maximum wait time (seconds) before arriving at the next order. Default: 99999999.** **routeType** **Integer** **matrixBuiltType** **Integer** **restrictions** **Integer** **vehicleCategory** **Integer** **sameDepartureForAll** **Boolean** **Whether all routes share the same departure point. Default: false.** **sameDestinationForAll** **Boolean** **Whether all routes share the same destination. Default: false.** **sameVehicleConstraintsForAll** **Boolean** **Whether all vehicles share the same constraints. Default: false.**
**Optimization criterion:** **0 - Distance** **1 - Time (default)**
**Order arrangement criterion (used only if optimizing by distance):** **0 - Matrix (default)** **1 - Euclidean** **2 - Exact Euclidean** **3 - Manhattan**
**Optimization quality:** **0 - Unoptimized** **1 - Fast** **2 - Optimized (default)** **3 - Best**
**Route type:** **0 - Round Route (default)** **1 - End Anywhere** **2 - Custom End**
**Matrix build type:** **0 - Set by user using "matrices" field** **1 - Real road distances and times**
**Road restrictions:** **0 - None (default)** **1 - Tolls** **2 - Highways**
**Vehicle category:** **0 - None Electric (default)** **1 - Electric**
--- ## Endpoints ### 1. Create Template Parameters **Description:** Adds a new template to the database. - **Method:** `POST` - **Endpoint:** `/templates` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/templates` - **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.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Template Parameters` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddTemplateParameters, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetTemplateParameters, null, 2)}
--- ### 2. Get All Templates Parameters **Description:** Fetches a list of all templates with optional filtering. - **Method:** `GET` - **Endpoint:** `/templates` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/templates` - **Query Parameters:** - `search` (string, *optional*) – General search term across optimizations. - `id` (string, *optional*) – Filter by optimization ID (`id=value:exact` for exact match). - `name` (string, *optional*) – Filter by optimization name (`name=value:exact` for exact match). - `creationTime` (string, *optional*) – Filter by creation time (`creationTime=value:exact` for exact match). - `ignoreTimeWindow` (string, *optional*) – Filter optimizations that ignore time windows (`ignoreTimeWindow=value:exact` for exact match). - `balancedRoutes` (string, *optional*) – Determines if routes have a similar number of orders. - `routeType` (string, *optional*) – Filter by route type (`routeType=value`). - `vehicleCategory` (string, *optional*) – Filter by vehicle type (electric or non-electric). - `sameVehicleConstraints` (string, *optional*) – Determines if only one vehicle constraint will be used for all vehicles. - `sameDeparture` (string, *optional*) – Determines if all routes start from the same departure point. - `sameDestination` (string, *optional*) – Determines if all routes end at the same destination. - `sort` (string, *optional*) – Sorting format: – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, name, creationTime, ignoreTimeWindow, optimizeBy, optimizationQuality, maxOptimizeTime, routeType, matricesBuildType, restrictions, maxWaitTimeOrders, arrangeCriterion, balancedRoutes ` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **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.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetTemplatesParameters, null, 2)}
--- ### 3. Get a Template Parameters by ID **Description:** Retrieves a specific template by ID. - **Method:** `GET` - **Endpoint:** `/templates/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/templates/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique template ID. - **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** Template not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetTemplateParameters, null, 2)}
--- ### 4. Update a Template Parameters **Description:** Updates an existing template record. - **Method:** `PUT` - **Endpoint:** `/templates/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/templates/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique template ID. - **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** Template not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetTemplateParameters, null, 2)}
- **Response Body:** (error code `200`) ```json { "message": "Operation done successfully" } ``` --- ### 5. Delete Templates Parameters **Description:** Deletes templates from the system. - **Method:** `DELETE` - **Endpoint:** `/templates` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/templates` - **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** Can't delete template parameters because at least one of them does not exist.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "ids": [101, 102] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully" } ``` --- # 2_Core_Concepts/012_Request.mdx # Request [ReadingTime] [br] ## Overview The **Request RestAPI** allows you to manage requests within the Fleet Management system. You can create, retrieve, update, and delete request data. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. ### Request Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the request.** **optimizationId** **Integer** **routeId** **Integer** **status** **Integer** **message** **String** **Status message for the request.** **creationTimestamp** **Integer** **Timestamp when the request was created.**
The ID of the associated optimization.**** **Only available in the JSON response if the request is an optimization request.**
The ID of the associated route.**** **Only available in the JSON response if the request is a route request.**
**Current status of the request:** **0 - Created** **1 - Pending** **2 - Finished** **3 - Canceled**
--- ## Endpoints ### 1. Get All Requests **Description:** Fetches a list of all requests. - **Method:** `GET` - **Endpoint:** `/requests` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/requests` - **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.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "requests": [ { "id": 23412, "optimizationId": 32754, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1747834619 }, { "id": 23456, "routeId": 46578, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1745676643 }, { "id": 23567, "routeId": 46587, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1747786578 } ] } ```
--- ### 2. Get a Request by ID **Description:** Retrieves a specific request by ID. - **Method:** `GET` - **Endpoint:** `/requests/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/requests/{id}` - **Path Parameter:** - `id` (integer) - The unique request ID. - **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** Request not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`) :::info[note] In this example, the request contains only the routeId, which means it is a route request. :::
```json { "id": 23567, "routeId": 46587, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1747786578 } ```
--- ### 3. Cancel Request **Description:** Cancel request. - **Method:** `DELETE` - **Endpoint:** `/requests` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/requests` - **Path Parameter:** - `id` (integer) - The unique request ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** Request done, cannot be canceled anymore.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Request not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[note] When a request is canceled, the corresponding operation that the request is tracking is also canceled. This means that any ongoing processes or actions associated with this request will be stopped immediately, ensuring that no further progress is made on the task. ::: #### Example: - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully!" } ``` --- # 2_Core_Concepts/01_Customer.mdx # Customer [ReadingTime] [br] ## Overview The **Customer RestAPI** allows you to manage customer records within the Fleet Management system. You can create, retrieve, update, and delete customer data. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. ### Customer Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the customer.** **location** **Object** **Coordinates of the customer’s location.** **alias** **String** **Short name or identifier for the customer.** **firstName** **String** **Customer's first name.** **lastName** **String** **Customer's last name.** **address** **Object** **Detailed address information of the customer.** **email** **String** **Email address of the customer.** **phoneNumber** **String** **Customer's contact phone number.** **customData** **String**
**Additional customer-specific data.**
--- ## Endpoints ### 1. Create Customer **Description:** Adds a new customer to the database. The `id` field will be populated, it will return a list of customers with the id field populated - **Method:** `POST` - **Endpoint:** `/customers` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The customer does not have the coordinates set.** **The email set for the customer has wrong format.** **The phone number set for the customer has wrong format.**
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Customer` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddCustomers, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetCustomers, null, 2)}
--- ### 2. Get All Customers **Description:** Fetches a list of all customers with optional filtering. - **Method:** `GET` - **Endpoint:** `/customers` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers` - **Query Parameters:** - `search` (string, *optional*) – General search term across customers. - `id` (string, *optional*) – Filter by customer ID (`id=value:exact` for exact match). - `alias` (string, *optional*) – Filter by customer alias (`alias=value:exact` for exact match). - `firstName` (string, *optional*) – Filter by first name (`firstName=value:exact` for exact match). - `lastName` (string, *optional*) – Filter by last name (`lastName=value:exact` for exact match). - `location` (string, *optional*) – Filter by location (`location=value:exact` for exact match). - `country` (string, *optional*) – Filter by country (`country=value:exact` for exact match). - `state` (string, *optional*) – Filter by state (`state=value:exact` for exact match). - `county` (string, *optional*) – Filter by county (`county=value:exact` for exact match). - `city` (string, *optional*) – Filter by city (`city=value:exact` for exact match). - `postalCode` (string, *optional*) – Filter by postal code (`postalCode=value:exact` for exact match). - `streetName` (string, *optional*) – Filter by street name (`streetName=value:exact` for exact match). - `streetNumber` (string, *optional*) – Filter by street number (`streetNumber=value:exact` for exact match). - `extra` (string, *optional*) – Filter by extra address value (`extra=value:exact` for exact match). - `email` (string, *optional*) – Filter by email (`email=value:exact` for exact match). - `phoneNumber` (string, *optional*) – Filter by phone number (`phoneNumber=value:exact` for exact match). - `customData` (string, *optional*) – Filter by custom data (`customData=value:exact` for exact match). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, alias, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, email, phoneNumber, customData`. - `includeColumns` (string, *optional*) – Specify which columns to include. - Available columns: `id, alias, idAddress, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, email, phoneNumber, customData` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetCustomers, null, 2)}
--- ### 3. Get a Customer by ID **Description:** Retrieves a specific customer by ID. - **Method:** `GET` - **Endpoint:** `/customers/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique customer ID. - **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** Customer not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetCustomer, null, 2)}
--- ### 4. Update a Customer **Description:** Updates an existing customer record. - **Method:** `PUT` - **Endpoint:** `/customers/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers/{id}` - **Path Parameter:** - id (integer, **required*) - Customer ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The customer does not have the coordinates set.** **The email set for the customer has wrong format.** **The phone number set for the customer has wrong format.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Customer not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetCustomer, null, 2)}
- **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 5. Delete Customers **Description:** Deletes customers from the system. - **Method:** `DELETE` - **Endpoint:** `/customers` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers` - **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** Can't delete customers because at least one of them does not exist.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** -List of customer IDs to delete. ```json [12345, 23456, 34567] ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 6. Get Customer History **Description:** Retrieves the order history and associated optimizations for a specific customer. - **Method:** `GET` - **Endpoint:** `/customers/{id}/history` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/customers/{id}/history` **Path Parameter:** - `id` (integer, **required*) - The unique customer ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The customer was not found or its history couldn’t be retrieved.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Customer not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "history": [ { "order": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 0, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "optimizationsAndRoutes": [ { "optimization": { "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization" }, "id": 139950, "creationTimestamp": 1744096603789, "orders": [ { "revenue": 0, "serviceTime": 600, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603173, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933798, "location": [ 48.870852, 2.356148 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c0@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839505, "location": [ 48.870852, 2.356148 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 12, "serviceTime": 600, "timeWindow": [ 770, 1020 ], "creationTimestamp": 1744096603274, "cube": 2.5, "numberOfPackages": 3, "depotId": 0, "customData": "", "weight": 5.099999904632568, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933800, "location": [ 48.88025, 2.299601 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c2@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839507, "location": [ 48.88025, 2.299601 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 2.700000047683716, "serviceTime": 200, "timeWindow": [ 752, 1036 ], "creationTimestamp": 1744096603322, "cube": 5.800000190734863, "numberOfPackages": 8, "depotId": 0, "customData": "", "weight": 15.399999618530273, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 933801, "location": [ 48.845198, 2.402896 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c3@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839508, "location": [ 48.845198, 2.402896 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 7.5, "serviceTime": 600, "timeWindow": [ 736, 1086 ], "creationTimestamp": 1744096603391, "cube": 8.399999618530273, "numberOfPackages": 9, "depotId": 0, "customData": "", "weight": 16.200000762939453, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933802, "location": [ 48.897163, 2.292865 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c4@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839509, "location": [ 48.897163, 2.292865 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 10, "serviceTime": 900, "timeWindow": [ 786, 1053 ], "creationTimestamp": 1744096603435, "cube": 9.699999809265137, "numberOfPackages": 9, "depotId": 0, "customData": "", "weight": 16.5, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 933803, "location": [ 48.90092, 2.400039 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c5@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839510, "location": [ 48.90092, 2.400039 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 13.399999618530273, "serviceTime": 500, "timeWindow": [ 820, 1020 ], "creationTimestamp": 1744096603475, "cube": 2.5999999046325684, "numberOfPackages": 5, "depotId": 0, "customData": "", "weight": 7.5, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933804, "location": [ 48.860914, 2.310625 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c6@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839511, "location": [ 48.860914, 2.310625 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 14.699999809265137, "serviceTime": 750, "timeWindow": [ 753, 1086 ], "creationTimestamp": 1744096603514, "cube": 4.599999904632568, "numberOfPackages": 11, "depotId": 0, "customData": "", "weight": 12.100000381469727, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 933805, "location": [ 48.827865, 2.379216 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c7@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839512, "location": [ 48.827865, 2.379216 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 2.9000000953674316, "serviceTime": 800, "timeWindow": [ 770, 1070 ], "creationTimestamp": 1744096603555, "cube": 1.5, "numberOfPackages": 6, "depotId": 0, "customData": "", "weight": 5.199999809265137, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 933806, "location": [ 48.887096, 2.283513 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c8@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839513, "location": [ 48.887096, 2.283513 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 8.100000381469727, "serviceTime": 1000, "timeWindow": [ 836, 1053 ], "creationTimestamp": 1744096603595, "cube": 7.5, "numberOfPackages": 13, "depotId": 0, "customData": "", "weight": 6.300000190734863, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933807, "location": [ 48.896894, 2.321586 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c9@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839514, "location": [ 48.896894, 2.321586 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 6.199999809265137, "serviceTime": 850, "timeWindow": [ 903, 1020 ], "creationTimestamp": 1744096603640, "cube": 4.099999904632568, "numberOfPackages": 10, "depotId": 0, "customData": "", "weight": 8, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933808, "location": [ 48.870449, 2.342204 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c10@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839515, "location": [ 48.870449, 2.342204 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 2.299999952316284, "serviceTime": 600, "timeWindow": [ 870, 1020 ], "creationTimestamp": 1744096603690, "cube": 11.5, "numberOfPackages": 6, "depotId": 0, "customData": "", "weight": 4.800000190734863, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933809, "location": [ 48.895658, 2.344043 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c11@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839516, "location": [ 48.895658, 2.344043 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } } ], "vehicles": [ { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139812, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139812, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] } ], "departures": [ { "depotId": 0, "alias": "Departure1", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.870569, 2.356448 ], "matchedLocation": [ 2147483647, 2147483647 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 0, "timeToNext": 0, "distanceToNext": 0 }, { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 2147483647, 2147483647 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 0, "timeToNext": 0, "distanceToNext": 0 } ], "destinations": [], "vehiclesConstraints": [ { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 0 } ], "matrixBuildType": 1 }, "routes": [ { "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "optimizationId": 139950, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, "id": 255145 } ] } ] } ] } ```
--- # 2_Core_Concepts/02_Order.mdx # Order [ReadingTime] [br] ## Overview The **Order RestAPI** allows you to manage orders within the Fleet Management system. You can create, retrieve, update, and delete order records. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. ### Order Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the order.** **customerInfo** **Object** **Customer details linked to the order. Cannot be changed once saved.** **location** **Object** **Location details of the order.** **alias** **String** **Short name or identifier for the order.** **firstName** **String** **First name of the customer.** **lastName** **String** **Last name of the customer.** **address** **Object** **Address details of the order.** **phoneNumber** **String** **Contact number for the order.** **customData** **String** **Additional order-specific data.** **type** **Integer** **status** **Integer** **state** **Integer** **priority** **Integer** **numberOfPackages** **Integer** **Number of packages in the order.** **weight** **Float** **Total weight of the order.** **cube** **Float** **Total volume of the order.** **timeWindow** **Object** **Time window during which the order should be serviced.** **serviceTime** **Integer** **Time (in seconds) required to complete the order.** **revenue** **Float** **Revenue associated with the order.** **depotId** **Integer** **Depot associated with the order.** **creationTimestamp** **Integer** **Timestamp of when the order was created.**
**Order type:** **0 - Pickup** **1 - Delivery**
**Order status:** **0 - Unscheduled** **1 - Scheduled**
**Order state:** **0 - None** **1 - On Route** **2 - Servicing** **3 - Rejected** **4 - Completed** **5 - Failed**
**Order priority:** **0 - Low** **1 - High**
--- ## Endpoints ### 1. Create Order **Description:** Adds a list of orders to the database. - **Method:** `POST` - **Endpoint:** `/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/orders` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The order’s customer was not found/doesn’t exist.** **The order doesn’t have the coordinates set.** **The time window format is wrong.** **The number of packages/weight/cubic volume has a negative value or exceeds the maximum limit.** **The orders’ phone number has wrong format.**
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Order` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddOrders, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetOrders, null, 2)}
--- ### 2. Get All Orders **Description:** Fetches a list of all orders with optional filtering. - **Method:** `GET` - **Endpoint:** `/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/orders` - **Query Parameters:** - `search` (string, *optional*) – General search term across orders. - `id` (string, *optional*) – Filter by order ID (`id=value:exact` for exact match). - `alias` (string, *optional*) – Filter by order alias (`alias=value:exact` for exact match). - `firstName` (string, *optional*) – Filter by first name (`firstName=value:exact` for exact match). - `lastName` (string, *optional*) – Filter by last name (`lastName=value:exact` for exact match). - `location` (string, *optional*) – Filter by location (`location=value:exact` for exact match). - `country` (string, *optional*) – Filter by country (`country=value:exact` for exact match). - `state` (string, *optional*) – Filter by state (`state=value:exact` for exact match). - `county` (string, *optional*) – Filter by county (`county=value:exact` for exact match). - `city` (string, *optional*) – Filter by city (`city=value:exact` for exact match). - `postalCode` (string, *optional*) – Filter by postal code (`postalCode=value:exact` for exact match). - `streetName` (string, *optional*) – Filter by street name (`streetName=value:exact` for exact match). - `streetNumber` (string, *optional*) – Filter by street number (`streetNumber=value:exact` for exact match). - `extra` (string, *optional*) – Filter by extra address value (`extra=value:exact` for exact match). - `phoneNumber` (string, *optional*) – Filter by phone number (`phoneNumber=value:exact` for exact match). - `type` (string, *optional*) – Filter by order type. - `status` (string, *optional*) – Filter by order status. - `orderState` (string, *optional*) – Filter by order state. - `timeWindowStart` (string, *optional*) – Filter by time window start (`timeWindowStart=value:exact` for exact match). - `timeWindowEnd` (string, *optional*) – Filter by time window end (`timeWindowEnd=value:exact` for exact match). - `creationTime` (string, *optional*) – Filter by creation time (`creationTime=value:exact` for exact match). - `priority` (string, *optional*) – Filter by order priority. - `customData` (string, *optional*) – Filter by custom data (`customData=value:exact` for exact match). - `customerId` (string, *optional*) – Filter by customer ID (`customerId=value:exact` for exact match). - `depotId` (string, *optional*) – Filter by depot/misc location ID (`depotId=value:exact` for exact match). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, alias, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, phoneNumber, type, timeWindowStart, timeWindowEnd, creationTime, serviceTime, priority, customData, customerId, depotId` - `includeColumns` (string, *optional*) – Specify which columns to include. - Available columns: `id, alias, firstName, lastName, phoneNumber, type,timeWindowStart, timeWindowEnd, serviceTime, creationTime, packages, revenue, cube, weight, priority, status, orderState, customerId, depotId, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetOrders, null, 2)}
--- ### 3. Get an Order by ID **Description:** Retrieves a specific order by ID. - **Method:** `GET` - **Endpoint:** `/orders/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/orders/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique order ID. - **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** Order not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetOrder, null, 2)}
--- ### 4. Update an Order **Description:** Updates an existing order record. - **Method:** `PUT` - **Endpoint:** `/orders/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/orders/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique order ID. - **Query Parameter:** -`autoAssignDepot`(integer, *optional*) ( `0`: (default) - No depot will be auto assigned to the current order. `1`: The closest depot (depending on time) will be assigned to the current order.) - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The order’s customer was not found/doesn’t exist.** **The order doesn’t have the coordinates set.** **The time window format is wrong.** **The number of packages/weight/cubic volume has a negative value or exceeds the maximum limit.** **The orders’ phone number has wrong format.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Order not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetOrder, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetOrder, null, 2)}
--- ### 5. Delete Orders **Description:** Deletes orders from the system. - **Method:** `DELETE` - **Endpoint:** `/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/orders` - **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** Can't delete orders because at least one of them does not exist or is used in another operation.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "ids": [78910, 78911] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- # 2_Core_Concepts/03_MiscLocation.mdx # Miscellaneous Location [ReadingTime] [br] ## Overview The **Miscellaneous Location RestAPI** allows you to manage miscellaneous locations within the Fleet Management system. You can create, retrieve, update, and delete miscellaneous locations. This API supports filtering, sorting, and pagination to help manage large datasets efficiently. ### Miscellaneous Location Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the miscellaneous location.** **isDepot** **Boolean** **Indicates whether the location is a depot.** **alias** **String** **Short name or identifier for the location.** **address** **Object** **Detailed address information of the location.** **location** **Object** **Coordinates of the miscellaneous location.**
--- ## Endpoints ### 1. Create Miscellaneous Location **Description:** Adds a new miscellaneous location to the database. - **Method:** `POST` - **Endpoint:** `/misc-locations` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/misc-locations` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The miscLocation does not have the coordinates set. Please try to set a correct set of coordinates.** **The miscLocation is curently used in another operation.**
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Miscellaneous Location` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddDepots, null, 2)}
**** - **Response Body:** (error code `200`)
{JSON.stringify(GetDepots, null, 2)}
--- ### 2. Get All Miscellaneous Location **Description:** Fetches a list of all miscellaneous locations with optional filtering. - **Method:** `GET` - **Endpoint:** `/misc-locations` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/misc-locations` - **Query Parameters:** - `search` (string, *optional*) – General search term across miscLocations. - `id` (string, *optional*) – Filter by miscLocation ID (`id=value:exact` for exact match). - `alias` (string, *optional*) – Filter by miscLocation alias (`alias=value:exact` for exact match). - `location` (string, *optional*) – Filter by location (`location=value:exact` for exact match). - `country` (string, *optional*) – Filter by country (`country=value:exact` for exact match). - `state` (string, *optional*) – Filter by state (`state=value:exact` for exact match). - `county` (string, *optional*) – Filter by county (`county=value:exact` for exact match). - `city` (string, *optional*) – Filter by city (`city=value:exact` for exact match). - `postalCode` (string, *optional*) – Filter by postal code (`postalCode=value:exact` for exact match). - `streetName` (string, *optional*) – Filter by street name (`streetName=value:exact` for exact match). - `streetNumber` (string, *optional*) – Filter by street number (`streetNumber=value:exact` for exact match). - `extra` (string, *optional*) – Filter by extra address value (`extra=value:exact` for exact match). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, isDepot, alias, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra` - `includeColumns` (string, *optional*) – Specify which columns to include. - Available columns: `id, isDepot, alias, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetDepots, null, 2)}
--- ### 3. Get a Miscellaneous Location by ID **Description:** Retrieves a specific miscellaneous location by ID. - **Method:** `GET` - **Endpoint:** `/misc-locations/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/misc-locations/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique location ID. - **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** MiscLocation not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetDepot, null, 2)}
--- ### 4. Update a Miscellaneous Location **Description:** Updates an existing miscellaneous location record. - **Method:** `PUT` - **Endpoint:** `/misc-locations/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/misc-locations/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique location ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The miscLocation does not have the coordinates set. Please try to set a correct set of coordinates.** **The miscLocation is curently used in another operation.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** MiscLocation not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetDepot, null, 2)}
- **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 5. Delete MiscLocations **Description:** Deletes miscellaneous locations. - **Method:** `DELETE` - **Endpoint:** `/misc-locations` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/misc-locations` - **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** Can't delete misc locations because at least one of them does not exist.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If a miscellaneous location that needs to be deleted was previously used to create orders or as a departure point, the id_depot in those orders or the departure field will be set to 0. ::: #### Example: - **Request Body:** ```json [98765, 98766, 98767 ] ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- # 2_Core_Concepts/04_Vehicle.mdx # Vehicle [ReadingTime] [br] ## Overview The **Vehicle RestAPI** allows you to manage vehicle records within the Fleet Management system. You can create, retrieve, update, and delete vehicle data. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. ### Vehicle Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the vehicle.** **type** **Integer** **status** **Integer** **name** **String** **Vehicle's name.** **lastPosition** **Object** **Last known GPS coordinates of the vehicle.** **maxLoadWeight** **Float** **Maximum weight the vehicle can carry.** **maxLoadCube** **Float** **Maximum cubic volume the vehicle can carry.** **startTime** **Integer** **Start time of the working program (minutes from midnight).** **endTime** **Integer** **End time of the working program (minutes from midnight).** **make** **String** **Vehicle's manufacturer (for cars, trucks, bikes, and e-bikes).** **model** **String** **Vehicle's model (for cars, trucks, bikes, and e-bikes).** **fuelType** **Integer** **consumption** **Float** **Vehicle's fuel consumption (only for cars and trucks).** **licensePlate** **String** **Vehicle's registration plate (only for cars and trucks).** **bikerWeight** **Float** **Total weight of the biker and bike (only for e-bikes).** **bikePower** **Float** **Power of the bicycle in watts (only for e-bikes).** **height** **Float** **Height of the vehicle.** **width** **Float** **Width of the vehicle.** **weight** **Float** **Weight of the vehicle.** **length** **Float** **Length of the vehicle.** **axleLoad** **Float** **Maximum axle load the vehicle can carry.**
**Vehicle type:** **0 - Car** **1 - Pedestrian** **2 - E-Bike** **3 - Truck** **4 - Bike**
**Vehicle status:** **-1 - Unavailable** **0 - Available** **1 - En Route**
**Fuel type (only for cars and trucks):** **-1 - None** **0 - Diesel Standard** **1 - Diesel Premium** **2 - Gasoline Standard** **3 - Gasoline Premium** **4 - Electric** **5 - LPG**
--- ## Endpoints ### 1. Create Vehicle **Description:** Adds a new vehicle to the database. - **Method:** `POST` - **Endpoint:** `/vehicles` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/vehicles` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The vehicle’s consumption/weight/cubic volume has a negative value or exceeds the maximum limit.** **The bike + biker weight exceeds the maximum weight the vehicle can carry.** **The fuel type is not right for the vehicle type (eg: vehicle type = car and fuel type = none ; vehicle type = E-bike and fuel type = gasoline).**
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Vehicle` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddVehicles, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetVehicles, null, 2)}
--- ### 2. Get All Vehicles **Description:** Fetches a list of all vehicles with optional filtering. - **Method:** `GET` - **Endpoint:** `/vehicles` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/vehicles` - **Query Parameters** - `search` (string, *optional*) – General search term across vehicles. - `id` (string, *optional*) – Filter by vehicle ID (use `id=value:exact` for exact match). - `name` (string, *optional*) – Filter by vehicle name (use `name=value:exact` for exact match). - `make` (string, *optional*) – Filter by vehicle manufacturer (use `make=value:exact` for exact match). - `model` (string, *optional*) – Filter by model (use `model=value:exact` for exact match). - `type` (string, *optional*) – Filter by vehicle type (`type=car`). - `status` (string, *optional*) – Filter by vehicle status(status=`enRoute`). - `lastPosition` (string, *optional*) – Filter by last known position (`lastPosition=value:exact` for exact match). - `fuelType` (string, *optional*) – Filter by fuel type(`fueType=gas`). - `licensePlate` (string, *optional*) – Filter by license plate (`licensePlate=value:exact` for exact match). - `bikePower` (string, *optional*) – Filter by bike power (`bikePower=value:exact` for exact match). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, name, make, model, fuelType, consumption, licensePlate, type, maxWeight, maxCube, bikerWeight, bikePower, status, latitude, longitude`. - `includeColumns` (string, *optional*) – Specify which columns to include. - Available columns:`id, name, make, model, fuelType, consumption, licensePlate, type, maxWeight, maxCube, bikerWeight, bikePower, status, latitude, longitude` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Vehicle not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetVehicles, null, 2)}
--- ### 3. Get a Vehicle by ID **Description:** Retrieves a specific vehicle by ID. - **Method:** `GET` - **Endpoint:** `/vehicles/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/vehicles/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique vehicle ID. - **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** Vehicle not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetVehicle, null, 2)}
--- ### 4. Update a Vehicle **Description:** Updates an existing vehicle record. - **Method:** `PUT` - **Endpoint:** `/vehicles/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/vehicles/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique vehicle ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The vehicle’s consumption/weight/cubic volume has a negative value or exceeds the maximum limit.** **The bike + biker weight exceeds the maximum weight the vehicle can carry.** **The fuel type is not right for the vehicle type (eg: vehicle type = car and fuel type = none ; vehicle type = E-bike and fuel type = gasoline).**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Vehicle not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetVehicle, null, 2)}
- **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 5. Delete Vehicles **Description:** Deletes vehicles from the system. - **Method:** `DELETE` - **Endpoint:** `/vehicles` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/vehicles` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The vehicles cannot be deleted, because there are optimizations and/or routes in which they are used.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Can't delete vehicles because at least one of them does not exist or is used in another operation.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "ids": [98765, 98766] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- # 2_Core_Concepts/05_ConfigurationParameters.mdx # Configuration Parameters [ReadingTime] [br] ## Overview `Configuration Parameters` class in RestAPI define key settings that influence the behavior of the route optimization process. These settings determine aspects such as optimization goals, search time limits, and flexibility in handling orders. Proper configuration ensures that the algorithm meets the operational constraints of the routing problem. ## Configuration Parameters Structure Each Configuration Parameter consists of: **Name** **Type** **Description** **Name** **String** **The name of the optimization/route configuration.** **IgnoreTimeWindow** **bool** **Specifies whether time-windows are ignored during optimization. Default is false.** **AllowDroppingOrders** **bool** **Specifies whether the algorithm is allowed to drop orders if no solution is found by visiting all of them. Default is false.** **GroupingOrders** **bool** ** Specify if the orders will be grouped. If the distance between any two orders is less than 10 meters, those orders will be considered part of the same group. Default is false.** **BalancedRoutes** **Integer** **OptimizationCriterion** **Integer** **ArrangeCriterion** **Integer** **OptimizationQuality** **Integer** **MaxSearchTime** **unsigned int** **Maximum time (in seconds) the algorithm can search for a solution. This parameter is considered only when the Optimization Quality is set to OQ_Best. Default is 300 seconds.** **MaxWaitTime** **unsigned int** **Maximum time (in seconds) that vehicles can wait at an order to align with the next order's time window. Default is INT_MAX.** **RouteType** **Integer** **Restrictions** **Integer** **DistanceUnit** **Integer** **OrderSequenceOptions** **OrdersSequenceMap**
Specifies the option to balance routes of an optimization. **** **Possible values:** **** • **0** - None: No balancing. **** • **1** - By time: Balance by time. **** • **2** - By number of orders: Balance by the number of orders.
Specifies the optimization criterion. **** **Possible values:** **** • **0** - Time: The problem will be optimized by distance. (the route with the shortest distance). **** • **1** - Distance: The problem will be optimized by time. (the route with the shortest time).
Specifies the arrangement criterion for optimizing time. **** **Used only if OptimizationCriterion = 1 (Distance).****** **Possible values:** **** • **0** - Matrix: Orders are arranged based on matrix distance. **** • **1** - Euclidian: Uses the rounded straight-line (Euclidean) distance between orders. **** • **2** - Exact Euclidian: Uses precise (decimal) straight-line distance between orders. **** • **3** - Geodesic: Considers Earth's curvature in straight-line distance calculation. **** • **4** - Manhattan: Uses the Manhattan (grid-based) distance formula.
Specifies the optimization quality (solution accuracy). **** **Possible values:** **** • **0** - Unoptimized: The algorithm will return an unoptimized solution. **** • **1** - Fast: The algorithm will return the first solution found. (Not an accurate solution) **** • **2** - Optimized: The algorithm will return an optimized solution. **** • **3** - Best: The algorithm will return the best solution found in the specified time.
Specifies the route type. **** **Possible values:** **** • **0** - RoundRoute: The route will return at the first order (circuit). **** • **1** - EndAnywhere: The route will end at the most efficient order selected by the algorithm. **** • **2** - CustomEnd: The route will end at the specified order.
Specifies road restrictions for distance and time matrix calculations. **** **Possible values:** **** • **0** - None: No restrictions. **** • **1** - Tolls: Avoid toll road restriction. **** • **2** - Highways: Avoid highways restriction.
Specifies the unit of distance used in optimization and routing calculations. **** **Possible values:** **** • **0** - Kilometers: Distance in kilometers. **** • **1** - Miles: Distance in miles.
Specifies the association between different orders that should be visited in a certain order. **** **Format:** A map where each pair contains an enum and a list of lists, where each inner list is a sequence of order IDs.
## Example
```json { "configurationParameters": { "name": "Test Optimization", "ignoreTimeWindow": false, "allowDroppingOrders": true, "groupingOrders": false, "balancedRoutes": 0, "optimizationCriterion": 1, "arrangeCriterion": 0, "optimizationQuality": 2, "maxTimeToOptimize": 600, "maxWaitTime": 18000, "routeType": 0, "restrictions": 0, "distanceUnit": 0, "orderSequenceOptions": [] } } ```
### Explanation This setup configures an optimization with the following characteristics: * **"Test Optimization" as the instance name** – Identifies the optimization session. * **Time windows are respected** (`ignoreTimeWindow = false`) – Ensures that orders are scheduled within their specified delivery windows. * **Orders can be dropped if needed** (`allowDroppingOrders = true`) – Allows the algorithm to exclude unserviceable orders. * **No grouping of nearby orders** (`groupingOrders = false`) – Each order is treated individually regardless of proximity. * **No route balancing applied** (`balancedRoutes = None (0)`) – The algorithm does not attempt to balance workloads across routes. * **Optimization is based on travel distance** (`optimizationCriterion = Distance (1)`) – The algorithm prioritizes routes with shorter total distance. * **Arrangement is done using matrix-based distance** (`arrangeCriterion = Matrix (0)`) – Orders are arranged based on distance matrix calculations. * **Optimized solution quality is targeted** (`optimizationQuality = Optimized (2)`) – Provides a well-refined solution without exhaustive search. * **Maximum optimization time is limited to 600 seconds** (`maxTimeToOptimize = 600`) – Constrains algorithm runtime for performance. * **Vehicles can wait up to 5 hours at an order** (`maxWaitTime = 18000`) – Allows schedule alignment with time windows. * **Each route is circular** (`routeType = RoundRoute (0)`) – Routes start and end at the same location. * **No road restrictions applied** (`restrictions = None (0)`) – All roads, including tolls and highways, are considered. * **Distance is measured in kilometers** (`distanceUnit = Kilometers (0)`) – Units used in optimization calculations. * **No specific order sequence constraints** (`orderSequenceOptions = []`) – Orders can be visited in any sequence. --- # 2_Core_Concepts/06_VehicleConstraints.mdx # Vehicle Constraints [ReadingTime] [br] ## Overview ``Vehicle Constraints`` class in Fleet Management RestAPI define the limitations and requirements applied to a vehicle during the route optimization process. These constraints ensure that the vehicle operates within its capabilities, such as capacity, distance, and revenue limits. Properly configuring these constraints ensures that the optimization algorithm generates feasible and efficient routes for the vehicle. ## Vehicle Constraints Structure Each Vehicle Constraint consists of: **Name** **Type** **Description** **StartDate** **Integer** **The date when the vehicle starts its route. Default is the current UTC time.** **MaxNumberOfPackages** **Integer** **The maximum number of packages that the vehicle can carry. Default is INT_MAX.** **MinNumberOfOrders** **Integer** **The minimum number of orders that the vehicle must visit. Default is 0.** **MaxNumberOfOrders** **Integer** **The maximum number of orders that the vehicle can visit. Default is INT_MAX.** **MinDistance** **Float** **The minimum distance that the vehicle must travel (in the same distance unit as set in ConfigurationParameters). Default is 0.** **MaxDistance** **Float** **The maximum distance that the vehicle can travel (in the same distance unit as set in ConfigurationParameters). Default is INT_MAX.** **MaxRevenue** **Float** **The maximum revenue that the vehicle can collect in total from all customers. Default is INT_MAX.** **FuelPrice** **Float** **The price for 1 liter of fuel or 1 kWh for an electric engine.**
## Example Usage ```json { "vehiclesConstraints": [ { "fuelPrice": 1.09, "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 300, "minDistance": 0, "maxDistance": 800, "maxRevenue": 85 } ] } ``` ### Explanation This setup configures a vehicle with the following `vehicleConstraints`: * **Start time** – The vehicle begins its route at the specified `startDate` (timestamp: 1596758400000, in UTC). * **Maximum of 53 packages** – The vehicle can carry up to 53 packages. * **Minimum of 0 orders** – The vehicle is not required to visit any minimum number of orders. * **Maximum of 300 orders** – The vehicle can visit up to 300 orders. * **Minimum distance of 0 units** – There is no minimum travel distance required. * **Maximum distance of 800 units** – The vehicle cannot travel more than 800 units. * **Maximum revenue of 85** – The total revenue collected from all customers must not exceed 85. * **Fuel price of 1.09** – The cost of fuel is set at 1.09 per unit (liter or kWh, depending on engine type). These constraints ensure that the vehicle operates within its defined limits, allowing the optimization algorithm to generate feasible and efficient routes. # 2_Core_Concepts/07_Optimization.mdx # Optimization [ReadingTime] [br] ## Overview The **Optimization RestAPI** allows you to create, retrieve, update, and delete route optimizations within the Fleet Management system. It helps in planning the most efficient routes by considering various constraints such as time windows, vehicle capacity, and priority. ### Optimization Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the optimization.** **name** **String** **Name of the optimization.** **configurationParameters** **Array** **List of configuration parameters for the optimization.** **orders** **Array** **List of order IDs included in the optimization.** **matrixBuiltType** **Integer** **matrices** **Array** **Contains distance and time matrices, required when matrixBuiltType is set to 0.** **departures** **Array** **List of departure locations for the optimization.** **destinations** **Array** **List of destination locations for the optimization.** **vehicles** **Array** **List of vehicle IDs assigned to the optimization.** **vehiclesConstraints** **Array** **List of vehicle constraints applied in the optimization.** **numberOfVehicles** **Integer** **Total number of vehicles used in the optimization.** **creationTimestamp** **Integer** **Timestamp of when the optimization was created.**
**Defines how the distance matrix is built:** **0 - Set by user using "matrices" field** **1 - Real road map distances and times (default)**
--- ## Endpoints ### 1. Create Optimization **Description:** An optimization must be created before it can be solved. It defines the routing problem by including `orders`, `vehicles`, and `constraints`.To solve the optimization, the system initiates the process and returns a `request` object. This object allows you to track the status of the optimization until the solution is ready. - **Method:** `POST` - **Endpoint:** `/optimizations` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations` - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1`:(default) - The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The vehicles list is empty.** **One or more vehicles are set multiple times.** **The vehicle with the id X is not available.** **In the same optimization we cannot combine vehicles with type EBike and with vehicle type Car, Truck or Bike.** **Number of vehicles constraints should be one or equal to the number of vehicles.** **The orders list is empty.** **The order with the id X is already scheduled for another optimization.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **One of the vehicles was not found.** **One of the orders was not found.** **One of the miscellaneous location set for departure/destination was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] Adding an optimization returns a `request` object, which allows you to track the status of the optimization process. Once the request status is finished, the solution can be retrieved using [Get Optimization's Solution](/Core_Concepts/Optimization#7-get-optimizations-solution) request. The solution consists of one or more routes. A route is the trip that a vehicle travels to visit the orders, so the number of routes returned is maximum the number of vehicles set in the optimization(see [Routes](/Core_Concepts/Route)).**** If the operation is successful, the `Optimization` object will have its `id` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:**
{JSON.stringify(AddOptimizationObj, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetOptimizationObj, null, 2)}
--- ### 2. Get all optimizations **Description:** Fetches all available optimizations. - **Method:** `GET` - **Endpoint:** `/optimizations/` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations` - **Query Parameters:** - `search` (string, *optional*) – General search term across optimizations. - `id` (string, *optional*) – Filter by optimization ID (`id=value:exact` for exact match). - `name` (string, *optional*) – Filter by optimization name (`name=value:exact` for exact match). - `creationTime` (string, *optional*) – Filter by creation time (`creationTime=value:exact` for exact match). - `ignoreTimeWindow` (string, *optional*) – Filter by optimizations that ignore time windows (`ignoreTimeWindow=value:exact` for exact match). - `routeType` (string, *optional*) – Filter by route type (`routeType=value`). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc`. Example: `name:asc,creationTime:desc,routeType:asc` - Available columns: `id, name, creationTime, ignoreTimeWindow, optimizeBy, optimizationQuality, maxOptimizeTime, routeType, matricesBuildType, restrictions, maxWaitTimeOrders, distanceUnit, arrangeCriterion, balancedRoutes`. - `includeColumns` (string, *optional*) – Specify which columns to include. Example: `&includeColumns = id,name,creationTime` - Available columns: `id, parentId, name, parentTime, creationTime, childTime, ignoreTimeWindow, balancedRoutes, optimizeBy, arrangeCriterion, optimizationQuality, maxOptimizeTime, routeType, matricesBuildType, restrictions, distanceUnit, idVehicles, maxWaitTimeOrders`. - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0..
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetAllOptimizationsObj, null, 2)}
--- ### 3. Get an Optimization by ID **Description:** Retrieves a specific optimization by its ID. - **Method:** `GET` - **Endpoint:** `/optimizations/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **Path Parameter:** - `id` (integer, **required*) - The unique optimization ID. - **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** The optimization or one of its components(orders, vehicles, departures,etc) was not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetOptimizationObjWithoutRequest, null, 2)}
--- ### 4. Update an Optimization **Description:** Updates an existing optimization. - **Method:** `PUT` - **Endpoint:** `/optimizations/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **Path Parameter:** - `id` (integer, **required*) - The unique optimization ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The vehicles list is empty.** **One or more vehicles are set multiple times.** **The vehicle with the id X is not available.** **In the same optimization we cannot combine vehicles with type EBike and with vehicle type Car, Truck or Bike.** **Number of vehicles constraints should be one or equal to the number of vehicles.** **The orders list is empty.** **The order with the id X is already scheduled for another optimization.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **One of the vehicles was not found.** **One of the orders was not found.** **One of the miscellaneous location set for departure/destination was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] Orders within an optimization **cannot be updated directly** using `UpdateOptimization` request. However, all other fields in the optimization can be modified using this method. To modify orders, refer to the following examples: * [Adding Orders to an Optimization](/Core_Concepts/Optimization#9-add-orders-to-an-optimization) * [Updating an Order from an Optimization](/Core_Concepts/Optimization#10-update-order-from-an-optimization) * [Deleting an Order from an Optimization](/Core_Concepts/Optimization#11-delete-order-from-an-optimization) Once the optimization is updated, it will be reoptimized. The reoptimized solution can be retrieved using [Get Optimization's Solution](/Core_Concepts/Optimization#7-get-optimizations-solution) request once the request status is `Finished`. ::: #### Example: - **Request Body:**
{JSON.stringify(GetOptimizationObj, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetOptimizationObj, null, 2)}
--- ### 5. Delete an Optimization **Description:** Delete the optimizations for the user. Optimizations can be deleted individually or in bulk. - **Method:** `DELETE` - **Endpoint:** `/optimizations` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations` - **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** Can't delete the optimizations because at least one of them does not exist.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] When an optimization is deleted, the routes assigned to that optimization are also deleted. ::: #### Example: - **Request Body:** ```json { "ids": [123, 456] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 6. Get Solutions for Multiple Optimizations **Description:** Retrieves solutions for multiple optimizations. - **Method:** `GET` - **Endpoint:** `/optimizations/solution` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations/solution` - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **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** The solutions were not found.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "ids": [123, 456] } ``` - **Response Body:** (error code `200`)
```json [ { "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "optimizationId": 139950, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, "id": 255145 } ] ```
--- ### 7. Get Optimization's Solution **Description:** Retrieves the computed routes and waypoints for a specific optimization. - **Method:** `GET` - **Endpoint:** `/optimizations/{id}/solution` - **Headers:** - `Authorization: YOUR_API_KEY` - **Path Parameter:** - `id` (integer, **required*) - The unique optimization ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **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** Solution not found.
**405 Method Not Allowed** Incorrect method type.
**425 Too Early** Request not finished.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "optimizationId": 139950, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, "id": 255145 } ```
--- ### 8. Reoptimize an Optimization - **Description:**Creates a new and improved solution (if one exists) for the optimization. Reoptimizing an existing optimization returns a `request` object, which can be used to track the status of the process. Once the request status is marked as *finished*, the new solution can be retrieved using the [Get Optimization's Solution](/Core_Concepts/Optimization#7-get-optimizations-solution) endpoint. The latest fuel prices are used in generating the new solution (see [Get Fuel Prices](/Core_Concepts/FuelPrice)). - **Method:** `POST` - **Endpoint:** `/optimizations/{id}/reoptimize` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations/{id}/reoptimize` - **Path Parameter:** - `id` (integer, **required*) - The unique optimization ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **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** Solution not found.
**405 Method Not Allowed** Incorrect method type.
**425 Too Early** Request not finished.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "id": 32342, "optimizationId": 137211, "routeId": , "status": 0, "message": "Operation done successfully!", "creationTimestamp": 123456 } ```
--- ### 9. Add Orders to an Optimization **Description:** Adds orders to the end of the existing optimization's order list. If the optimization is reoptimized, the new orders will be assigned to routes, and the returned optimization will include a `request` object to track the reoptimization status. - **Method:** `POST` - **Endpoint:** `/optimizations/{id}/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations/{id}/orders` - **Path Parameter:** - `id` (integer, **required*) - The unique optimization ID. - **Query Parameters:** - `reoptimize` (integer, *optional*) - `0` (default): - If the optimization will not be re-optimized, the orders will be added to the optimization's order list, but will not be in a route, so they won't be visited by any vehicle. - `1`: The route will be re-optimized. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **One of the orders is scheduled for another optimization.** **One of the orders has the time window outside of the optimization’s vehicles start time-end time interval.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **Optimization was not found.** **One of the orders to be added was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "orders":[ 898241, 898242 ] } ``` - **Response Body:** (error code `200`) :::info[note] There are two possible responses: 1. If the optimization is reoptimized, the response will be a request object with the status of the request. 2. If the optimization is not reoptimized, the response will be the updated optimization. :::
{JSON.stringify(GetNewOptimizationObj, null, 2)}
--- ### 10. Update Order from an Optimization **Description:** Updates an existing order within an optimization. - **Method:** `PUT` - **Endpoint:** `/optimizations/{id}/orders/{orderId}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **Path Parameters:** - `id` (integer, **required*) - The unique optimization ID. - `orderId` (integer, **required*) - The unique order ID within the optimization. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **Order’s time window is outside of the optimization start-end time limit.** **The total number of packages/weight/cubic volume of the optimization’s orders exceeds the vehicles limitations.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **Optimization was not found.** **Optimization’s solution not found.** **Order not found in optimization’s orders.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] These changes will also be seen in the route orders for the routes involved in the optimization. So when you want to update a route order you can use this method. ::: #### Example: - **Request Body:**
{JSON.stringify(GetOrder, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetNewOptimizationObj, null, 2)}
--- ### 11. Delete Order from an Optimization **Description:** Delete an order from an existing optimization. It will not appear in the Route as well. - **Method:** `DELETE` - **Endpoint:**`/optimizations/{id}/orders/{orderId}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/optimizations/{id}/orders/{orderId}` - **Path Parameters:** - `id` (integer, **required*) - The unique optimization ID. - `orderId` (integer, **required*) - The unique order ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **If the optimization has only one order, the order cannot be deleted.** **The optimization does not contain the order.** **If one of the optimization’s routes contains only one order, the order cannot be deleted.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **Optimization was not found.** **Optimization’s solution not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] A route must contain at least two orders for one to be deleted. If the order you want to delete is the only one in the route, it cannot be deleted. ::: #### Example: - **Response Body:**
{JSON.stringify(GetOptimizationObjWithoutRequest, null, 2)}
--- # 2_Core_Concepts/08_Route.mdx # Route [ReadingTime] [br] ## Overview The **Route RestAPI** allows you to manage route data, including retrieving, updating, and deleting routes. This RestAPI supports multiple request types to interact with route solutions and optimization processes. ### Route Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the route.** **optimizationId** **Integer** **ID of the associated optimization.** **idVehicle** **Integer** **ID of the vehicle assigned to this route.** **matrixBuiltType** **Integer** **matrices** **Array** **Contains distance and time matrices (set only if matrixBuiltType = 0).** **configurationParameters** **Object** **Configuration parameters for the route.** **departure** **Object** **Details of the departure location.** **destination** **Object** **Details of the destination location.** **vehicleConstraints** **Array** **List of vehicle constraints applied to the route.** **orders** **Array** **List of orders included in the route.** **totalDistance** **Float** **Total route distance (in kilometers or miles based on settings).** **totalTime** **Integer** **Total duration of the route (in seconds).** **totalServiceTime** **Integer** **Total service time for all orders in the route (in seconds).** **totalWaitTime** **Integer** **Total wait time for the route (in seconds).** **neededFuel** **Float** **Total fuel consumption for the route (liters or kWh based on fuel type).** **price** **Float** **Total cost of the route, calculated based on fuel consumption and distance.** **shape** **String** **Encoded polyline or list of locations representing the route.** **creationTimestamp** **Integer** **Timestamp of when the route was created.**
**Distance calculation method:** **0 - Set by user using "matrices" field** **1 - Real road distances and times**
--- ## Endpoints ### 1. Get All Routes **Description:** Fetches all available routes. - **Method:** `GET` - **Endpoint:** `/routes` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes` - **Query Parameters:** - `search` (string, *optional*) - General search term. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "routes": [ { "id": 255145, "optimizationId": 139950, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ] } ```
--- ### 2. Get a Route by ID **Description:** Retrieves a specific route by its ID. - **Method:** `GET` - **Endpoint:** `/routes/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique route ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0` : The route's shape will not be encoded. - `1` (default) : The route's shape will be encoded. - **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** Route not found.
**405 Method Not Allowed** Incorrect method type.
**425 Too Early** Request not finished.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
```json { "id": 255145, "optimizationId": 139950, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ```
--- ### 3. Update a Route **Description:** Routes can be updated with new parameters, such as vehicle or constraints. Make changes on Route and return the new solution after reptimizing the changed route. - **Method:** `PUT` - **Endpoint:** `/routes/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}` - **Path Parameter:** - `id` (integer) - The unique route ID. - **Query Parameter:** - `encodeShape` (integer) - 0: The route's shape will not be encoded. 1:(default) - The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **Route’s vehicle is unavailable.** **Route’s vehicle limitations are exceeded by the order’s total number of packages/weight/cubic volume.** **Route’s start-end time are not valid.** **No destination set for the Route, and the route type is Custom end.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **Route was not found.** **Route’s optimization was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] Orders within a route **cannot be updated directly** using `Update Route` request. However, all other fields in the route can be modified using this method. To modify orders, refer to the following examples: * [Adding Orders to a Route](/Core_Concepts/Route#6-add-route-orders) * [Updating an Order from a Optimization](/Core_Concepts/Optimization#10-update-order-from-an-optimization) * [Deleting an Order from a Route](/Core_Concepts/Route#7-delete-an-order-from-a-route) ::: #### Example: - **Request Body:**
```json { "id": 250806, "optimizationId": 137211, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 134764, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 134764, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1742220618730, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1742220613856, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 876534, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1786643, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ```
- **Response Body:** (error code `200`)
```json { "id": 250806, "optimizationId": 137211, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 1, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1 updated" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 85, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 999999, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 134764, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 134764, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1742220618730, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1742220613856, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 876534, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1786643, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ```
--- ### 4. Delete Routes **Description:** Delete the routes from the list. Routes can be deleted individually or in bulk. - **Method:** `DELETE` - **Endpoint:** `/routes` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes` - **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** Can't delete the routes because at least one of them does not exist.
**405 Method Not Allowed** Incorrect method type.
**425 Too Early** Request not finished.
**500 Internal Server Error** Database error occurred.
:::info[Note] The orders of a deleted route will also be deleted from the optimization to which the route belongs. If the route is the only route of an optimization, then it cannot be deleted, instead delete the optimization (see [Delete Optimization](/Core_Concepts/Optimization#5-delete-an-optimization)). ::: #### Example: - **Request Body:** ```json { "ids": [123, 456] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 5. Reoptimize a Route **Description:** Reoptimization allows you to find a better solution for an existing route. - **Method:** `PUT` - **Endpoint:** `/routes/{id}/reoptimize` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/reoptimize` - **Path Parameter:** - `id` (integer, **required*) - The unique route ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **Route’s vehicle is unavailable.** **Route’s vehicle limitations are exceeded by the order’s total number of packages/weight/cubic volume.** **Route’s start-end time are not valid.** **No destination set for the Route, and the route type is Custom end.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **Route was not found.** **Route’s optimization was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] Rearranges the orders in a better order of visit, if exists. The latest fuel prices are used to calculate the route's cost (see [Get Fuel Prices](/Core_Concepts/FuelPrice) example). ::: #### Example: - **Response Body:** (error code `200`) ```json { "id": 767456, "optimizationId": 56646, "routeId": 221356, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1743324342543 } ``` --- ### 6. Add Route Orders **Description:** Add a list of orders into an existing route's orders list. The orders will also be added in the optimization's orders list. - **Method:** `POST` - **Endpoint:** `/routes/{id}/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/orders` - **Path Parameter:** - `id` (integer, **required*) - The unique route ID. - **Query Parameters:** - `reoptimize` (integer, *optional*) - `0`: (default) - If the route will not be re-optimized, the orders will be added to the end of the route. - `1`: The route will be re-optimized. - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1`(default) : - The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **One of the orders is used in another operation.** **One of the orders time window is outside the route’s start-end time interval.** **(For matrix build type=Set by user) The distances and times to all the orders of the route’s optimization were not set.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **The route’s optimization was not found.** **The solution of the route’s optimization was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] There are three options to add orders to a route: - at the end of the route's orders list. - at the optimal positions, which are determined by the algorithm.The orders are inserted at the best positions between the route's orders, without rearranging the route's orders. - at specified positions between the route's orders. The route can be reoptimized, which means that after the addition, the route orders will be rearranged in the best order of visit, so it doesn’t matter which option was chosen to add the orders. The orders will be also added in the list of orders of the route's optimization. ::: #### Example: - **Request Body:** ```json { "orders": [ { "id": 899037, "position": 0 }, { "id": 899038, "position": 0 } ], "optimalPosition": true, } ``` - **Response Body:** (error code `200`) :::info[note] There are two possible responses: 1. If the route is reoptimized, the response will be a request object with the status of the request. 2. If the route is not reoptimized, the response will be the updated route. :::
```json { "id": 255145, "optimizationId": 139950, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 899037, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.9867892, 2.3453345 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.9867892, 2.3453345 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.90019499689340591, "distanceToNextOrder": 0.3640029430003894, "revenueAtArrival": 0, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 899038, "location": [ 48.787420, 2.673783 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12234550181", "email": "c2@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839507, "location": [ 48.787420, 2.673783 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.787420, 2.673783 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783742000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 1.23019499689340591, "distanceToNextOrder": 0.4536400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ```
--- ### 7. Delete an Order from a Route **Description:** Delete an order from an existing route. The order will also be deleted from the optimization. - **Method:** `DELETE` - **Endpoint:** `/routes/{id}/orders/{orderId}` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/orders/{orderId}` - **Path Parameters:** - `id` (integer, **required*) - The unique route ID. - `orderId` (integer, **required*) - The unique order ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1`(default) : - The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** If the route has only one order, the order cannot be deleted.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **The route’s optimization was not found.** **The solution of the route’s optimization was not found.** **The order was not scheduled for any route.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] A route must contain at least two orders for one to be deleted. If the order you want to delete is the only one in the route, it cannot be deleted. ::: #### Example: - **Response Body:** (error code `200`)
```json { "id": 255145, "optimizationId": 139950, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 139813, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 139813, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1744096606089, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371, } ```
--- ### 8. Merge Routes **Description:** Merge multiple routes into a new one. A new optimization will be created for the merged route. The optimization will have same configuration parameters, vehicle constraints and the rest of the fields as the first route from the list. The merged route will not be optimized. - **Method:** `POST` - **Endpoint:** `/routes/merge` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/merge` - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1`(default) : - The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **One of the routes has matrix build type = Set by user and cannot be merged because of that.** **The routes do not have the same vehicle type.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** One of the routes was not found.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Warning] Routes with matrices build type set to `EMatrixBuildType::MBT_Set`, cannot be merged. ::: #### Example: - **Request Body:** ```json { [250995, 250996] } ``` - **Response Body:** (error code `200`)
```json { "id": 250999, "optimizationId": 137369, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 0, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 1, "allowDroppingOrders": false, "ignoreTimeWindow": true, "name": "Merge routes 250996 250995 - Part 0" }, "vehicleConstraints": { "startDate": 1742860800000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 135027, "name": "Car vehicle", "model": "", "costPerHour": 20, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 135027, "endTime": 1439, "fixedCost": 150.5, "startTime": 727, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.826295, 2.343264 ], "matchedLocation": [ 48.82623, 2.343238125 ], "arrivalTime": 1742948951000, "traveledDistance": 90.75505065917969 }, "departure": { "depotId": 0, "alias": "departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.826295, 2.343264 ], "matchedLocation": [ 48.82623, 2.343238125 ], "numberOfpackages": 34, "weight": 49.20000076293945, "cube": 21.600000381469727, "departureTime": 1742927130605, "timeToNext": 413, "distanceToNext": 2.7538180351257324 }, "shape": "{j_iHgthMt@sJBq@t@_J@g@[aQkAyi@}", "creationTimestamp": 1742904432224, "neededFuel": 5.899078369140625, "matrixBuildType": 1, "price": 276.81201171875, "totalWaitTime": 0, "totalServiceTime": 8960, "orders": [ { "orderInfo": { "revenue": 14.699999809265137, "serviceTime": 750, "timeWindow": [ 1060, 1387 ], "creationTimestamp": 1742904432067, "cube": 4.599999904632568, "numberOfPackages": 11, "depotId": 0, "customData": "", "weight": 12.100000381469727, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 878525, "location": [ 48.827865, 2.379216 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c6@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1789281, "location": [ 48.827865, 2.379216 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82792, 2.3791415625 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 0, "arrivalTime": 1742927544000, "timeToNextOrder": 535, "waitTime": 0, "numberOfPackagesAtArrival": 34, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 11, "weightAtArrival": 49.20000076293945, "collectedWeight": 0, "deliveredWeight": 12.100000381469727, "cubeAtArrival": 21.600000381469727, "collectedCube": 0, "deliveredCube": 4.599999904632568, "traveledDistance": 2.7538180351257324, "distanceToNextOrder": 3.6211578845977783, "revenueAtArrival": 0, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 2.700000047683716, "serviceTime": 200, "timeWindow": [ 1060, 1343 ], "creationTimestamp": 1742904432067, "cube": 5.800000190734863, "numberOfPackages": 8, "depotId": 0, "customData": "", "weight": 15.399999618530273, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 878526, "location": [ 48.845198, 2.402896 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c2@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1789277, "location": [ 48.845198, 2.402896 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.8452625, 2.4027009375 ], "actualLocation": [ 0, 0 ], "indexInRoute": 1, "indexInOptimization": 1, "arrivalTime": 1742928829000, "timeToNextOrder": 855, "waitTime": 0, "numberOfPackagesAtArrival": 23, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 8, "weightAtArrival": 37.099998474121094, "collectedWeight": 0, "deliveredWeight": 15.399999618530273, "cubeAtArrival": 17, "collectedCube": 0, "deliveredCube": 5.800000190734863, "traveledDistance": 6.37497615814209, "distanceToNextOrder": 9.219883918762207, "revenueAtArrival": 14.699999809265137, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 10, "serviceTime": 900, "timeWindow": [ 1093, 1360 ], "creationTimestamp": 1742904432067, "cube": 9.699999809265137, "numberOfPackages": 9, "depotId": 0, "customData": "", "weight": 16.5, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 878527, "location": [ 48.90092, 2.400039 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c4@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1789279, "location": [ 48.90092, 2.400039 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.9005959375, 2.4000475 ], "actualLocation": [ 0, 0 ], "indexInRoute": 2, "indexInOptimization": 2, "arrivalTime": 1742929884000, "timeToNextOrder": 971, "waitTime": 0, "numberOfPackagesAtArrival": 15, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 9, "weightAtArrival": 21.69999885559082, "collectedWeight": 0, "deliveredWeight": 16.5, "cubeAtArrival": 11.199999809265137, "collectedCube": 0, "deliveredCube": 9.699999809265137, "traveledDistance": 15.594860076904297, "distanceToNextOrder": 9.614479064941406, "revenueAtArrival": 17.399999618530273, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 7.5, "serviceTime": 600, "timeWindow": [ 1043, 1387 ], "creationTimestamp": 1742904432067, "cube": 8.399999618530273, "numberOfPackages": 9, "depotId": 0, "customData": "", "weight": 16.200000762939453, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 878531, "location": [ 48.897163, 2.292865 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c3@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1789278, "location": [ 48.897163, 2.292865 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.89706375, 2.29247 ], "actualLocation": [ 0, 0 ], "indexInRoute": 6, "indexInOptimization": 6, "arrivalTime": 1742935187000, "timeToNextOrder": 404, "waitTime": 0, "numberOfPackagesAtArrival": 29, "collectedNumberOfPackages": 9, "deliveredNumberOfPackages": 0, "weightAtArrival": 16.299999237060547, "collectedWeight": 16.200000762939453, "deliveredWeight": 0, "cubeAtArrival": 20.5, "collectedCube": 8.399999618530273, "deliveredCube": 0, "traveledDistance": 34.35464096069336, "distanceToNextOrder": 2.4328789710998535, "revenueAtArrival": 37.79999923706055, "visitTimestamp": 0 }, { "orderInfo": { "revenue": 2.9000000953674316, "serviceTime": 800, "timeWindow": [ 1077, 1377 ], "creationTimestamp": 1742904432067, "cube": 1.5, "numberOfPackages": 6, "depotId": 0, "customData": "", "weight": 5.199999809265137, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 1, "priority": 0, "id": 878532, "location": [ 48.887096, 2.283513 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c7@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1789282, "location": [ 48.887096, 2.283513 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.886898125, 2.2838078125 ], "actualLocation": [ 0, 0 ], "indexInRoute": 7, "indexInOptimization": 7, "arrivalTime": 1742936191000, "timeToNextOrder": 1286, "waitTime": 0, "numberOfPackagesAtArrival": 38, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 6, "weightAtArrival": 32.5, "collectedWeight": 0, "deliveredWeight": 5.199999809265137, "cubeAtArrival": 28.899999618530273, "collectedCube": 0, "deliveredCube": 1.5, "traveledDistance": 36.78752136230469, "distanceToNextOrder": 10.027785301208496, "revenueAtArrival": 45.29999923706055, "visitTimestamp": 0 } ], "totalTime": 21820, "totalDistance": 90.75505065917969, } ```
--- ### 9. Unlink a Route from its Optimization **Description:** Unlinks a route from its optimization. The route will no longer be a part of the optimization's solution. The orders used in this route will be deleted from the optimization. A new optimization will be created for the unlinked route. The new optimization will have same configuration parameters, vehicle constraints and the rest of the fields as the unlinked route. - **Method:** `POST` - **Endpoint:** `/routes/{id}/unlink` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/routes/{id}/unlink` - **Path Parameters:** - `id` (integer, **required*) - The unique route ID. - **Query Parameter:** - `encodeShape` (integer, *optional*) - `0`: The route's shape will not be encoded. - `1` (default): The route's shape will be encoded. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** If the route is the only one in the optimization’s solution it cannot be deleted (Tip: delete the optimization instead).
**401 Unauthorized** API key is missing or invalid.
**404 Not Found**
    **The route’s optimization was not found.** **The solution of the route’s optimization was not found.**
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::warning[Info] The route cannot be unlinked if it is the only route in the optimization's solution. ::: #### Example: - **Response Body:** (error code `200`)
```json { "id": 250807, "optimizationId": 137212, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Unlinked route Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 134764, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 134764, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1742220618730, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1742220613856, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 876534, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1786643, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371 } ```
--- # 2_Core_Concepts/09_Territory.mdx # Territory [ReadingTime] [br] ## Overview The **Territory RestAPI** allows you to manage territories within the Fleet Management system. You can create, retrieve, update, and delete territories. This RestAPI supports basic operations to define geographical regions used for route planning and optimization. ### Territory Object Fields **Field** **Type** **Description** **id** **Integer** **Unique identifier for the territory.** **name** **String** **Name of the territory.** **type** **Integer** **data** **Array** **color** **String** **Color associated with the territory.** **orders** **Array** **List of orders associated with the territory.**
**Territory type:** **0 - Polygon** **1 - Circle** **2 - Rectangle**
**Defines the shape of the territory based on its type:** **Circle - Contains the center and a point on the circle.** **Rectangle - Contains two diagonally opposite points.** **Polygon - Contains a list of points defining the area.**
--- ## Endpoints ### 1. Create Territory **Description:** Adds a new territory to the database. - **Method:** `POST` - **Endpoint:** `/territories` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **Not all the points of the territory's data have 2 values (latitude, longitude).** **For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite.**
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(AddTerritories, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GetTerritories, null, 2)}
--- ### 2. Get All Territories **Description:** Fetches a list of all territories. - **Method:** `GET` - **Endpoint:** `/territories` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories` - **Query Parameters:** - `search` (string, *optional*) – General search term across territories. - `id` (string, *optional*) – Filter by territory ID (`id=value:exact` for exact match). - `name` (string, *optional*) – Filter by territory name (`name=value:exact` for exact match). - `type` (string, *optional*) – Filter by territory type (`type=value`). - `data` (string, *optional*) – Filter by data (`data=value:exact` for exact match). - `color` (string, *optional*) – Filter by color (`color=value:exact` for exact match). - `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc` - Available columns: `id, name, type, data, color` - `includeColumns` (string, *optional*) – Specify which columns to include. - Available columns: `id, name, type, data, color` - `page` (integer, *optional*) – Page number for pagination. - `per_page` (integer, *optional*) – Number of items per page. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request** The values sent for page and per_page parameters are incorrect; should be greater than 0.
**401 Unauthorized** API key is missing or invalid.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetTerritories, null, 2)}
--- ### 3. Get a Territory by ID **Description:** Retrieves a specific territory by ID. - **Method:** `GET` - **Endpoint:** `/territories/{id}` - **Headers:** - `Authorization: Bearer YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories/{id}` - **Path Parameter:** - `id` (integer, **required*) - The unique territory ID. - **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** Territory not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`)
{JSON.stringify(GetTerritory, null, 2)}
--- ### 4. Update a Territory **Description:** Updates an existing territory record. - **Method:** `PUT` - **Endpoint:** `/territories/{id}` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories/{id}` - **Path Parameter:** - `id` (integer, **required*) - Territory ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **Not all the points of the territory's data have 2 values (latitude, longitude).** **For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Territory not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GetTerritory, null, 2)}
- **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 5. Delete Territories **Description:** Deletes territories from the system. - **Method:** `DELETE` - **Endpoint:** `/territories` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Can't delete territories because at least one of them does not exist
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:** ```json { "ids": [1234, 5678] } ``` - **Response Body:** (error code `200`) ```json { "message": "Operation done successfully", } ``` --- ### 6. Generate a Territory **Description:** Automatically generates a territory based on provided parameters.The list of coordinates should contain at least 3 coordinates to create 1 territory. TerritoriesNumber, how many territories should be created (if is is 0, then the algorithm will determinate how many should be created). - **Method:** `POST` - **Endpoint:** `/territories/generate` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories/generate` - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**400 Bad Request**
    **The number of locations is less than 3 and a territory needs at least 3 locations.** **The number of locations should be at least three times the number of territories.**
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Couldn't create that many territories. Try adding more coordinates or lower the number of territories.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Request Body:**
{JSON.stringify(GenerateTerritories, null, 2)}
- **Response Body:** (error code `200`)
{JSON.stringify(GeneratedTerritories, null, 2)}
--- ### 7. Get Orders from Territory **Description:** Retrieves all orders assigned to a specific territory. - **Method:** `GET` - **Endpoint:** `/territories/{id}/orders` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/territories/{id}/orders` - **Path Parameter:** - `id` (integer, **required*) - The unique territory ID. - **Returned error codes:**
Error Code Description
**200 Successful** Successful operation.
**401 Unauthorized** API key is missing or invalid.
**404 Not Found** Territory not found in database.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
- **Response Body:** (error code `200`)
{JSON.stringify(GetOrders, null, 2)}
--- # 2_Core_Concepts/10_FuelPrice.mdx # Fuel Price [ReadingTime] [br] ## Overview The **Fuel Price RestAPI** allows you to manage fuel price records within the Fleet Management system. You can create, retrieve, update, and delete fuel price data. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently. :::warning[Currency Note] No specific currency is used for the fuel price to keep the method as generic as possible. However, it is recommended that users apply the same currency consistently to ensure route cost calculations reflect reality as closely as possible. ::: ### Fuel Price Object Fields **Field** **Type** **Description** **creationTimestamp** **Integer** **Timestamp when the fuel prices were created.** **dieselStandard** **Float** **Price per unit of standard diesel fuel. Default: 1.09.** **dieselPremium** **Float** **Price per unit of premium diesel fuel. Default: 1.17.** **gasolineStandard** **Float** **Price per unit of standard gasoline. Default: 1.07.** **gasolinePremium** **Float** **Price per unit of premium gasoline. Default: 1.19.** **electric** **Float** **Price per unit of electric charging (e.g., kWh). Default: 0.10.** **lpg** **Float** **Price per unit of LPG fuel. Default: 0.55.**
--- ## Endpoints ### 1. Create Fuel Price **Description:** Adds a new fuel price record to the database. - **Method:** `POST` - **Endpoint:** `/fuel-prices` - **Headers:** - `Authorization: YOUR_API_KEY` - `Content-Type: application/json` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/fuel-prices` - **Returned error codes:** - **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.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
:::info[Note] If the operation is successful, the `Fuel Price` object will have its `creationTimestamp` field populated. If the operation fails, an error code is returned, which can be interpreted as described in the **Returned error codes** section. ::: #### Example: - **Request Body:** ```json { "dieselStandard": 1.5, "dieselPremium": 2, "gasolineStandard": 1.51, "gasolinePremium": 1.48, "electric": 0.18, "lpg": 0.6 } ``` - **Response Body:** (error code `200`) - ```json { "creationTimestamp": 1602684618476, "dieselStandard": 1.5, "dieselPremium": 2, "gasolineStandard": 1.51, "gasolinePremium": 1.48, "electric": 0.18, "lpg": 0.6 } ``` --- ### 2. Get All Fuel Prices **Description:** Get fuel prices. If no entry was previously added, the default values will be returned - **Method:** `GET` - **Endpoint:** `/fuel-prices` - **Headers:** - `Authorization: YOUR_API_KEY` - **URL:** `https://fleetmanagement.magiclaneapis.com/v1/fuel-prices` - **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** The fuel prices were not found.
**405 Method Not Allowed** Incorrect method type.
**500 Internal Server Error** Database error occurred.
#### Example: - **Response Body:** (error code `200`) ```json { "creationTimestamp": 1602684618476, "dieselStandard": 1.5, "dieselPremium": 2, "gasolineStandard": 1.51, "gasolinePremium": 1.48, "electric": 0.18, "lpg": 0.6 } ```