Vehicle

_{Estimated reading time: 11 minutes}

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	Vehicle type: 0 - Car 1 - Pedestrian 2 - E-Bike 3 - Truck 4 - Bike
status	Integer	Vehicle status: -1 - Unavailable 0 - Available 1 - En Route
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	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
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.

---

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.

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:

[
  {
    "type": 0,
    "status": 0,
    "name": "Car vehicle 1",
    "manufacturer": "Renault",
    "model": "Master",
    "fuelType": 2,
    "lastPosition": [
      48.870569,
      2.356448
    ],
    "consumption": 6.5,
    "plate": "AA-123-AA",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 420,
    "endTime": 1439
  },
  {
    "type": 0,
    "status": 0,
    "name": "Car vehicle 2",
    "manufacturer": "Renault",
    "model": "Master",
    "fuelType": 2,
    "lastPosition": [
      48.82674,
      2.342116
    ],
    "consumption": 6.5,
    "plate": "AA-124-AA",
    "maxLoadWeight": 60,
    "maxLoadCube": 50,
    "height": 0,
    "width": 0,
    "weight": 0,
    "length": 0,
    "axleLoad": 0,
    "fixedCost": 0,
    "costPerHour": 0,
    "startTime": 420,
    "endTime": 1439
  }
]

• Response Body: (error code 200)

{
  "vehicles": [
    {
      "id": 135932,
      "type": 0,
      "status": 0,
      "name": "Car vehicle 1",
      "manufacturer": "Renault",
      "model": "Master",
      "fuelType": 2,
      "lastPosition": [
        48.870569,
        2.356448
      ],
      "consumption": 6.5,
      "plate": "AA-123-AA",
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "height": 0,
      "width": 0,
      "weight": 0,
      "length": 0,
      "axleLoad": 0,
      "fixedCost": 0,
      "costPerHour": 0,
      "startTime": 420,
      "endTime": 1439
    },
    {
      "id": 135933,
      "type": 0,
      "status": 0,
      "name": "Car vehicle 2",
      "manufacturer": "Renault",
      "model": "Master",
      "fuelType": 2,
      "lastPosition": [
        48.82674,
        2.342116
      ],
      "consumption": 6.5,
      "plate": "AA-124-AA",
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "height": 0,
      "width": 0,
      "weight": 0,
      "length": 0,
      "axleLoad": 0,
      "fixedCost": 0,
      "costPerHour": 0,
      "startTime": 420,
      "endTime": 1439
    }
  ]
}

---

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)

{
  "vehicles": [
    {
      "id": 135932,
      "type": 0,
      "status": 0,
      "name": "Car vehicle 1",
      "manufacturer": "Renault",
      "model": "Master",
      "fuelType": 2,
      "lastPosition": [
        48.870569,
        2.356448
      ],
      "consumption": 6.5,
      "plate": "AA-123-AA",
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "height": 0,
      "width": 0,
      "weight": 0,
      "length": 0,
      "axleLoad": 0,
      "fixedCost": 0,
      "costPerHour": 0,
      "startTime": 420,
      "endTime": 1439
    },
    {
      "id": 135933,
      "type": 0,
      "status": 0,
      "name": "Car vehicle 2",
      "manufacturer": "Renault",
      "model": "Master",
      "fuelType": 2,
      "lastPosition": [
        48.82674,
        2.342116
      ],
      "consumption": 6.5,
      "plate": "AA-124-AA",
      "maxLoadWeight": 60,
      "maxLoadCube": 50,
      "height": 0,
      "width": 0,
      "weight": 0,
      "length": 0,
      "axleLoad": 0,
      "fixedCost": 0,
      "costPerHour": 0,
      "startTime": 420,
      "endTime": 1439
    }
  ]
}

---

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)

{
  "id": 135932,
  "type": 0,
  "status": 0,
  "name": "Car vehicle 1",
  "manufacturer": "Renault",
  "model": "Master",
  "fuelType": 2,
  "lastPosition": [
    48.870569,
    2.356448
  ],
  "consumption": 6.5,
  "plate": "AA-123-AA",
  "maxLoadWeight": 60,
  "maxLoadCube": 50,
  "height": 0,
  "width": 0,
  "weight": 0,
  "length": 0,
  "axleLoad": 0,
  "fixedCost": 0,
  "costPerHour": 0,
  "startTime": 420,
  "endTime": 1439
}

---

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:

{
  "id": 135932,
  "type": 0,
  "status": 0,
  "name": "Car vehicle 1",
  "manufacturer": "Renault",
  "model": "Master",
  "fuelType": 2,
  "lastPosition": [
    48.870569,
    2.356448
  ],
  "consumption": 6.5,
  "plate": "AA-123-AA",
  "maxLoadWeight": 60,
  "maxLoadCube": 50,
  "height": 0,
  "width": 0,
  "weight": 0,
  "length": 0,
  "axleLoad": 0,
  "fixedCost": 0,
  "costPerHour": 0,
  "startTime": 420,
  "endTime": 1439
}

• Response Body: (error code 200)

{
  "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:

{
  "ids": [98765, 98766]
}

• Response Body: (error code 200)

{
  "message": "Operation done successfully",
}

---