Core - Trips
Module dedicated to the trips.
The base url for the APIs in this page is at:
/api/admin
A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.
Get trip
Gets data about a specific trip:
- GET /v1/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 requested trip (Guid of the trip):
{
"CreatedDate": "2020-09-03T06:47:55Z", // DateTime
"Guid": "91de0c8c-ce20-420f-84c7-61b4031c7696", // Guid
"IsCompleted": true, // Boolean
"IsBillable": false, // Boolean
"BillableReason": null, // String (nullable)
"StartLocationName": "Treviso", // String
"EndLocationName": "Treviso", // String (nullable)
"StartLocationLatitude": 45.669532661484325, // Double (nullable)
"StartLocationLongitude": 12.161521911621096, // Double (nullable)
"EndLocationLatitude": 45.669532661484325, // Double (nullable)
"EndLocationLongitude": 12.161521911621096, // Double (nullable)
"EndTimestamp": "2020-09-03T06:48:40Z", // DateTime (nullable)
"StartTimestamp": "2020-09-03T06:47:52Z", // DateTime
"ActualMileageKm": 0, // Int
"ActualDurationSeconds": 0, // Int
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"Duration": 48, // Int (in seconds)
"User": {
"CreatedDate": "2020-02-07T19:48:43Z", // DateTime
"UserName": "gianni.gianni@gmail.com", // String
"Guid": "908d4483-e6fd-4315-9954-751e5ecb8e35", // Guid
"LastLogonTimestamp": "2020-09-03T13:49:44Z", // DateTime
"LCID": 1040, // Int
"Language": "it-IT", // String
"IsConfirmed": true, // Boolean
"IsDisabled": false, // Boolean
"ManualApprovalDate": null, // DateTime (nullable)
"Email": "gianni.gianni@gmail.com", // String
"FullName": "Gianni Gianni", // String
"MobilePhoneNumber": null, // String
"ID": 2101 // Int
},
"MovementAuthority":
{
"CreatedDate": "2020-09-03T06:47:28Z", // DateTime
"StartTime": "2020-09-03T06:50:00Z", // DateTime
"EndTime": "2020-09-03T06:55:00Z", // DateTime
"EndLocationName": "Treviso", // String
"EndLocationAddress": "Via Castage, Treviso", // String
"StartLocationName": "Treviso", // String
"StartLocationAddress": "Via Castagne, Treviso", // String
"StartLocationLatitude": 45.669532661484325, // Double (nullable)
"StartLocationLongitude": 12.161521911621096, // Double (nullable)
"EndLocationLatitude": 45.669532661484325, // Double (nullable)
"EndLocationLongitude": 12.161521911621096, // Double (nullable)
"OriginatorKey": "c8f0ff575299ba1a72e4a20b1...", // String
"OriginatorModule": "32b297..", // Guid
"Guid": "8796ef0c-0b51-4db3-a6ee-20229b35b250", // Guid
"IsConfirmed": true, // Boolean
"IsReadyToStart": true, // Boolean
"MinValidStartTime": "2020-09-03T06:47:28Z", // DateTime
"MaxValidEndTime": "2020-09-03T07:25:00Z", // DateTime
"EquipmentReference": "MV003BB;;3VWSF91C5K78BH0JL0", // String (nullable)
"ServiceReference": null, // String (nullable)
"MaxValidStartTime": "2020-09-03T06:55:00Z", // DateTime
"ActualTripCount": 1, // Int
"MaxTripCount": 1, // Int
"IsDeletable": false, // Boolean
"ID": 2194 // Int
},
"Status": 4, // Int
"ID": 530 // Int
}
Value of the Status field can be one of the TripStatus enumeration.
The BillableReason property may be valorized only if IsBillable is set to true.
Get trips
Gets the list of trips filtered by trip status or time intervals (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/trips/list
Gets the list of trips, whether open or not, between two dates
- Query Parameters
open (boolean) – If True, only open trips. If False, only closed trips. If null, both open and closed trips.
from (string) – The starting date
to (string) – The ending date
- Status Codes
200 OK – Success
The optional parameters for the request are:
open: true or false
from: "2020/01/01 10:00:00"
to: "2020/01/01 22:00:00"
The open parameter allows you to filter trips that are currently open or closed.
If no parameter is provided then all trips will be returned regardless of their status.
The parameters from and to specify the starting time and end time of the trips.
Either parameters are optional, and if none are provided all trips are returned regardless of time intervals.
Returns a list of the trips with the following format:
[
{
"CreatedDate": "2020-09-03T06:47:55Z", // DateTime
"Guid": "91de0c8c-ce20-420f-84c7-61b4031c7696", // Guid
"IsCompleted": true, // Boolean
"IsBillable": false, // Boolean
"BillableReason": null, // String (nullable)
"StartLocationName": "Treviso", // String
"EndLocationName": "Treviso", // String
"StartLocationLatitude": 45.669532661484325, // Double (nullable)
"StartLocationLongitude": 12.161521911621096, // Double (nullable)
"EndLocationLatitude": 45.669532661484325, // Double (nullable)
"EndLocationLongitude": 12.161521911621096, // Double (nullable)
"EndTimestamp": "2020-09-03T06:48:40Z", // DateTime (nullable)
"StartTimestamp": "2020-09-03T06:47:52Z", // DateTime
"ActualMileageKm": 0, // Int
"ActualDurationSeconds": 0, // Int
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"Duration": 48, // Int (in seconds)
"User": {
"CreatedDate": "2020-02-07T19:48:43Z", // DateTime
"UserName": "gianni.gianni@gmail.com", // String
"Guid": "908d4483-e6fd-4315-9954-751e5ecb8e35", // Guid
"LastLogonTimestamp": "2020-09-03T13:49:44Z", // DateTime
"LCID": 1040, // Int
"Language": "it-IT", // String
"IsConfirmed": true, // Boolean
"IsDisabled": false, // Boolean
"ManualApprovalDate": null, // DateTime (nullable)
"Email": "gianni.gianni@gmail.com", // String
"FullName": "Gianni Gianni", // String
"MobilePhoneNumber": null, // String
"ID": 2101 // Int
},
"Status": 4, // Int (enum TripStatus)
"ID": 530 // Int
},
...
]
Value of the Status field can be one of the TripStatus enumeration.
The BillableReason property may be valorized only if IsBillable is set to true.
Get user trips
Gets the list of trips for a specified user (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/trips/user-trips/{user}
Gets the list of trips for a specified user
- Parameters
user (string) – The guid of the user
- Status Codes
200 OK – Success
Returns a Json positive response with the list of all trips for the specified user (Guid of the user):
[
{
"CreatedDate": "2019-09-29T12:25:17Z", // DateTime
"Guid": "1a906d9e-73d0-4116-961a-b0fdbc3aac1d", // Guid
"IsCompleted": true, // Boolean
"IsBillable": false, // Boolean
"BillableReason": null, // String (nullable)
"StartLocationName": "Milan Malpensa Airport - ParkinGO", // String
"EndLocationName": "Milan Malpensa Airport - ParkinGO", // String
"StartLocationLatitude": 45.634623, // Double (nullable)
"StartLocationLongitude": 8.7033, // Double (nullable)
"EndLocationLatitude": 45.9666377, // Double (nullable)
"EndLocationLongitude": 12.9765353, // Double (nullable)
"EndTimestamp": "2019-09-29T12:25:34Z", // DateTime (nullable)
"StartTimestamp": "2019-09-29T12:25:17Z", // DateTime
"ActualMileageKm": 0, // Int
"ActualDurationSeconds": 0, // Int
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"Duration": 16, // Int
"Status": 4, // Int
"ID": 56 // Int
},
...
]
Value of the Status field can be one of the TripStatus enumeration.
The BillableReason property may be valorized only if IsBillable is set to true.
If there is no user corresponding to the Guid provided in the request, it will return a plain Json negative response.
Get trip user
Gets data about the user performing a specified trip:
- GET /v1/trips/{guid}/user
Gets data about the user performing a specified trip
- Parameters
guid (string) – The guid of the trip
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the user of the trip (Guid of the trip):
{
"CreatedDate": "2020-02-07T19:48:43Z", // DateTime
"UserName": "gianni.gianni@gmail.com", // String
"Guid": "908d4483-e6fd-4315-9954-751e5ecb8e35", // Guid
"LastLogonTimestamp": "2020-09-03T13:49:44Z", // DateTime
"LCID": 1040, // Int
"Language": "it-IT", // String
"IsConfirmed": true, // Boolean
"IsDisabled": false, // Boolean
"ManualApprovalDate": null, // DateTime (nullable)
"Email": "gianni.gianni@gmail.com", // String
"FullName": "Gianni Gianni", // String
"MobilePhoneNumber": null, // String
"ID": 2101 // Int
}
Returns a plain Json negative response if the Guid of the trip provided in the request does not correspond to any existing record,
or if there is no user data for that trip.
Open trip
Opens a trip from a movement authority:
- POST /v1/trips/open-trip/{mid}
Opens a trip from a movement authority
- Parameters
mid (integer) – The ID of the movement authority
- Status Codes
200 OK – Success
Returns a Json positive response and the Guid of the opened trip:
{
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784" // Guid
}
Returns a plain Json negative response if there is no current user logged in or if there was a problem opening the trip.
Possible errors are:
err_InvalidAuthorityThe provided ID does not correspond to any existing movement authority
err_AuthorityNotReadyToStartThe movement authority is not marked as ready
err_AuthorityExpiredThe movement authority has no trip and is past its maximum possible start time
err_MaxNumberOfTripsReachedMaximum number of trips reached on the specified movement authority
Close trip
Closes the specified trip:
- POST /v1/trips/close-trip/{t}
Closes a specified trip
- Parameters
t (integer) – The ID of the trip to close
- Status Codes
200 OK – Success
Returns a plain Json positive response if the trip is successfully closed.
Returns a plain Json negative response if there is no current user logged in or if there was a problem closing the trip.
Possible errors are:
err_CannotCloseNoTripNo trip corresponding to the specified trip
err_TripAlreadyClosedThe specified trip is already closed
Download user trips
Gets the list of trips for a specified user as an Excel file:
- GET /v1/trips/download-excel/{user}
Gets the list of trips for a specified user as an Excel file
- Parameters
user (string) – The guid of the user
- Status Codes
200 OK – Success
Returns an excel file with all the trips of the user (Guid of the user) in the time range or nothing if the user was not found.
With a request body like this:
{
startDate: "2020/01/01 10:00:00",
endDate: "2020/01/02 10:00:00"
}
If neither startDate and endDate is valorized, the API will return the list of trips of a specified range of months
(as set in the configuration variable DEFAULT_USER_TRIPS_EXPORT_MONTHS).
If only one of the two parameters is valorized, the other one will be set to cover the specified range of months.
The fields in the Excel sheet are:
Start from
Start at
End to
End at
Duration
Overtime
Completed
BillableReason
Get trip events
Gets the list of events for a trip (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/trips/events/{t}
Gets the list of events for a trip
- Parameters
t (string) – The guid of the trip
- Status Codes
200 OK – Success
Returns a Json positive response and the list of all the events for the trip corresponding to the trip guid provided in the request:
[
{
"Timestamp": "2019-09-29T12:25:34Z", // DateTime
"CreatedDate": "2019-09-29T12:25:34Z", // DateTime
"Latitude": 45.9666377, // Double (nullable)
"Longitude": 12.9765353, // Double (nullable)
"Source": 1, // Int (enum TripEventSource)
"Type": 3, // Int (enum TripEventType)
"AdditionalData": null, // String
"ID": 259 // Int
},
...
]
Value types of Source can be one of the TripEventSource.
Value types of Type can be one of the TripEventType.
Returns a plain Json negative response if the trip guid does not correspond to any existing record.
Get trip details
Gets the list of trip details for a specified trip (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/trips/details/{t}
Gets the list of trip details for a specified trip
- Parameters
t (string) – The guid of the trip
- Status Codes
200 OK – Success
Returns a Json positive response and the list of all the details for the trip corresponding to the trip guid provided in the request:
[
{
"OriginatorKey": "wk-res-groups", // String
"CreatedDate": "2020-09-03T06:48:13Z", // DateTime
"Labels": "{\"en\":\"Actual parking time (s):\",\"it\":\"Tempo effettivo di sosta (s):\"}", // String
"ValueLabels": null, // String (nullable)
"Value": "2ddc0f63-e924-4fba-8e31-fa5803bf1e39", // String
"ValueType": 4, // Int
"ID": 2613 // Int
},
...
]
The value of the OriginatorKey property can be one of the value described in Trip Details.
The ValueType field can be one of the AdditionalValueTypes enumeration.
The type of the contents of the Value field depends on the value specified in ValueType field
Returns a plain Json negative response if the trip guid does not correspond to any existing record.
Get trips exceeding expected duration
Gets the list of trips that need fleet manager intervention:
- GET /v1/trips/exceeding-duration
Gets the list of trips that exceed the estimated duration
- Status Codes
200 OK – Success
Gets the list of trips that exceed the estimated duration:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsCompleted: true, // Boolean
IsBillable: true, // Boolean
BillableReason: null, // String (nullable)
StartLocationName: "London Heathrow", // String
EndLocationName: "London Gatwick", // String
StartLocationLatitude: 51.4700223, // Double (nullable)
StartLocationLongitude: -0.4542955, // Double (nullable)
EndLocationLatitude: 51.1536654, // Double (nullable)
EndLocationLongitude: -0.1842569, // Double (nullable)
EndTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
ActualMileageKm: 600, // Int
ActualDurationSeconds: 1200, // Int
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
Duration: 120, // Int (in seconds)
Status: 4, // Int
Deletiondate: "2001-01-01T01:01:01Z", // DateTime (nullable)
},
...
]
Value of the Status field can be one of the TripStatus enumeration.
The BillableReason property may be valorized only if IsBillable is set to true.
Get attention required trips news
Gets the list of news regarding attention-needing trips:
- GET /v1/trips/attention-reason-news
Gets the list of news regarding attention-needing trips
- Status Codes
200 OK – Success
Returns a Json positive response with the list of news about trips that required attention:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsCompleted: true, // Boolean
IsBillable: true, // Boolean
BillableReason: null, // String (nullable)
StartLocationName: "London Heathrow", // String
EndLocationName: "London Gatwick", // String
StartLocationLatitude: 51.4700223, // Double (nullable)
StartLocationLongitude: -0.4542955, // Double (nullable)
EndLocationLatitude: 51.1536654, // Double (nullable)
EndLocationLongitude: -0.1842569, // Double (nullable)
EndTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
ActualMileageKm: 600, // Int
ActualDurationSeconds: 1200, // Int
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
Duration: 120, // Int (in seconds)
Status: 4, // Int
Deletiondate: "2001-01-01T01:01:01Z", // DateTime (nullable)
},
...
]
Value of the Status field can be one of the TripStatus enumeration.
The BillableReason property may be valorized only if IsBillable is set to true.
Returns a plain Json negative response if there was an error retrieving the list.