Core - Trips ============ .. Last update: 02/09/2020 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 :download:`here `. Synchronize Trip Data --------------------- .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/trips/sync 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 :ref:`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 :ref:`enum-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 :ref:`enum-tripeventsource` enumeration, and the ``Type`` property has a value from the :ref:`enum-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 :ref:`enum-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 :ref:`details-trips`. Retrieve Trip Data ------------------ Retrieves the data for a specified trip for the current user .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/trips/{trip} 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 :ref:`details-trips`. Retrieve Trip History --------------------- Retrieves the history of trips for the current user .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/trips/history 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 :ref:`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 :ref:`details-trips`.