Skip to content

Updater configuration

This section covers options that can be set in the updaters section of router-config.json. See the parameter summary and examples in the router configuration documentation

Real-time data are those that are not added to OTP during the graph build phase but during runtime.

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.

GTFS-Realtime

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.

GTFS-Realtime 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.

Alerts

Alerts are text messages attached to GTFS objects, informing riders of disruptions and changes. The information is downloaded in a single HTTP request and polled regularly.

Config Parameter Type Summary Req./Opt. Default Value Since
type = "real-time-alerts" enum The type of the updater. Required 1.5
earlyStartSec integer How long before the posted start of an event it should be displayed to users Optional 0 1.5
feedId string The id of the feed to apply the alerts to. Required 1.5
frequency duration How often the URL should be fetched. Optional "PT1M" 1.5
fuzzyTripMatching boolean Whether to match trips fuzzily. Optional false 1.5
url string URL to fetch the GTFS-RT feed from. Required 1.5
headers map of string HTTP headers to add to the request. Any header key, value can be inserted. Optional 2.3
Parameter details

headers

Since version: 2.3 ∙ Type: map of string ∙ Cardinality: Optional
Path: /updaters/[0]

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

Example configuration
// router-config.json
{
  "updaters" : [
    {
      "type" : "real-time-alerts",
      "frequency" : "30s",
      "url" : "http://developer.trimet.org/ws/V1/FeedSpecAlerts/appID/0123456789ABCDEF",
      "feedId" : "TriMet",
      "headers" : {
        "Some-Header" : "A-Value"
      }
    }
  ]
}

TripUpdates via HTTP(S)

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. The information is downloaded in a single HTTP request and polled regularly.

Config Parameter Type Summary Req./Opt. Default Value Since
type = "stop-time-updater" enum The type of the updater. Required 1.5
backwardsDelayPropagationType enum How backwards propagation should be handled. Optional "required-no-data" 2.2
feedId string Which feed the updates apply to. Required 1.5
frequency duration How often the data should be downloaded. Optional "PT1M" 1.5
fuzzyTripMatching boolean If the trips should be matched fuzzily. Optional false 1.5
url string The URL of the GTFS-RT resource. Required 1.5
headers map of string HTTP headers to add to the request. Any header key, value can be inserted. Optional 2.3
Parameter details

backwardsDelayPropagationType

Since version: 2.2 ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "required-no-data"
Path: /updaters/[5]
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.

url

Since version: 1.5 ∙ Type: string ∙ Cardinality: Required
Path: /updaters/[5]

The URL of the GTFS-RT resource.

file: URLs are also supported if you want to read a file from the local disk.

headers

Since version: 2.3 ∙ Type: map of string ∙ Cardinality: Optional
Path: /updaters/[5]

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

Example configuration
// router-config.json
{
  "updaters" : [
    {
      "type" : "stop-time-updater",
      "frequency" : "1m",
      "backwardsDelayPropagationType" : "REQUIRED_NO_DATA",
      "url" : "http://developer.trimet.org/ws/V1/TripUpdate/appID/0123456789ABCDEF",
      "feedId" : "TriMet",
      "headers" : {
        "Authorization" : "A-Token"
      }
    }
  ]
}

Streaming TripUpdates via MQTT

This updater connects to an MQTT broker and processes TripUpdates in a streaming fashion. This means that they will be applied individually in near-realtime rather than in batches at a certain interval.

This system powers the realtime updates in Helsinki and more information can be found on Github.

Config Parameter Type Summary Req./Opt. Default Value Since
type = "mqtt-gtfs-rt-updater" enum The type of the updater. Required 1.5
backwardsDelayPropagationType enum How backwards propagation should be handled. Optional "required-no-data" 2.2
feedId string The feed id to apply the updates to. Required 2.0
fuzzyTripMatching boolean Whether to match trips fuzzily. Optional false 2.0
qos integer QOS level. Optional 0 2.0
topic string The topic to subscribe to. Required 2.0
url string URL of the MQTT broker. Required 2.0
Parameter details

backwardsDelayPropagationType

Since version: 2.2 ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "required-no-data"
Path: /updaters/[6]
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.

Example configuration
// router-config.json
{
  "updaters" : [
    {
      "type" : "mqtt-gtfs-rt-updater",
      "url" : "tcp://pred.rt.hsl.fi",
      "topic" : "gtfsrt/v2/fi/hsl/tu",
      "feedId" : "HSL",
      "fuzzyTripMatching" : true
    }
  ]
}

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. The information is downloaded in a single HTTP request and polled regularly.

Config Parameter Type Summary Req./Opt. Default Value Since
type = "vehicle-positions" enum The type of the updater. Required 1.5
feedId string Feed ID to which the update should be applied. Required 2.2
frequency duration How often the positions should be updated. Optional "PT1M" 2.2
fuzzyTripMatching boolean Whether to match trips fuzzily. Optional false 2.5
url uri The URL of GTFS-RT protobuf HTTP resource to download the positions from. Required 2.2
features enum set Which features of GTFS RT vehicle positions should be loaded into OTP. Optional 2.5
headers map of string HTTP headers to add to the request. Any header key, value can be inserted. Optional 2.3
Parameter details

features

Since version: 2.5 ∙ Type: enum set ∙ Cardinality: Optional
Path: /updaters/[7]
Enum values: position | stop-position | occupancy

Which features of GTFS RT vehicle positions should be loaded into OTP.

headers

Since version: 2.3 ∙ Type: map of string ∙ Cardinality: Optional
Path: /updaters/[7]

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

Example configuration
// router-config.json
{
  "updaters" : [
    {
      "type" : "vehicle-positions",
      "url" : "https://s3.amazonaws.com/kcm-alerts-realtime-prod/vehiclepositions.pb",
      "feedId" : "1",
      "frequency" : "1m",
      "headers" : {
        "Header-Name" : "Header-Value"
      },
      "fuzzyTripMatching" : false,
      "features" : [
        "position"
      ]
    }
  ]
}

GBFS vehicle rental systems

Besides GTFS-RT transit data, OTP can also fetch real-time data about vehicle rental networks including the number of vehicles and free parking spaces at each station. We support vehicle rental systems that use the GBFS standard.

GBFS can be used for a variety of shared mobility services, with partial support for both v1 and v2.2 (list of known GBFS feeds). OTP supports the following GBFS form factors:

  • bicycle
  • scooter
  • car
Config Parameter Type Summary Req./Opt. Default Value Since
type = "vehicle-rental" enum The type of the updater. Required 1.5
allowKeepingRentedVehicleAtDestination boolean If a vehicle should be allowed to be kept at the end of a station-based rental. Optional false 2.1
frequency duration How often the data should be updated. Optional "PT1M" 1.5
geofencingZones boolean Compute rental restrictions based on GBFS 2.2 geofencing zones. Optional false 2.3
language string TODO Optional 2.1
network string The name of the network to override the one derived from the source data. Optional 1.5
overloadingAllowed boolean Allow leaving vehicles at a station even though there are no free slots. Optional false 2.2
sourceType enum What source of vehicle rental updater to use. Required 1.5
url string The URL to download the data from. Required 1.5
headers map of string HTTP headers to add to the request. Any header key, value can be inserted. Optional 1.5
rentalPickupTypes enum set This is temporary and will be removed in a future version of OTP. Use this to specify the type of rental data that is allowed to be read from the data source. Optional 2.7
Parameter details

allowKeepingRentedVehicleAtDestination

Since version: 2.1 ∙ 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.

In some cases it may be useful to not drop off the rented vehicle before arriving at the destination. This is useful if vehicles 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 allowKeepingRentedVehicleAtDestination should be set to true.
  • allowKeepingRentedVehicleAtDestination should also be set for each request, either using routing defaults, or per-request.
  • If keeping the vehicle at the destination should be discouraged, then keepingRentedVehicleAtDestinationCost (default: 0) may also be set in the routing defaults.

geofencingZones

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

Compute rental restrictions based on GBFS 2.2 geofencing zones.

This feature is somewhat experimental and therefore turned off by default for the following reasons:

  • It delays start up of OTP. How long is dependent on the complexity of the zones. For example in Oslo it takes 6 seconds to compute while Portland takes 25 seconds.
  • It's easy for a malformed or unintended geofencing zone to make routing impossible. If you encounter such a case, please file a bug report.

network

Since version: 1.5 ∙ 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

Since version: 1.5 ∙ Type: enum ∙ Cardinality: Required
Path: /updaters/[1]
Enum values: gbfs | smoove

What source of vehicle rental updater to use.

headers

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

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

rentalPickupTypes

Since version: 2.7 ∙ Type: enum set ∙ Cardinality: Optional
Path: /updaters/[1]
Enum values: station | free-floating

This is temporary and will be removed in a future version of OTP. Use this to specify the type of rental data that is allowed to be read from the data source.

  • station Stations are imported.
  • free-floating Free-floating vehicles are imported.
Example configuration
// router-config.json
{
  "updaters" : [
    {
      "type" : "vehicle-rental",
      "network" : "socialbicycles_coast",
      "sourceType" : "gbfs",
      "language" : "en",
      "frequency" : "1m",
      "allowKeepingRentedVehicleAtDestination" : false,
      "geofencingZones" : false,
      "url" : "http://coast.socialbicycles.com/opendata/gbfs.json",
      "headers" : {
        "Auth" : "<any-token>",
        "<key>" : "<value>"
      }
    }
  ]
}

Other updaters in sandboxes