Vehicle - Billable Trips
The Admin interface handles web service calls from the Admin web gui. The base url for this is at:
/api/vehicle-admin
A JSON file with OpenAPI data about all vehicle-related admin APIs can be downloaded here.
Get trip
Gets data about a specific trip:
- GET /v1/billable-trips/{guid}
Gets data about a specific trip
- Parameters
guid (string) – The guid of the trip
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the specified trip:
{
ID: 100, // Int
CreatedDate: "2020-05-05T07:20:08Z", // DateTime
LastUpdated: "2020-05-05T07:20:08Z", // DateTime
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsCompleted: true, // Boolean
IsBillable: true, // Boolean
BillableReason: "...", // String
StartLocationName: "Milan", // String
EndLocationName: "Milan", // String
StartLocationLatitude: 1.0000, // Double (nullable)
StartLocationLongitude: 2.0000, // Double (nullable)
EndLocationLatitude: 3.0000, // Double (nullable)
EndLocationLongitude: 4.0000, // Double (nullable)
EndTimestamp: "2020-05-05T07:20:08Z", // DateTime (nullable)
StartTimestamp: "2020-05-05T07:20:08Z", // DateTime
ActualMileageKm: 1500, // Int
ActualDurationSeconds: 10000, // Int
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
RemainingSeconds: 100, // Int
DeletionDate: null // DateTime (nullable)
}
Get trip vehicle
Gets the vehicle for a specific trip:
- GET /v1/billable-trips/{guid}/vehicle
Gets the vehicle for a specific trip
- Parameters
guid (string) – The guid of the trip to search the vehicle for
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the vehicle:
{
ID: 37, // Int
LicensePlate: "AB 123 CD", // String
VIN: "343434343434343434", // String
Sticker: "...", // String
LastSetOperativeBy: "User Name", // String
IsOperative: false, // Boolean
AdminOperativeStatus: true, // Boolean
SystemOperativeStatus: false, // Boolean
SystemOperativeReason: "...", // String (nullable)
"OverriddenSystemOperativeStatus": true, // Boolean
"ForcedOperativeBy": "Administrator.name", // String (nullable)
Notes: "notes", // String (nullable)
CategoryLabels: "{\"en\":\"Sedan\",...}", // String
CategoryID: 4, // Int
CategoryTree:
{
ID: 4, // Int
Labels: "{\"en\":\"Sedan\",...}", // String
Children: [ CategoryDescription object array ]
},
Devices: [ // Object array (nullable)
{
ID:12, // Int
SerialNumber:"123124124" // String
},
...
],
NominalGarage: "London Maintenance Garage", // String
NominalGarageID: 1, // Int
RecoveringGarage: "...", // String (nullable)
RecoveringGarageID: 2, // Int (nullable)
Latitude: 51.1536654, // Double (nullable)
Longitude: -0.1842569, // Double (nullable)
LastPositionUpdate: "2001-01-01T01:01:01Z", // DateTime (nullable)
Groups: [ Guid array ], // Guid Array
CurrentTripGuid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid (nullable)
DeviceID: 123, // Int (nullable)
LastDeviceSync: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastNetworkSignalStrengthPct: 12, // Int (nullable)
FuelSoCLevel: 50.123. // Int (nullable)
OdometerKm: 1000.123, // Int (nullable)
IsDamaged: false, // Boolean (nullable)
InternalCleaningStatus: 4, // Int (nullable)
ExternalCleaningStatus: 4, // Int (nullable)
IgnitionVoltageLevel: 130 // Int (nullable)
}
The field CategoryLabels and Labels in CategoryTree contain a stringified Json containing pairs “language code”:”localized value”
Value of the InternalCleaningStatus and ExternalCleaningStatus can be one of the VehicleCleaningStatus enumeration.
Get GPS Path
Gets the GPS path for a specific trip:
- GET /v1/billable-trips/{guid}/path
Gets the GPS path for a specific trip
- Parameters
guid (string) – The guid of the trip to search the gps path for
- Status Codes
200 OK – Success
Returns a Json positive response and the GPS path of the trip corresponding to the guid provided:
{
Samples: [ [ key1,lat1,lon1,altitude1 ], [key2,lat2,lon2,altitude2 ], ...], // Int 2D Array
Start: "2001-01-01T01:01:01Z", // DateTime
MinCorner: [double, double], // Double Array (two values)
MaxCorner: [double, double], // Double Array (two values)
MinAltitude: double, // Double (nullable)
MaxAltitude: double, // Double (nullable)
}
Samples: key=Seconds from trip begin; lat=Latitude; lon=Logitude; altitude=Elevation (nullable).
The fields MinCorner `` and ``MaxCorner are arrays of [latitude, longitude]
Possible errores are:
err_NoTripFoundNo trip corresponding to the guid provided in the request
err_NoVehicleThe specified trip does not have a vehicle
Get vehicles
Gets all the vehicles involved in any trip
- GET /v1/billable-trips/vehicles
Gets all the vehicles involved in any trip, for list display purposes
- Status Codes
200 OK – Success
Returns a Json positive response and the list of vehicles:
[
{
ID: 12, // Int
LicensePlate: "AB345TR", // String
Trip: [ Array of Billable Trips Guid ] // Guid Array
},
...
]
Returns a plain Json negative response if ther was any problem retrieving the data.
Extend reservation
Allows the user to ask for an extension of the trip’s reservation
- POST /v1/billable-trips/{guid}/extend
Request a reservation extension for a running trip
- Parameters
guid (string) – The guid of the trip
- Status Codes
200 OK – Success
The API accepts a request body in the following format:
{
EndTime: '2021-01-01 00:00:00' // DateTime
}
and will respond with a response body in the following format:
{
Result: true // Boolean, true if extension accepted, false if refused
}
The API will respond with one of the following errors:
err_NoRunningTripNo trip has been found for the provided guid, or the trip was already closed
err_InvalidEndTimeNo EndTime has been provided, or its value is less or equal to the current authority end time
err_MaxExtensionsReachedThe reservation already reached the maximum number of allowed extensions, expressed in the MAMaxExtensions environment variable
err_CannotRequestExtensionThe reservetion extension request came outside of the allowed grace time period befor the reservation expected end, as expressed in the MAMaxExtensionAdvanceMinutes environment variable
err_TooLongExtensionThe required extension is more than the maximum extension duration, expressed in minutes in the MAMaxExtensionTime environment variable
err_TooShortExtensionThe required extension is less than the minimum extension duration, expressed in minutes in the MAMinExtensionTime environment variable