This API returns the expected positions of all the real vehicles serving a specified list of lines at a given instant.
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/line
Request parameters
| Parameter | Required | Description |
|---|---|---|
|
format |
NO |
Response format. It can be bytes or text. The default is bytes. |
|
lineId |
NO |
Identifiers of the lines. If not specified, the API returns the position of all vehicles of all available lines running at the specified instant. |
|
timeStamp |
NO |
Reference timestamp for retrieving the positions of the vehicles. The default is now. |
|
gps |
NO |
If true, the API returns only the positions of the vehicles on which some GPS information is available. The default is false. |
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, when the API has been called with wrong arguments. |
Response content-type
If in the request:
- format=bytes, the format of the response is application/x-google-protobuf.
- format=text, the format of the response is text/plain.
Response output
Text containing all information about the expected 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/line?lineId=371&timeStamp=2016-05-27T04:14: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: 1464336708
}
entity {
id: "1"
vehicle {
trip {
trip_id: "915422"
route_id: "371"
}
position {
latitude: 43.864124
longitude: -79.29721
}
current_stop_sequence: 12
current_status: INCOMING_AT
timestamp: 1464322440
stop_id: "express_2754"
}
}
entity {
id: "2"
vehicle {
trip {
trip_id: "915499"
route_id: "371"
}
position {
latitude: 43.843597
longitude: -79.412
}
current_stop_sequence: 43
current_status: INCOMING_AT
timestamp: 1464322440
stop_id: "2807"
vehicle {
id: "M1101"
}
}
}
entity {
id: "3"
vehicle {
trip {
trip_id: "915420"
route_id: "371"
}
position {
latitude: 43.86255
longitude: -79.30406
}
current_stop_sequence: 11
current_status: STOPPED_AT
timestamp: 1464322440
stop_id: "2753"
vehicle {
id: "M1501"
}
}
}