Skip to main content
GuidesExamples

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

FieldTypeDescription
idIntegerUnique identifier for the vehicle.
typeInteger
Vehicle type:
0 - Car
1 - Pedestrian
2 - E-Bike
3 - Truck
4 - Bike
statusInteger
Vehicle status:
-1 - Unavailable
0 - Available
1 - En Route
nameStringVehicle's name.
lastPositionObjectLast known GPS coordinates of the vehicle.
maxLoadWeightFloatMaximum weight the vehicle can carry.
maxLoadCubeFloatMaximum cubic volume the vehicle can carry.
startTimeIntegerStart time of the working program (minutes from midnight).
endTimeIntegerEnd time of the working program (minutes from midnight).
makeStringVehicle's manufacturer (for cars, trucks, bikes, and e-bikes).
modelStringVehicle's model (for cars, trucks, bikes, and e-bikes).
fuelTypeInteger
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
consumptionFloatVehicle's fuel consumption (only for cars and trucks).
licensePlateStringVehicle's registration plate (only for cars and trucks).
bikerWeightFloatTotal weight of the biker and bike (only for e-bikes).
bikePowerFloatPower of the bicycle in watts (only for e-bikes).
heightFloatHeight of the vehicle.
widthFloatWidth of the vehicle.
weightFloatWeight of the vehicle.
lengthFloatLength of the vehicle.
axleLoadFloatMaximum 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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe values sent for page and per_page parameters are incorrect; should be greater than 0.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundVehicle not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundVehicle not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
404 Not FoundVehicle not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe vehicles cannot be deleted, because there are optimizations and/or routes in which they are used.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCan't delete vehicles because at least one of them does not exist or is used in another operation.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:

  • Request Body:
{
"ids": [98765, 98766]
}
  • Response Body: (error code 200)
{
"message": "Operation done successfully",
}