This API returns the expected positions of the specified real vehicle at a given instant.
This API is not synchronized with the raw position service API, therefore the positions retrieved do not coincide with the results provided by the raw position service API.
Authentication phase
Before using the endpoint, you must run the authentication phase (→ Login).
After the authentication, a session opens and a valid session token persists until:
- The end of the session time-out, that is set through the parameter sessionTimeout (→ OptimaWSI configuration > OptimaAuth section).
- An explicit Logout call (→ Logout).
Request endpoint
Request
GET
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-put/position/vehicle/
Request resource
Not applicable.
Request parameters
| Parameter | Required | Description |
|---|---|---|
|
format |
NO |
Text or bytes type. It defines the format of the response. The default value is bytes. |
|
vehicleId |
NO |
String type. It contains the identifier of the list of vehicles. If not specified, the API returns the positions of all available vehicles running at the specified time. |
|
timeStamp |
NO |
Timestamp type. It contains the reference timestamp to retrieve the vehicles’ locations. The default value is now. |
Request content-type
Not applicable.
Request body (payload)
Not applicable.
Response
Response status
| HTTP status | Description |
|---|---|
|
200 OK |
Result of the processed request. |
|
400 Bad request |
Several conditions can be classified under this code. Generally, where the API has been called with wrong arguments. |
Response content-type
- If format=text, the response content-type is text/plain.
- If format=bytes, the response content-type is application/x-google-protobuf.
Response output
Text containing all information about the positions of the vehicles. Note that the current_status returned value is either INCOMING_AT or STOPPED_AT.
In case of a bad request, a text message is returned, explaining what has caused the problem.
Example
Request
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-put/position/vehicle?vehicleId=M1502&timeStamp=2016-05-27T04:00:00&format=text
Response status
| HTTP status | Description |
|---|---|
|
200 OK |
Result of the processed request. |
Response content-type
text/plain
Response output
header {
gtfs_real time_version: "1.0"
timestamp: 1464335631
}
entity {
id: "1"
vehicle {
trip {
trip_id: "915421"
route_id: "371"
}
position {
latitude: 43.869915
longitude: -79.21608
}
current_stop_sequence: 33
current_status: STOPPED_AT
stop_id: "6165"
vehicle {
id: "M1502"
}
}
}