Getting vehicle raw positions from a GTFS feed

This API publishes the vehicle positions similarly to the original GTFS-RT feed.

For details, see GTFS-RT feed information.

The position information in the response body is provided in GTFS format as FeedEntity.VehiclePosition.

Important:  Optima handles GTFS input packets compliant with either GTFS 1.0 and 2.0. The output is compliant with GTFS 1.0, without any data losses with respect to GTFS 2.0.

Every part of the feed that has been discarded - in accordance with the "GTFS feed acceptance criteria" -, is not represented. The endpoint publishes the received positions without modifications only for validated data.

For each unique vehicle, only the most recent received position is available in the output. Vehicles are identified by their ID or by their trip ID. Two vehicle positions refer to the same vehicle if the vehicle positions’ vehicle ID or trip ID is the same.

The endpoint returns only data that is reasonably recent and considered still valid. The configuration parameter TimeToConsiderRealVehicles (given in seconds) provides the validity of the received positions. The endpoint returns only vehicle positions whose timestamp attribute is greater than now() − TimeToConsiderRealVehicles.

If no timestamp is provided for a vehicle position, the timestamp defaults to the timestamp provided in the feed header. If the feed header has no timestamp either, the timestamp defaults to the instant when the data is received (according to the time of the server that receives the information).

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:

Request

GET 

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-put/position/raw

Request parameters

Parameter Required Description

vehicleId

NO

List of vehicle IDs. Only the vehicle positions that match the provided IDs are returned in the output.

tripId

NO

 List of trip IDs. Only the vehicle positions that contain trip descriptors matching the provided trip IDs are returned in the output.

lineId

NO

 List of line IDs. Only the vehicle positions that contain trip descriptors matching the provided route IDs are returned in the output

Request content-type

Not applicable

Request entity

Not applicable

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.
500 Internal server error The endpoint instance is not found.

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 unmodified position information in GTFS format as FeedEntity.VehiclePosition.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-put/position/raw?format=text&vehicleId=C0315

Response status

HTTP status Description
200 OK Result of the processed request.

Response output

header {
  gtfs_real time_version: "1.0"
  incrementality: FULL_DATASET
  timestamp: 1593011046
}
entity {
  id: "2"
  vehicle {
    trip {
      trip_id: "960694"
      route_id: "88"
    }
    position {
      latitude: 43.884167
      longitude: -79.46727
    }
    current_stop_sequence: 41
    current_status: IN_TRANSIT_TO
    timestamp: 1593010931
    stop_id: "350"
    vehicle {
      id: "C0315"
    }
  }
}