Updater configuration

This section covers all options that can be set in the router-config.json in the updaters section.

Real-time data

GTFS feeds contain schedule data that is published by an agency or operator in advance. The feed does not account for unexpected service changes or traffic disruptions that occur from day to day. Thus, this kind of data is also referred to as 'static' data or 'theoretical' arrival and departure times.

Real-time data sources are configured in the updaters section is an array of JSON objects, each of which has a type field and other configuration fields specific to that type. Common to all updater entries that connect to a network resource is the url field.

GTFS-Realtime

The GTFS-RT spec complements GTFS with three additional kinds of feeds. In contrast to the base GTFS schedule feed, they provide real-time updates ('dynamic' data) and are updated from minute to minute.

Configuring real-time updaters

Real-time data can be provided using either a pull or push system. In a pull configuration, the GTFS-RT consumer polls the real-time provider over HTTP. That is to say, OTP fetches a file from a web server every few minutes. In the push configuration, the consumer opens a persistent connection to the GTFS-RT provider, which then sends incremental updates immediately as they become available. OTP can use both approaches. The OneBusAway GTFS-realtime exporter project provides this kind of streaming, incremental updates over a websocket rather than a single large file.

Realtime Alerts

Alerts are text messages attached to GTFS objects, informing riders of disruptions and changes.

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "REAL_TIME_ALERTS"	`enum`	The type of the updater.	Required		na
earlyStartSec	`integer`	TODO	Optional	`0`	na
feedId	`string`	TODO	Optional		na
frequencySec	`integer`	TODO	Optional	`60`	na
fuzzyTripMatching	`boolean`	TODO	Optional	`false`	na
url	`string`	TODO	Required		na

// router-config.json
{
    "updaters": [
    {
      "type" : "real-time-alerts",
      "frequencySec" : 30,
      "url" : "http://developer.trimet.org/ws/V1/FeedSpecAlerts/appID/0123456789ABCDEF",
      "feedId" : "TriMet"
    }
  ]

}

TripUpdates

TripUpdates report on the status of scheduled trips as they happen, providing observed and predicted arrival and departure times for the remainder of the trip.

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "STOP_TIME_UPDATER"	`enum`	The type of the updater.	Required		na
backwardsDelayPropagationType	`enum`	How backwards propagation should be handled.	Optional	`"required-no-data"`	2.2
feedId	`string`	Which feed the updates apply to.	Optional		na
frequencySec	`integer`	How often the data should be downloaded in seconds.	Optional	`60`	na
fuzzyTripMatching	`boolean`	If the trips should be matched fuzzily.	Optional	`false`	na
maxSnapshotFrequencyMs	`integer`	TODO	Optional	`-1`	na
purgeExpiredData	`boolean`	Should expired data removed from the snapshot.	Optional	`false`	na
url	`string`	The URL of the GTFS-RT resource.	Required		na

Details

backwardsDelayPropagationType

Since version: 2.2 ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "required-no-data" \ Path: /updaters/[3] \ Enum values: required-no-data | required | always

How backwards propagation should be handled.

REQUIRED_NO_DATA: Default value. Only propagates delays backwards when it is required to ensure that the times are increasing, and it sets the NO_DATA flag on the stops so these automatically updated times are not exposed through APIs.

REQUIRED: Only propagates delays backwards when it is required to ensure that the times are increasing. The updated times are exposed through APIs.

ALWAYS Propagates delays backwards on stops with no estimates regardless if it's required or not. The updated times are exposed through APIs.

// router-config.json
{
    "updaters": [
    {
      "type" : "stop-time-updater",
      "frequencySec" : 60,
      "backwardsDelayPropagationType" : "REQUIRED_NO_DATA",
      "url" : "http://developer.trimet.org/ws/V1/TripUpdate/appID/0123456789ABCDEF",
      "feedId" : "TriMet"
    }
  ]

}

TripUpdates Websocket GTFS RT

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "WEBSOCKET_GTFS_RT_UPDATER"	`enum`	The type of the updater.	Required		na
backwardsDelayPropagationType	`enum`	TODO	Optional	`"required-no-data"`	na
feedId	`string`	TODO	Optional		na
reconnectPeriodSec	`integer`	TODO	Optional	`60`	na
url	`string`	TODO	Optional		na

Details

backwardsDelayPropagationType

Since version: na ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "required-no-data" \ Path: /updaters/[5] \ Enum values: required-no-data | required | always

TODO

// router-config.json
{
    "updaters": [
    {
      "type" : "websocket-gtfs-rt-updater"
    }
  ]

}

Vehicle Positions

VehiclePositions give the location of some or all vehicles currently in service, in terms of geographic coordinates or position relative to their scheduled stops.

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "VEHICLE_POSITIONS"	`enum`	The type of the updater.	Required		na
feedId	`string`	Feed ID to which the update should be applied.	Required		2.2
frequencySec	`integer`	How often the positions should be updated.	Optional	`60`	2.2
url	`uri`	The URL of GTFS-RT protobuf HTTP resource to download the positions from.	Required		2.2

// router-config.json
{
    "updaters": [
    {
      "type" : "vehicle-positions",
      "url" : "https://s3.amazonaws.com/kcm-alerts-realtime-prod/vehiclepositions.pb",
      "feedId" : "1",
      "frequencySec" : 60
    }
  ]

}

Vehicle rental systems using GBFS

Besides GTFS-RT transit data, OTP can also fetch real-time data about vehicle rental networks including the number of bikes and free parking spaces at each station. We support vehicle rental systems from using GBFS feed format.

GBFS is used for a variety of shared mobility services, with partial support for both v1 and v2.2 (list of known GBFS feeds).

Arriving with rental bikes at the destination

In some cases it may be useful to not drop off the rented bicycle before arriving at the destination. This is useful if bicycles may only be rented for round trips, or the destination is an intermediate place.

For this to be possible three things need to be configured:

In the updater configuration allowKeepingRentedBicycleAtDestination should be set to true.
allowKeepingRentedBicycleAtDestination should also be set for each request, either using routing defaults, or per-request.
If keeping the bicycle at the destination should be discouraged, then keepingRentedBicycleAtDestinationCost (default: 0) may also be set in the routing defaults.

Header Settings

Sometimes GBFS Feeds might need some headers e.g. for authentication. For those use cases headers can be configured as a json. Any header key, value can be inserted.

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "VEHICLE_RENTAL"	`enum`	The type of the updater.	Required		na
allowKeepingRentedBicycleAtDestination	`boolean`	If a vehicle should be allowed to be kept at the end of a station-based rental.	Optional	`false`	na
frequencySec	`integer`	How often the data should be updated in seconds.	Optional	`60`	na
language	`string`	TODO	Optional		na
network	`string`	The name of the network to override the one derived from the source data.	Optional		na
sourceType	`enum`	What source of vehicle rental updater to use.	Required		na
url	`string`	The URL to download the data from.	Required		na
headers	`map of string`	HTTP headers to add to the request. Any header key, value can be inserted.	Optional		na

Details

allowKeepingRentedBicycleAtDestination

Since version: na ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: false \ Path: /updaters/[1]

If a vehicle should be allowed to be kept at the end of a station-based rental.

This behaviour is useful in towns that have only a single rental station. Without it you would need see any results as you would have to always bring it back to the station.

network

Since version: na ∙ Type: string ∙ Cardinality: Optional \ Path: /updaters/[1]

The name of the network to override the one derived from the source data.

GBFS feeds must include a system_id which will be used as the default network. These ids are sometimes not helpful so setting this property will override it.

sourceType

What source of vehicle rental updater to use.

headers

Since version: na ∙ Type: map of string ∙ Cardinality: Optional \ Path: /updaters/[1]

HTTP headers to add to the request. Any header key, value can be inserted.

// router-config.json
{
    "updaters": [
    {
      "type" : "vehicle-rental",
      "network" : "socialbicycles_coast",
      "sourceType" : "gbfs",
      "language" : "en",
      "frequencySec" : 60,
      "allowKeepingRentedBicycleAtDestination" : true,
      "url" : "http://coast.socialbicycles.com/opendata/gbfs.json",
      "headers" : {
        "Auth" : "<any-token>",
        "<key>" : "<value>"
      }
    }
  ]

}

Vehicle parking (sandbox feature)

Vehicle parking options and configuration is documented in its sandbox documentation.

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "VEHICLE_PARKING"	`enum`	The type of the updater.	Required		na
facilitiesFrequencySec	`integer`	How often the facilities should be updated.	Optional	`3600`	na
facilitiesUrl	`string`	URL of the facilities.	Optional		na
feedId	`string`	The name of the data source.	Optional		na
hubsUrl	`string`	Hubs URL	Optional		na
sourceType	`enum`	The source of the vehicle updates.	Required		na
timeZone	`time-zone`	The time zone of the feed.	Optional		na
utilizationsFrequencySec	`integer`	How often the utilization should be updated.	Optional	`600`	na
utilizationsUrl	`string`	URL of the utilization data.	Optional		na

Details

feedId

Since version: na ∙ Type: string ∙ Cardinality: Optional \ Path: /updaters/[2]

The name of the data source.

This will end up in the API responses as the feed id of of the parking lot.

sourceType

The source of the vehicle updates.

timeZone

Since version: na ∙ Type: time-zone ∙ Cardinality: Optional \ Path: /updaters/[2]

The time zone of the feed.

Used for converting abstract opening hours into concrete points in time.

// router-config.json
{
    "updaters": [
    {
      "type" : "vehicle-parking",
      "sourceType" : "hsl-park"
    }
  ]

}

SIRI SX updater for Azure Service Bus (sandbox feature)

This is a Sandbox updater se sandbox documentation.

Vehicle Rental Service Directory configuration (sandbox feature)

To configure and url for the VehicleRentalServiceDirectory.