Core - Movement Authorities
Movement Authorities represent the trip reservations; the system can propose many items, and the user can confirm some of them.
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.
Asking for proposals
Once a Transportation Request has been successfully posted, the User Agent receives the Guid of the entity. With this, the User Agent can ask for the proposed Movement Authorities that can fulfill the request.
Such a request produces a streaming response of JSON arrays. There are 15 update events in total, one per second. The arrays are separated by a newline character. It is up to the User Agent to handle the streaming.
Each array contains the Movement Authority proposals that have arrived until the moment the array was issued, so every update event supersedes the previous ones.
- GET /v1/movement-authorities/{tr}
Streams the actual list of proposed MovAuths for the given Transportation Request
- Parameters
tr (string) – Transportation Request GUID
- Status Codes
200 OK – Success
An example of the stream of responses may look like this:
[]
/* then the channel remains silent for 1 second */
[]
/* then the channel remains silent for 1 second */
[]
/* then the channel remains silent for 1 second */
[{
"Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid
"TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid
"OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String
"OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid
"LastUpdated": "2020-09-01T09:21:32Z", // DateTime
"IsConfirmed": false, // Boolean
"IsReadyToStart": false, // Boolean
"DeletionDate": null, // DateTime (nullable)
"StartTime": "2020-09-01T09:31:29Z", // DateTime
"EndTime": "2020-09-01T09:51:29Z", // DateTime
"MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime
"MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime
"MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"StartLocationName": "Milan", // String
"StartLocationAddress": "Piazza Duomo, 1", // String
"StartLocationLatitude": 45.46018980653452, // Double (nullable)
"StartLocationLongitude": 12.21862968891009, // Double (nullable)
"EndLocationName": "Milan", // String
"EndLocationAddress": "Piazza Duomo, 1", // String
"EndLocationLatitude": 45.46018980653452, // Double (nullable)
"EndLocationLongitude": 12.21862968891009, // Double (nullable)
"MaxTripCount": 1, // Int
"RemainingTripCount": 1, // Int
"Details": null, // Object array (nullable)
"EstimatedCost": "10 - 20" // String (nullable)
},
...
]
In this response example JSON data is formatted for clarity, but in the actual data stream there are no newlines inside JSON objects. The newline character is used to separate the streaming event data.
The User Agent should start this long-running request as soon as it receives the Guid after a successful Transportation Request submission.
As soon as some data is received, the User Agent is expected to present and update a list of processed Movement Authority proposals for the user to choose from.
The streaming is composed of 15 events 1 second apart; as soon as the user selects and chooses to confirm a proposal the User Agent can close the connection and/or ignore further events.
The value of the OriginatorKey property of the authority’s details can be one of the value described in Movement Authorities.
Confirm a proposal
- POST /v1/movement-authorities/confirm/{ma}
Sets a MovAuth as confirmed
- Parameters
ma (string) – Movement Authority GUID
- Status Codes
200 OK – Success
As soon as the user decides to confirm one of the proposed Movement Authorities retrieved by the User Agent with the above-mentioned streaming updates request, the User Agent should post this confirmation.
This action will produce a confirmed Movement Authority, otherwise known as a reservation.
List all confirmed
Retrieves the list of all the confirmed and not revoked user’s reservation with trip yet to be started or closed within
a time range defined by the configuration variable MAX_MA_HISTORY_USER_DAYS)
- GET /v1/movement-authorities/list
Lists the Movement Authorities that are still valid or that were expected to terminate less than a set time (by default, a month) ago for the current user
- Status Codes
200 OK – Success
Response example:
[
{
"Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid
"TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid
"OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String
"OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid
"LastUpdated": "2020-09-01T09:21:32Z", // DateTime
"IsConfirmed": false, // Boolean
"IsReadyToStart": false, // Boolean
"DeletionDate": null, // DateTime (nullable)
"StartTime": "2020-09-01T09:31:29Z", // DateTime
"EndTime": "2020-09-01T09:51:29Z", // DateTime
"MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime
"MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime
"MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"StartLocationName": "Milan", // String
"StartLocationAddress": "Piazza Duomo, 1", // String
"StartLocationLatitude": 45.46018980653452, // Double (nullable)
"StartLocationLongitude": 12.21862968891009, // Double (nullable)
"EndLocationName": "Milan", // String
"EndLocationAddress": "Piazza Duomo, 1", // String
"EndLocationLatitude": 45.46018980653452, // Double (nullable)
"EndLocationLongitude": 12.21862968891009, // Double (nullable)
"MaxTripCount": 1, // Int
"RemainingTripCount": 1, // Int
"Details":
[
{
"Guid": "8668be9e-42c0-4af2-878a-64823081c90b", // Guid
"DeletionDate": null, // DateTime (nullable)
"OriginatorKey": "ma-vehicle-license-plate", // String
"Labels": "", // String
"ValueLabels": "", // String
"Value": "AA000XX", // String
"ValueType": 2 // Int (enum)
},
...
],
"EstimatedCost": "10 - 20" // String (nullable)
},
...
]
The implementing User Agent is expected to periodically ask the server about confirmed
Movement Authorities and update a local list accordingly (i.e. keeping track of deletion
and/or other updates). In particular, the platform updates the Details property with
vehicle data as soon as the start time approaches, so the User Agent can present this data
to the user (i.e. the license plate, or the sticker number).
This list can be presented to the user as a list of vehicle reservations. Care must be taken
to present expired reservations with appropriate indication; also, revoked reservations
(i.e. those with a non-null DeletionDate) must be appropriately presented.
The value of the OriginatorKey property of the authority’s details can be one of the value described in Movement Authorities.
List all open reservations
Retrieves the list of all the confirmed and not revoked user’s reservation with trip yet to be started
- GET /v1/movement-authorities/open-authorities
Get open movement authorities for a user
- Status Codes
200 OK – Success
Response example:
[
{
"Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid
"TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid
"OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String
"OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid
"LastUpdated": "2020-09-01T09:21:32Z", // DateTime
"IsConfirmed": false, // Boolean
"IsReadyToStart": false, // Boolean
"DeletionDate": null, // DateTime (nullable)
"StartTime": "2020-09-01T09:31:29Z", // DateTime
"EndTime": "2020-09-01T09:51:29Z", // DateTime
"MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime
"MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime
"MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime
"EquipmentReference": null, // String (nullable)
"ServiceReference": null, // String (nullable)
"StartLocationName": "Milan", // String
"StartLocationAddress": "Piazza Duomo, 1", // String
"StartLocationLatitude": 45.46018980653452, // Double (nullable)
"StartLocationLongitude": 12.21862968891009, // Double (nullable)
"EndLocationName": "Milan", // String
"EndLocationAddress": "Piazza Duomo, 1", // String
"EndLocationLatitude": 45.46018980653452, // Double (nullable)
"EndLocationLongitude": 12.21862968891009, // Double (nullable)
"MaxTripCount": 1, // Int
"RemainingTripCount": 1, // Int
"Details":
[
{
"Guid": "8668be9e-42c0-4af2-878a-64823081c90b", // Guid
"DeletionDate": null, // DateTime (nullable)
"OriginatorKey": "ma-vehicle-license-plate", // String
"Labels": "", // String
"ValueLabels": "", // String
"Value": "AA000XX", // String
"ValueType": 2 // Int (enum)
},
...
],
"EstimatedCost": "10 - 20" // String (nullable)
},
...
]
The value of the OriginatorKey property of the authority’s details can be one of the value described in Movement Authorities.
Revocation
Revokes a confirmed movement authority:
- POST /v1/movement-authorities/revoke/{ma}
Revokes (deletes) a Movement Authority
- Parameters
ma (string) – Movement Authority GUID
- Status Codes
200 OK – Success
The API does not need a request body, and it may respond with a plain error response if the movement authority has not been found for the user, or is not confirmed, or with one of the following error:
err_CannotRevokeThe requested was either already revoked, expired or with an opened trip