Public Transport (PuT) ETA configuration

Public transport data can be either static or real-time data. It is defined:

The standard format used for both input and output data of PuT ETA is General Transit Feed Specification (GTFS).

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.

The proto files defining the real-time data format are:

All PuT static information is contained in a number of text files produced by a mobility agency.

Optima is fully compliant with the following GTFS files, which are all in CSV format.

For additional details, see the official Google documentation .

File Required Description
agency.txt YES One or more transit agencies that provide the data in this feed.
stops.txt YES Individual locations where vehicles pick up or drop off passengers.
routes.txt YES

Transit routes.

A route is a group of trips that are displayed to riders as a single service.
trips.txt YES

Trips for each route.

A trip is a sequence of two or more stops that occurs at a specific time.
stop_times.txt YES Times that a vehicle arrives at and departs from individual stops for each trip.
calendar.txt YES

Dates for service IDs using a weekly schedule.

Specify when service starts and ends, as well as days of the week where service is available.
calendar_dates.txt Optional

Exceptions for the service IDs defined in the calendar.txt file.

If calendar_dates.txt includes all dates of service, this file may be specified instead of calendar.txt.
fare_attributes.txt Optional Fare information for a transit organization's routes.
fare_rules.txt Optional Rules for applying fare information for a transit organization's routes.
shapes.txt Optional Rules for drawing lines on a map to represent a transit organization's routes.
frequencies.txt Optional Headway (time between trips) for routes with variable frequency of service.
transfers.txt Optional Rules for making connections at transfer points between routes.
feed_info.txt Optional Additional information about the feed itself, including publisher, version, and expiration information.

The GTFS-real time protocol supports three different types of real-time data:

  • Trip updates: These updates give a predicted arrival or departure time for stops along the route. Trip updates can also describe more complex scenarios where trips are canceled or added to the schedule, or even re-routed.
  • Service alerts: Service alerts represent more serious issues on the public transport network and are generally in the form of a textual description of the disruption.
  • Vehicle positions: Vehicle position is used to provide automatically generated information on the location of a vehicle, such as from a GPS device on board.

For additional details about GTFS-real time, see the official Google documentation.

Adaptations to the standard

In Public Transport ETA, in order to provide all the above-mentioned services, we use a modified version of the GTFS-real time standard file gtfs-real time.proto. Changes to the standard file are mandatory for Optima to work. The necessary modifications are listed in the table below.

Moreover, Optima extends the original GTFS-real time standard by gtfs-real time-optima-ext.proto. The extension introduces a new entity, called Transfer, used to provide information about transfer alerts (→ Public transport API).

Important:  Take care of the fact that for the vehicle position message either the current stop sequence or the stop ID must be provided. This is to enable the ETA service to work seamlessly. In case the current stop sequence and the stop ID are both provided, the ETA computation is based on the stop sequence.

The following table lists the differences between the GTFS-real time standard and the optima.proto file.

GTFS-real time message Message field Original value Modified value Reason of modification
TripDescriptor Trip_id Optional Mandatory Needed by APIs managing PuT events
TripDescriptor Route_id Optional Mandatory Needed by APIs managing PuT events
StopTimeUpdate Stop_sequence Optional Mandatory Needed by APIs managing PuT events
StopTimeUpdate Stop_id Optional Mandatory Needed by APIs managing PuT events
VehiclePosition Current_stop_sequence Optional Mandatory if the next vehicle position is not provided Needed by APIs managing PuT ETA
VehiclePosition Stop_id Optional Mandatory if the previous vehicle position is not provided Needed by APIs managing PuT ETA

Important:  In some PuT API (see → Public transport) you find the parameter public_stop_id. It is the string identifier of a stop and its meaning is coherent with the definition of stop_id as specified in the GTFS static model.

The information modeled in PTV Visum for the PuT ETA integration, are mapped to the PTV Optima DB through  TDE (→ Transportation Data Exchange (TDE)).

The mapping is described in the table:

DB Visum

DB Optima

Description

STOP POINT

tstp

See tstp table.

STOP AREA

stop_area

See stop_area table.

STOP

Not modeled in Optima

N.A.

STOP SECTION

stop

Optima stop section models the shape of the path between two consecutive stops.

See stop table.

LINE ROUTE

line_route

See line_route table.

VEHICLE JOURNEY

runs

See runs table.

TIMETABLE

ttab

See ttab table.

Important:  Optima model is simplified than VISUM modelling, so even though there is a correspondence, it is not always a 1-1 mapping.

The information modeled in GTFS RT feed for the PuT ETA integration, are mapped to the PTV Optima DB through the PuT ETA GTFS-RT import process.

The mapping is described in the table:

GTFS RT

DB Optima

Description

stop_id

tstp

See tstp.public_stop_id field.

Trip.trip_id

runs

See runs.idno field.

Trip.route_id

line

See line.idno field.

StopTimeUpdate.stop_sequence

stop

See stop.stop_sequence field.

Vehicle.idno

vehicles_put

See vehicles_put.idno field.

This field is set automatically by the PuT ETA GTFS-RT import process.

PuT ETA is configured in the XML file:

/opt/ptv-optima-vv.n.xxxx/ptv-optima-as/standalone/configuration/optima/optima-configuration.xml.

In the following sections we describe the parent and child elements required. To localize a specific XML object, we use XPath notation.

You can set a specific threshold parameter for tracking the detour of a vehicle:

Element Description

configurations/configuration

[@name='optima']/optima-put/@realVehicleDetourDistance

Detour distance, measured in meters.

If the distance between the real vehicle position and the referenced stop section is greater than this threshold, then the vehicle is considered in detour.

Optima can manage GTFS-real time feeds either in PULL or in PUSH mode.

  • PULL mode: Optima is scheduled to read the real-time feed constantly.
  • PUSH mode: Optima is fed asynchronously.

Important:  Only use one of both feeding methods, otherwise one method overwrite the other and you can not distinguish the data feeding mode.

To feed PTV Optima in PULL mode, set the element:

Element Description

configurations/configuration

[@name='optima']/datex-interface/

datex-process[@name=’GTFS vehicle position’]/provider

[@name=’gtfs_vehicle_position_import’]/endpoint

URL where to get the GTFS-real time feed.

If you want to work in PUSH mode, remove from the configuration file the XML element:

datex-process[@name=’GTFS vehicle position']

and all its child elements, up to its closing tag </datex-process>.

In some cases, the REST APIs used to get real-time vehicle position feeds require to define an header associated to a specific protocol (for example an HTTP header).

For this reason you can set an optional configuration node

<configurations>/<configuration>/<datex-interface>/<

<datex-process[@name="GTFS vehicle position"]>/<provider

[@name="gtfs_vehicle_position_import"]>/<httpHeaders>.

Important:  The endpoint could be a resource not relying on HTTP or HTTPS (like a local file or an FTP resource); in those cases, the HTTP headers defined in the configuration are ignored.

Each header node represents a new header (key and value).

Element Description 
<?xml version="1.0" encoding="UTF-8">
<configurations>
........
        <provider action="IMPORT" name="gtfs_vehicle_position_import" type="...">
            <!--
            ===================================================
            Change the <endpoint> accordingly to the study area
            ===================================================
            -->
            <endpoint>http://...</endpoint>
            <httpHeaders>
                <header key="Authorization" value="apikey tfvFhuLhX4lDM5l24gtxFZVOYBejdFjWjHVA" />
                <header key="CustomKey" value="CustomValue" />
            </httpHeaders>
        </provider>
........
</configurations>

Each <header> node represents a new header to be used for the HTTP request, for the specified endpoint.

The key and value specified are depending by the <endpoint> design.

This section contains configuration parameters related to the timetable, which are included in the timeTableInCache XML element.

Element Description

configurations/configuration
[@name='optima']/timeTableInCache/
numberOfDaysInCache

Number of days after the startingDay of the service to be loaded.

  • If not specified or set to 0, the PuT module loads at most three days of the PuT calendar.
  • If set to a negative value, the PuT module loads all days of the available PuT calendar.

configurations/configuration
[@name='optima']/
timeTableInCache/startingDay

Reference date for the loading process. The Public Transport ETA module loads the timetable elements from the Optima database with the following day bounds:

  • startingDay−1
  • startingDay+numberOfDaysInCache

Format: yyyyMMdd

Special values:

  • first (or FIRST)=first day of the PuT calendar as defined in the Optima database
  • not set or empty=now()

configurations/configuration
[@name='optima']/
timeTableInCache/updateProcess/
@enabled

Enables or disables the background process to import days.

configurations/configuration

[@name='optima']/ timeTableInCache/updateProcess/

schedule

Schedule of the background process to import days in cron syntax (see here for cron syntax documentation).

This section contains configuration parameters related to the SUP, which are included in the scheduleUpdate element of the optima-put/configurations element.

Element Description

configuration[@name='optima']/optima-put/scheduleUpdate/@enabled

Enable or disable SUP.

configuration[@name='optima']/optima-put/scheduleUpdate/@enabledManualUpdate

Enable or disable the possibility to manually run a SUP using the endpoint: SERVER_ADDRESS/optima-put/schedule/update/run?instant=2014-03-27T06:12:00

(SERVER_ADDRESS is the Optima application server root address. Example: /https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>

configuration[@name='optima']/optima-put/scheduleUpdate/schedule

PuT schedule.

Subelements configure the corresponding values of a standard Java EE ScheduleExpression (see here).

configuration[@name='optima']/optima-put/scheduleUpdate/vehiclesToConsider

Vehicle types to consider in SUP.

Possible values:

  • real = only real vehicles
  • virtual = only virtual vehicles
  • empty string = consider both real and virtual vehicles

Default: empty string

configuration[@name='optima']/optima-put/scheduleUpdate/
timeToConsiderRealVehicles

Identifies the time window of real vehicles to be considered. The SUP takes into account all real vehicles that have a "last updated" instant not older than SUP instant minus timeToConsiderRealVehicles.

If the value is < 0, all available real vehicles are considered.

Type: Integer

Default: 300

Unit: s

configuration[@name='optima']/optima-put/scheduleUpdate/nocturnalMaxTime

Time interval from midnight to consider nocturnal services in SUP:

Example: If the update time instant is 2017/03/30 05:25 and nocturnalMaxTime = 07:00:00, then the search for the active runs is made at 2017/03/29 29:25 (24:00 + 05:25) and 2017/03/30 05:25.

Format: HHmmss

Default = 70000

configuration[@name='optima']/optima-put/
scheduleUpdate/
timeToConsiderVirtualVehicles

Time interval in which virtual vehicles start service.

If, for example, the configuration parameter is equal to 10000 (1 hour), then the update process considers all virtual vehicles starting in 1 hour from the SUP time.

If the value = 0, the Public Transport ETA module considers only virtual vehicles that are running at the SUP starting instant.

Format: HHmmss

Default: 0

configuration[@name='optima']/optima-put/scheduleUpdate/timeToDeleteStoppedRuns

Time after which stopped runs will be deleted and a waiting vehicle is considered stuck

If, during SUP, a run encounters a closed street, it stops at the beginning of this street. Its arrival times at the next stops are set to "maximum available" (→ Public Transport ETA methodology), and the vehicles are removed from the timetable (because they are considered unreliable) if they remain stuck until an instant given by the planned arrival time at the last stop of the run plus the timeToDeleteStoppedRuns amount of seconds.

Example: If a run is planned to arrive at its destination at 08:00:00 and it gets stuck at an intermediate stop at 10:01:00, it will be discarded because it arrives more than 2 hours behind schedule at the last stop.

This parameter is also used as a threshold to determine if a vehicle that encounters a road closure is stuck. More precisely, a vehicle will be marked as stuck if its waiting time is greater than this threshold.

Default: 7200

Unit: s