Acquiring positions of vehicles by time (PUSH mode)

You can use this endpoint if the Optima PuT component is running in PUSH mode, therefore Optima waits to be fed by a data provider.

For the GTFS data format, see → GTFS feed acceptance criteria.

For the configuration of the GTFS feed, see → GTFS real-time feed.

The endpoint manages data according to the GTFS data format, described in:

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:

Full Data vs. Partial Data

Optima considers every vehicle feed either as a full data set or as a partial one.

  • For a full data set feed, old data is fully replaced by new data.
  • For a partial data set feed, the data is added and merged with the old data.

The behavior is triggered by an option of the GTFS data feed called Incrementality.

  • When Incrementality is set to DIFFERENTIAL, the service does not delete the old data and merge it to the arriving new data.
  • When Incrementality is set to FULL_DATASET, every feed update overwrites the old data.

Example:

header {
  gtfs_real time_version: "1.0"
  incrementality: DIFFERENTIAL
  timestamp: 1464269975
}
entity {
  id: "1"
  vehicle {
.....
  }
}

If in the GTFS feed is not present the element incrementality, the default value is FULL_DATASET.

Vehicle localization

The vehicle position is deduced from the feed by looking at:

  • the current_stop_sequence field, if it exists.
  • the stop_id, if the previous parameters does not exist.

The current stop_sequence is preferred to the stop_id for lines with loops, such as circular lines, where a stop can be identified by a stop_id, but more often by a current_stop_sequence.

Vehicle status

If the entity element current_status is not provided, it is estimated using:

  • position
  • trip_id
  • current_stop_sequence (provided or estimated).

Vehicle timestamp

If the entity element timestamp is not provided, the header timestamp is used.

If the latter is also not provided, it is the instant in which the feed is read that is considered.

Clearing old data

In a new feed, Optima performs a cleanup.

Any vehicle information is removed from the dataset if it is older than the current time plus an offset specified by the configuration parameter timeToConsiderRealVehicles (see → Public Transport (PuT) ETA configuration).

The process of merging vehicles works as follows:

  1. Identify the conflicting vehicles according to the associated trip_id and vehicle id.
  2. If the feed has a timestamp that is before now() − timeToConsiderRealVehicles, ignore the feed.
  3. If trip_id or vehicle id is not in the system, add the feed.

  4. If trip_id or vehicle id is already in the system:

    • If the feed has no timestamp or if the timestamp is newer than the previous one, data is overwritten and eventually the missing trip_id or the missing vehicle id is added after removing possible old entities with similar IDs.
    • If the feed has a timestamp that is older than the previous one, data is not updated.

Request

POST 

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

Request resource

Not applicable.

Request parameters

Not applicable.

Request content-type

application/x-google-protobuf

Request body (payload)

Binary file containing all information about the position of the vehicles.

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

Not applicable

Response output

Not applicable