Getting expected positions of vehicles by trips and time

This API returns the expected positions of all the real vehicles serving a specified list of trips 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/trip/

Request parameters

Parameter	Required	Description
format	NO	Response format. It can be bytes or text. The default is bytes.
tripId	NO	Identifiers of the trips. If not specified, the API returns the position of all vehicles of all available trips 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 for 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, where 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/trip?tripId=915420&timeStamp=2016-05-27T04:10: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: 1464336517
}
entity {
  id: "1"
  vehicle {
    trip {
      trip_id: "915420"
      route_id: "371"
    }
    position {
      latitude: 43.85547
      longitude: -79.33485
    }
    current_stop_sequence: 6
    current_status: STOPPED_AT
    stop_id: "2745"
    vehicle {
      id: "M1501"
    }
  }
}