Core - Trips
Trips can be autonomously started from the smartphone when the Internet connection is not available. Due to this feature, there is no explicit trip opening/closing API endpoints, but trips are always synchronized with the platform as a list of entities that may or may not already exist on the server.
The platform will automatically integrate such data with data received from on-board devices from the vehicles, and will send back to the User Agent the consolidated trip history.
The trip history contains any started trip, whether it is terminated or not. The User Agent may automatically select to present a different UI to the user if there is an ongoing trip, or it may just inform the user and ask if he/she wants to resume the ongoing trip.
To open a trip, the User Agent must keep locally a list of events associated to the newly-created trip, identified by a Guid. To successfully open a trip, the User Agent must create a Trip entity and an event with the status value of BEGIN.
To close a trip, the User Agent must add an event with the status value of END or ABORT to the event list, and synchronize the trip entity with the platform.
The base url for the APIs in this page is at:
/api/mobile/
A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded here.
Synchronize Trip Data
- POST /v1/trips/sync
Synchronizes the list of trips from the client to the server
- Status Codes
200 OK – Success
Example body data:
{
Trips: [
{
Guid: "7ea07c96-b22a-4423-aa9f-d1438fa06df6", // Guid
MovementAuthority: "6a2f4328-275c-48e4-978d-0e92a58dc6d0", // Guid
DeletionDate: null, // DateTime (nullable)
IsCompleted: true, // Boolean
Status: 1, // Int
Index: 0, // Int
StartLocationName: "Milan", // String
StartLocationLatitude: 45.46417, // Double (nullable)
StartLocationLongitude: 9.19, // Double (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
EndLocationName: "Milan", // String
EndTimestamp: "2001-01-01T02:01:01Z", // DateTime (nullable)
EndLocationLatitude: 45.46417, // Double (nullable)
EndLocationLongitude: 9.19, // Double (nullable)
Details: [
{
Guid: "ca9e1a11-cc86-4525-aadd-9f4ae176b1cd", // Guid
Deletiondate: null, // DateTime (nullable)
OriginatorKey: "", // String
Labels: "", // String (nullable)
ValueLabels: "", // String (nullable)
Value: "123", // String
ValueType: 0 // Int
},
...
],
Events: [
{
Guid: "7806f52d-ef6a-4c2c-a297-b8124728e0f5", // Guid
Timestamp: "2001-01-01T01:01:01Z", // DateTime
Latitude: 45.46418, // Double (nullable)
Longitude: 9.191, // Double (nullable)
Source: 2, // Int
Type: 1, // Int
AdditionalData: "", // String (nullable)
OriginatorKey: null // Guid (nullable)
},
...
],
UserId: "6a2f4328-275c-48e4-978d-0e92a58dc6d0", // Guid
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
ActualDurationSeconds: 3900, // Int (total running time in seconds)
ActualMileageKm: 25, // Int
Duration: 4000 // Int (total trip time in seconds)
},
...
]
}
In this example, a couple of Trips are shown; the first is a completed Trip, the second is in progress.
The response is an array of Trip entities, with the same format as the request, but with data that has been integrated with data on the server. The response will also contain a list of the provided trips that has not been opened due to errors. The format of the response is the following:
{
Trips: [ ... ],
Errors: [{
Trip: "7ea07c96-b22a-4423-aa9f-d1438fa06df6", // Guid of the trip
Code: "10101", // Numeric code of the error
Message: "..." // Localized description of the error
},
{ ... }
]
}
- The error reason may be:
20000: the movement authority provided for the trip has not been found
20001: the trip index is greater than the max trip count accepted by the authority
20002: the user has an already existing trip ongoing
The User Agent is expected to be able to keep and manage local trip creation (i.e. on a
smartphone) when using this API endpoint. The list will return only the trip opened within a
timespan, defined in the configuration variable MAX_TRIP_HISTORY_USER_DAYS.
With this, the User Agent can synchronize trip data by sending its database situation and having the platform reconcile and integrate data from other sources, to finally receive a new list of trip data to trust as the new situation.
Returned data includes a DeletionDate property for each entity (Trip, Detail or Event)
that, if not-null, signals that the related entity has been removed and should not be displayed
anymore to the user. If this property is posted from the User Agent to the platform its value
will be ignored.
For the Trip entity, also a property Status is returned, with a value from the
TripStatus enumeration. Passing this property from the User Agent to the platform
will have no effect, and the value of the Status property in the returned entity will
be coherent with the chronological result of the Events array. The Index property is
a zero-based integer that represents the trip index for the same Movement Authority, if that
allows the user to start more than one trip, to be able to match trip entities on the
platform should the Guids differ on the same trip entity.
For the trip events, the property Source has a value from the TripEventSource
enumeration, and the Type property has a value from the TripEventType enumeration.
The Latitude and Longitude fields must be filled when available. The AdditionalData
property is expected to be a JSON string representing additional data, that may or may not be
displayed to the user, depending on application.
Trip details may include additional data, such as expected weather, traffic, or trip cost
(both estimated or metered), but are not defined as of now. The ValueType field has a
value from the AdditionalValueTypes enumeration.
While on trip, the User Agent is expected to periodically synchronize its local status with the platform, when connection is available, to receive updates from the platform itself. When the trip is closed by the platform (i.e. an administrator operation), the User Agent should inform the user of the event and direct the user to an appropriate UI (i.e. not the trip progress UI if applicable).
The value of the OriginatorKey property of the trip’s details can be one of the value
described in Trip Details.
Retrieve Trip Data
Retrieves the data for a specified trip for the current user
- GET /v1/trips/{trip}
Retrieves the data for a specified trip
- Parameters
trip (string) – Trip GUID
- Status Codes
200 OK – Success
The API will return a response like this:
{
Guid: "d9f1d223-782b-414e-81aa-918cc4105b45", // Guid
MovementAuthority: "840dcbc1-4f53-4878-a0c9-cf5916b6c7dc", // Guid
DeletionDate: null, // DateTime (nullable)
IsCompleted: true, // Boolean
Status: 1, // Int
Index: 0, // Int
StartLocationName: "Milan", // String
StartLocationLatitude: 45.46417, // Double (nullable)
StartLocationLongitude: 9.19, // Double (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
EndLocationName: "Milan", // String
EndTimestamp: "2001-01-01T02:01:01Z", // DateTime (nullable)
EndLocationLatitude: 45.46417, // Double (nullable)
EndLocationLongitude: 9.19, // Double (nullable)
Details: [
{
Guid: "ca9e1a11-cc86-4525-aadd-9f4ae176b1cd", // Guid
Deletiondate: null, // DateTime (nullable)
OriginatorKey: "detail key", // String
Labels: "detail name labels", // JSON stringified array of localized strings (nullable)
ValueLabels: "value labels", // JSON stringified array of localized strings (nullable)
Value: "123", // String
ValueType: 0 // Int
},
...
],
Events: [
{
Guid: "7806f52d-ef6a-4c2c-a297-b8124728e0f5", // Guid
Timestamp: "2001-01-01T01:01:01Z", // DateTime
Latitude: 45.46418, // Double (nullable)
Longitude: 9.191, // Double (nullable)
Source: 2, // Int
Type: 1, // Int
AdditionalData: "", // JSON stringified dictionary (nullable)
OriginatorKey: null // Guid (nullable)
},
...
],
UserId: "6a2f4328-275c-48e4-978d-0e92a58dc6d0", // Guid
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
ActualDurationSeconds: 3900, // Int (total running time in seconds)
ActualMileageKm: 25, // Int
Duration: 4000 // Int (total trip time in seconds)
}
with the data of the specified trip, if it is found and it is related to the current user, or a generic error if the current user is not found.
The value of the OriginatorKey property of the trip’s details can be one of the value
described in Trip Details.
Retrieve Trip History
Retrieves the history of trips for the current user
The API accepts an input body like this:
{
fromDate: "2012-04-23T18:25:43.511Z",
toDate: "2012-04-23T18:25:43.511Z"
}
and returns a list of trips opened inside a time range, defined in the
configuration variable MAX_TRIP_HISTORY_USER_DAYS.
If both dates are sent as null, the system will set the time range as ending at the current time. If only one of the two dates is sent as not null, the system will set the time range as starting/ending at the provided time. If both the dates are sent as not null, the system will check if the defined time range exceedes the configuration variable, and if so will set the time range as ending at the provided end time and overwrite the provided start time.
The API will return a response like this:
{
Trips: [
{
Guid: "d9f1d223-782b-414e-81aa-918cc4105b45", // Guid
MovementAuthority: "840dcbc1-4f53-4878-a0c9-cf5916b6c7dc", // Guid
DeletionDate: null, // DateTime (nullable)
IsCompleted: true, // Boolean
Status: 1, // Int
Index: 0, // Int
StartLocationName: "Milan", // String
StartLocationLatitude: 45.46417, // Double (nullable)
StartLocationLongitude: 9.19, // Double (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
EndLocationName: "Milan", // String
EndTimestamp: "2001-01-01T02:01:01Z", // DateTime (nullable)
EndLocationLatitude: 45.46417, // Double (nullable)
EndLocationLongitude: 9.19, // Double (nullable)
Details: [
{
Guid: "ca9e1a11-cc86-4525-aadd-9f4ae176b1cd", // Guid
Deletiondate: null, // DateTime (nullable)
OriginatorKey: "detail key", // String
Labels: "detail name labels", // JSON stringified array of localized strings (nullable)
ValueLabels: "value labels", // JSON stringified array of localized strings (nullable)
Value: "123", // String
ValueType: 0 // Int
},
...
],
Events: [
{
Guid: "7806f52d-ef6a-4c2c-a297-b8124728e0f5", // Guid
Timestamp: "2001-01-01T01:01:01Z", // DateTime
Latitude: 45.46418, // Double (nullable)
Longitude: 9.191, // Double (nullable)
Source: 2, // Int (enum TripEventSource)
Type: 1, // Int (enum TripEventType)
AdditionalData: "", // JSON stringified dictionary (nullable)
OriginatorKey: null // Guid (nullable)
},
...
],
UserId: "6a2f4328-275c-48e4-978d-0e92a58dc6d0", // Guid
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
ActualDurationSeconds: 3900, // Int (total running time in seconds)
ActualMileageKm: 25, // Int
Duration: 4000 // Int (total trip time in seconds)
},
...
]
}
The API will return a generic error if no user is found for the data set in the provided authentication token.
The value of the IsCompleted property is always set to true for the trip retrieved from this API.
The value of the OriginatorKey property of the trip’s details can be one of the value
described in Trip Details.