Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

GTFS-Flex v2

Flexible public transit services in GTFS.

Overview

GTFS-Flex v2 is composed of two extensions that aim to model the variety of demand responsive services that do not always follow the same fixed stops. The following two extensions address this need:

Extension name Description
GTFS-FlexibleTrips Flexible services that operate according to some schedule but are responsive to on-demand requests of individual riders.
GTFS-BookingRules Booking information for rider-requested services using GTFS-FlexibleTrips, such as how far in advance booking should occur or a phone number that should be called.

GTFS-FlexibleTrips

Goals

This extension describes services that operate according to a schedule, but also include one or more flexible features, such as:

  • Dial-a-ride service: the vehicle serves a zone where pickups and drop offs are allowed during certain service hours.
  • Route deviation services: the vehicle serves a fixed route and ordered set of stops, and may detour to pick up or drop off a passenger between stops.
  • Point-to-zone service: the rider can board at a fixed stop such as a train station, and then alight anywhere within an area, or vice versa. Departures from some locations are scheduled or timed with other services.
  • Point deviation or checkpoint service: the rider can board at a fixed stop, and then alight anywhere among an unordered list of stops, or the opposite. The driver only serves stops at which a request is made.
  • Hail-and-ride services: the vehicle stays along a fixed path, but the rider can request a stop anywhere along the path to board or alight.

GTFS-FlexibleTrips describes the times when and locations where flexible service can be requested.

Overview

This extension

  • Describes locations and groups of locations where riders can request pickup or drop off: these locations are included in new files called location_groups.txt and locations.geojson
  • Indicates the times when services are available at on demand locations and the expected travel times: new fields in stop_times.txt provide ranges that equate to service hours and expected travel times on demand trips
  • Clarifies elements of the current specification necessary to inform data consumers of how to interpret the above files and fields added: new fields in stop_times.txt provide ranges that equate to service hours or expected traversal times for locations

Requirements

None. Extends the GTFS.

In order for a trip planner to provide a user with information about how to request many flexible services, data producers must also provide information according to the GTFS-BookingRules extension.

Files extended or added

File name State Defines
location_groups.txt Added (Optional file) Adds location groups. Location groups are groups of stops and GeoJSON locations, which allow predetermined groups of these features to be specified on individual rows of stop_times.txt.
locations.geojson Added (Optional file) Adds GeoJSON locations, which are LineString, MultiLineString, Polygon and MultiPolygon features that indicate groups of lat/lon coordinates where riders can request either pickup or drop off.
stop_times.txt Extended and modified

File definitions

location_groups.txt (file added)

Field Name Type Required Description
location_group_id ID Required Identifies a location group. A location group is a group of stops or GeoJSON locations that together indicate locations where a rider may request pickup or drop off.

By default, every stop_id and id from locations.geojson belongs to a location_group_id of the same value. Therefore, it is forbidden to define a location_group_id with the same value as a stop_id or id from locations.geojson.

Multiple entries in location_groups.txt can have the same location_group_id.
location_id ID referencing stops.stop_id or id from locations.geojson Optional Identifies a stop or location belonging to the location group.
location_group_name Text Optional Name of the location group. Must be defined either once, or exhaustively for a single location_group_id.

locations.geojson (file added)

  • This file uses a subset of the GeoJSON format, described in RFC 7946.
  • The locations.geojson file must contain a FeatureCollection.
  • A FeatureCollection defines various stop locations where riders may request pickup or drop off.
  • Every GeoJSON Feature must have an id. The id belongs to the same namespace as stop_id in stops.txt and location_group_id in location_groups.txt, called “stop locations”.
  • Every GeoJSON Feature should have objects and associated keys according to the table below:
Field Name Required Type Description
type Required String "FeatureCollection" of locations.
features Required Array Collection of "Feature" objects describing the locations.
 - type Required String "Feature"
 - id Required String Location ID belonging to the same namespace as stops.stop_id. Therefore, it is forbidden to define an id from locations.geojson with the same value as a stops.stop_id.

By default, every id from locations.geojson belongs to a location_groups.location_group_id of the same value.
 - properties Required Object Location property keys.
  - stop_name Optional String Indicates the name of the location as displayed to riders.
  - stop_desc Optional String Meaningful description of the location to help orient riders.
  - zone_id Conditionally Required String Identifies the fare zone for a stop.

Conditionally required:
- Required if fare_rules.txt is defined.
- Optional otherwise.
  - stop_url Optional URL URL of a web page about the location.

If provided, the URL should be different from the agency.agency_url and the routes.route_url field values.
 - geometry Required Object Geometry of the location.
  - type Required String Must be of type:
"Point"
"MultiPoint"
"Linestring"
"MutiLineString"
"Polygon"
"MultiPolygon"
  - coordinates Required Array Geographic coordinates (latitude and longitude) defining the geometry of the location.

stop_times.txt (file extended)

Field Name Type Required Description
stop_id ID referencing stops.stop_id, location_groups.location_group_id, or id from locations.geojson Required Identifies the serviced stop. All stops serviced during a trip must have a record in stop_times.txt. Referenced locations must be stops, not stations or station entrances. A stop may be serviced multiple times in the same trip, and multiple trips and routes may service the same stop.

If service is on demand, a GeoJSON location or location group can be referenced:
id from locations.geojson
location_groups.location_group_id
arrival_time Time Conditionally Required Arrival time at a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time.

Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. If this stop is not a timepoint, it is recommended to provide an estimated or interpolated time. If this is not available, arrival_time can be left empty. Further, indicate that interpolated times are provided with timepoint=0. If interpolated times are indicated with timepoint=0, then time points must be indicated with timepoint=1. Provide arrival times for all stops that are timepoints.

Conditionally Required:
Required for the first and the last stop in a trip.
Forbidden when stop_times.start_pickup_dropoff_window or stop_times.end_pickup_dropoff_window are defined.
departure_time Time Conditionally Required Departure time from a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for arrival_time and departure_time. See the arrival_time description for more details about using timepoints correctly.

The departure_time field should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints.

Conditionally Required:
Required for the first and the last stop in a trip.
Forbidden when stop_times.start_pickup_dropoff_window or stop_times.end_pickup_dropoff_window are defined.
start_pickup_dropoff_window Time Conditionally Required Time that on-demand service becomes available in a GeoJSON location, location group or stop.

Conditionally Required:
Required if stop_times.stop_id refers to location_groups.location_group_id or id from locations.geojson.
Forbidden if stop_times.arrival_time or stop_times.departure_time are defined.
end_pickup_dropoff_window Time Conditionally Required Time that on-demand service ends in a GeoJSON location, location group or stop.

Conditionally Required:
Required if stop_times.stop_id refers to location_groups.location_group_id or id from locations.geojson.
Forbidden if stop_times.arrival_time or stop_times.departure_time are defined.
pickup_type Enum Conditionally Forbidden Indicates pickup method. Valid options are:

0 or empty - Regularly scheduled pickup.
1 - No pickup available.
2 - Must phone agency to arrange pickup.
3 - Must coordinate with driver to arrange pickup.

Conditionally Forbidden:
- pickup_type=0 forbidden for stop_times.stop_id referring to location_groups.location_group_id or id from locations.geojson.
- pickup_type=3 forbidden for location_groups.location_group_id or locations.geojson that are not a single "LineString".
- Optional otherwise.
drop_off_type Enum Conditionally Forbidden Indicates drop off method. Valid options are:

0 or empty - Regularly scheduled drop off.
1 - No drop off available.
2 - Must phone agency to arrange drop off.
3 - Must coordinate with driver to arrange drop off.

Conditionally Forbidden:
- drop_off_type=0 forbidden for stop_times.stop_id referring to location_groups.location_group_id or id from locations.geojson.
- Optional otherwise.
mean_duration_factor

and

mean_duration_offset
Float Conditionally Forbidden Together, mean_duration_factor and mean_duration_offset allow an estimation of the duration a rider’s trip will take, in minutes, using the on-demand service in a GeoJSON location or location group.

Data consumers are expected to use mean_duration_factor and mean_duration_offset to make the following calculation:

MeanTravelDuration = mean_duration_factor × DrivingDuration + mean_duration_offset

Where DrivingDuration is the time it would take in a car to travel the distance being calculated for the on-demand service, and MeanTravelDuration is the calculated average time one expects to travel the same trip using the on-demand service.

The MeanTravelDuration may be calculated for the time and the day of the trip to take into account traffic; in other words the consumer is expected to know that DrivingDuration is dynamic. Producers should thus provide values that reflect increases in DrivingDuration due to additional pickups and drop offs beyond that of the passenger. A downtown TNC will likely always have a mean_duration_factor of 1, with or without traffic, since it goes with the flow. But a shared service can have a factor of 2 or more if many additional pickups and drop offs are expected. mean_duration_offset can be utilized to increase travel times of shorter trips relatively more than times for longer trips.

While traveling through undefined space between GeoJSON locations or location groups, it is assumed that:

MeanTravelDuration = DrivingDuration

Conditionally Forbidden:
- Forbidden if stop_times.stop_id does not refer to a location_groups.location_group_id or an id from locations.geojson.
- Optional otherwise.
safe_duration_factor

and

safe_duration_offset
Float Conditionally Forbidden Together, safe_duration_factor and safe_duration_offset allow an estimation of the longest amount of time a rider can expect the on-demand service in a GeoJSON location or location group may require, in minutes, for 95% of trips.

Data consumers are expected to use safe_duration_factor and safe_duration_offset to make the following calculation:

SafeTravelDuration = safe_duration_factor × DrivingDuration + safe_duration_offset

Where DrivingDuration is the time it would take in a car to travel the distance being calculated for the on-demand service, and SafeTravelDuration is the longest amount of time a rider can expect the on-demand service in a GeoJSON location or location group may require.

Conditionally Forbidden:
- Forbidden if stop_times.stop_id does not refer to a location_groups.location_group_id or an id from locations.geojson.
- Optional otherwise.

GTFS-BookingRules

Goals

Many flexible services included in the GTFS-FlexibleTrips extension must be booked in advance and/or by using a phone or the internet. This extension provides the rider with information about how to request service.

Requirements

None. Extends the GTFS.

Files extended or added

File Name State Defines
stop_times.txt Extended Adds links to booking rules.
booking_rules.txt Added Defines the booking rules.

Table Definitions

stop_times.txt (file extended)

Field Name Type Required Description
pickup_booking_rule_id ID referencing booking_rules.booking_rule_id Optional Identifies the boarding booking rule at this stop time.

Recommended when pickup_type=2.
drop_off_booking_rule_id ID referencing booking_rules.booking_rule_id Optional Identifies the alighting booking rule at this stop time.

Recommended when drop_off_type=2.

booking_rules.txt (file added)

Field Name Type Required Description
booking_rule_id ID Required Identifies the rule.
booking_type Enum Required Indicates how far in advance booking can be made. Valid options are:

0 - Real time booking.
1 - Up to same-day booking with advance notice.
2 - Up to prior day(s) booking.
prior_notice_duration_min Integer Conditionally Required Minimum number of minutes before travel to make the request.

Conditionally Required:
- Required for booking_type=1.
- Forbidden otherwise.
prior_notice_duration_max Integer Conditionally Forbidden Maximum number of minutes before travel to make the booking request.

Conditionally Forbidden:
- Forbidden for booking_type=0 and booking_type=2.
- Optional for booking_type=1.
prior_notice_last_day Integer Conditionally Required Last day before travel to make the booking request.

Example: “Ride must be booked 1 day in advance before 5PM” will be encoded as prior_notice_last_day=1.

Conditionally Required:
- Required for booking_type=2.
- Forbidden otherwise.
prior_notice_last_time Time Conditionally Required Last time on the last day before travel to make the booking request.

Example: “Ride must be booked 1 day in advance before 5PM” will be encoded as prior_notice_last_time=17:00:00.

Conditionally Required:
- Required if prior_notice_last_day is defined.
- Forbidden otherwise.
prior_notice_start_day Integer Conditionally Forbidden Earliest day before travel to make the booking request.

Example: “Ride can be booked at the earliest one week in advance at midnight” will be encoded as prior_notice_start_day=7.

Conditionally Forbidden:
- Forbidden for booking_type=0.
- Forbidden for booking_type=1 if prior_notice_duration_max is defined.
- Optional otherwise.
prior_notice_start_time Time Conditionally Required Earliest time on the earliest day before travel to make the booking request.

Example: “Ride can be booked at the earliest one week in advance at midnight” will be encoded as prior_notice_start_time=00:00:00.

Conditionally Required:
- Required if prior_notice_start_day is defined.
- Forbidden otherwise.
prior_notice_service_id ID referencing calendar.service_id Conditionally Forbidden Indicates the service days on which prior_notice_last_day or prior_notice_start_day are counted.

Example: If empty, prior_notice_start_day=2 will be two calendar days in advance. If defined as a service_id containing only business days (weekdays without holidays), prior_notice_start_day=2 will be two business days in advance.

Conditionally Forbidden:
- Optional if booking_type=2.
- Forbidden otherwise.
message Text Optional Message to riders utilizing service at a stop_time when booking on-demand pickup and drop off. Meant to provide minimal information to be transmitted within a user interface about the action a rider must take in order to utilize the service.
pickup_message Text Optional Functions in the same way as message but used when riders have on-demand pickup only.
drop_off_message Text Optional Functions in the same way as message but used when riders have on-demand drop off only.
phone_number Phone number Optional Phone number to call to make the booking request.
info_url URL Optional URL providing information about the booking rule.
booking_url URL Optional URL to an online interface or app where the booking request can be made.