Generate Shapes Features From GTFS (Conversion)

Summary

Generates an estimate of the paths traveled by the vehicles in a public transit system. The output from this tool can be used to generate a new shapes.txt file for a GTFS public transit dataset.

The optional GTFS shapes.txt file contains a representation of the geographic paths taken by transit vehicles in a transit system. A good shapes.txt file is important for GTFS-based routing apps to display transit routes correctly on the map. Although many transit agencies generate their shapes.txt files using GPS trackers on their vehicles, other transit agencies lacking this hardware may have trouble creating this file.

This tool, together with the Features To GTFS Shapes tool, allows you to create a shapes.txt file based on the stop, route, and schedule information from an existing GTFS dataset. This tool generates estimates for the geographic paths used by vehicles in the transit system and writes the output to a feature class. You can review and edit these line features before running the Features To GTFS Shapestool, which exports the shapes to a new shapes.txt file.

This tool is intended to be used in a workflow with three main steps:

  1. Run this tool to produce an estimate of the geographic paths used by vehicles in the transit system.
  2. Use the map to inspect each estimated shape, and use the standard editing tools to make any corrections.
  3. Run the Features To GTFS Shapes tool to create a shapes.txt file for your GTFS dataset.

Note:

The GTFS Shapes To Features tool and the Generate Shapes Features From GTFS tool are used for different purposes. Use GTFS Shapes To Features if your GTFS dataset includes an existing shapes.txt file and you want to convert these shapes to a feature class to display in the map. Use Generate Shapes Features From GTFS if your GTFS dataset does not include an existing shapes.txt file and you want to estimate the shapes based on the other information contained in the GTFS dataset and create a shapes.txt file.

Usage

  • This tool estimates the route shapes of the public transit network using one of the following options for each mode of transit in the data:

    • Straight lines—Transit route shapes are straight lines connecting adjacent transit stops. This is appropriate for subways, ferries, or other transit modes that don't travel on streets.
    • On-street routes generated using a road network—Transit line shapes are generated by solving a route between adjacent stops to model vehicles traveling along roads in a network.
    You can choose which option to use for each mode of public transit included in the data. For example, you can create shapes for bus lines using the network and straight lines for subways. This is configured in the Transit Modes for Network parameter.

    There are two choices for generating route shapes based on a road network:

    • Use a local network dataset—This option requires the ArcGIS Network Analyst extension and a network dataset.
    • Use a portal service—This option requires an ArcGIS Online account with routing privileges and sufficient credits or a portal with ArcGIS Enterprise routing service configured. You must be signed in to the portal before running the tool.

  • When calculating route shapes along a road network, Network Analyst may not successfully calculate a route connecting the stops for some shapes. In these cases, since network shapes could not be created, the tool creates straight-line shapes instead and returns a warning message indicating which shape_id values were affected.

  • When inspecting and correcting the output of the tool, you can use a definition query to display only a single shape and its associated stops on the map. Use the shape_id field in both outputs to select the shape to show. The sequence field in the output stops indicates the order in which the transit stops are visited.

  • Note:

    The output shape features created by this tool are an estimate of the actual paths traveled by the transit vehicles in your system. Manually inspect each output shape feature individually to ensure that the path is correct.

    Before running the Features To GTFS Shapes tool, inspect the shape feature output from this tool and make any corrections to the shape geometry. This ensures that the final output shapes.txt file will be accurate and helps avoid errors in the shape_dist_traveled field calculation for the stop_times.txt file.

    In addition to making basic corrections to the shapes to accurately represent the paths traveled, edit the shapes to avoid directly overlapping line segments. If a bus travels in both directions along the same street and overlaps itself on the centerline, you can slightly offset each direction of the shape line to either side of the centerline.

    Use the Reshape editing tool to correct shape geometry. To completely replace the shape geometry by manually digitizing the shape in the map, use the Replace Geometry editing tool.

    If the stops are not in the correct location, use the GTFS Stops To Features and Features To GTFS Stops tools to correct them, and run this tool again.

  • When examining and editing the tool outputs, you can edit the feature geometry and attributes but do not delete any rows. Deleted rows may cause errors when you run the Features To GTFS Shapes tool.

Parameters

LabelExplanationData Type
Input GTFS Folder

A folder containing a valid GTFS dataset for which you want to create a new shapes.txt file. The folder must contain the GTFS stops.txt, trips.txt, routes.txt, and stop_times.txt files.

Folder
Output Transit Shape Lines

A line feature class representing the estimated route shapes calculated by this tool. Each line in the output represents a unique shape required for this GTFS dataset. You can edit the line geometry and use this feature class as input to the Features To GTFS Shapes tool.

Feature Class
Output Shape Stops

A point feature class of GTFS transit stops with an ID associating them with each shape line to be created by the tool. In cases where the same GTFS stop is visited by multiple shapes, this feature class will contain multiple copies of that stop, one for each shape with which it is associated. This feature class is useful with definition queries when editing one shape line at a time. Use this feature class as input to the Features To GTFS Shapes tool.

Note:

This output feature class is not equivalent to the output of the GTFS Stops To Features tool. That tool produces a feature class of the GTFS stops exactly as they are in the original dataset; this tool may produce multiple copies of each stop to associate them with different shapes. Use this output feature class in conjunction with the other outputs of the Generate Shapes Features From GTFS tool to create a shapes.txt file.

Feature Class
Output GTFS Trips

The output GTFS trips.txt file. This file will be equivalent to the trips.txt file in the input GTFS folder but will include the shape_id field added and populated with values corresponding to the shape_id field in the Output Transit Shape Lines feature class.

File
Transit Modes for Network
(Optional)

Specifies the modes of transit for which line shapes will be generated along the road network rather than with straight lines. Shapes for all modes not selected will be generated using straight lines.

You should typically select modes that run on streets, such as buses, since those modes are most accurately represented by the road network. Do not select modes that are not modeled by your road network. For example, unless your network explicitly models ferry lanes, don't use the network to represent the paths traveled by ferries.

The modes are specified using the codes in the table below. These correspond to the valid GTFS routes.txt file's route_type field values from the GTFS documentation.

Modes 3, 5, and 11 are used by default.

  • Tram, streetcar, light rail (GTFS 0) Tram, streetcar, light rail. This mode corresponds to GTFS route_type 0.
  • Subway, metro (GTFS 1) Subway or metro. This mode corresponds to GTFS route_type 1.
  • Rail (GTFS 2) Rail. This mode corresponds to GTFS route_type 2.
  • Bus (GTFS 3) Bus. This mode corresponds to GTFS route_type 3.
  • Ferry (GTFS 4) Ferry. This mode corresponds to GTFS route_type 4.
  • Cable tram (GTFS 5) Cable tram. This mode corresponds to GTFS route_type 5.
  • Aerial lift, suspended cable car, gondola lift, aerial tramway (GTFS 6) Aerial lift, suspended cable car, gondola lift, aerial tramway. This mode corresponds to GTFS route_type 6.
  • Funicular (GTFS 7) Funicular. This mode corresponds to GTFS route_type 7.
  • Trolleybus (GTFS 11) Trolleybus. This mode corresponds to GTFS route_type 11.
  • Monorail (GTFS 12) Monorail. This mode corresponds to GTFS route_type 12.
  • Other transit modeThis option corresponds to any mode of public transit not encompassed by the other options.
String
Network Data Source
(Optional)

The network dataset or service that will be used for calculating route shapes along a road network. You can use a catalog path to a network dataset, a network dataset layer object, the string name of the network dataset layer, or a portal URL for a network analysis service. The network must have at least one travel mode.

To use a portal URL, you must be signed in to the portal with an account that has routing privileges.

Running the tool will consume credits if you use ArcGIS Online as the network data source.

Learn more about estimating credit usage for this tool

This parameter is required when any network modes are selected.

Note:

The network dataset you choose should be appropriate for modeling transit vehicles, such as buses, driving on streets. Don't use a network dataset configured to use public transit data with the Public Transit evaluator because this type of network models passengers riding on public transit, not public transit vehicles driving on streets.

Network Data Source
Travel Mode
(Optional)

The travel mode on the network data source that will be used when calculating route shapes along a road network. You can specify the travel mode as a string name of the travel mode or as an arcpy.nax.TravelMode object.

Use the travel mode most appropriate for modeling vehicles in your transit system driving along the road network.

This parameter is required when any network modes are selected.

Note:

Do not use a travel mode with an impedance attribute that uses the Public Transit evaluator because that travel mode models passengers riding on public transit, not transit vehicles driving on streets.

Network Travel Mode
Side of Road on which Vehicles Drive
(Optional)

Specifies the side of the road on which vehicles drive in your transit system. This is used to ensure that stops are visited on the correct side of the road.

  • LeftVehicles drive on the left side of the road.
  • RightVehicles drive on the right side of the road. This is the default.
String
Bearing Tolerance
(Optional)

The maximum allowed angle between a transit vehicle's estimated direction of travel at a stop and the angle of the network edge where the stop could locate. If the angles differ by more than this value, it is assumed that this is not the correct network edge on which to locate the stop, and Network Analyst will continue searching other nearby network edges for a more appropriate edge.

When calculating route shapes along a road network, bearing and bearing tolerance are used to more accurately locate transit stops along the road network. The transit vehicle's bearing is estimated at each stop based on the angles between the current stop and the previous and next stops along the transit route.

Specify the value in units of degrees between 0 and 180. The default is 30.

Double
Maximum Bearing Angle Difference
(Optional)

The maximum allowable difference in bearing angle between the previous stop and the current stop and the current stop to the next stop.

The transit vehicle's bearing is estimated at each stop based on the angles between the current stop and the previous and next stops along the transit route. When the transit route follows a relatively straight road, this angle is a good representation of the bearing. However, if the route goes around a corner, makes a U-turn, follows a twisty road, or diverts into a parking lot or side road, the average angle is not a good estimate of bearing and using this estimate can cause the stop to locate on the network far away from where it should and worsen the quality of the tool output.

The tool will ignore the bearing estimate if the difference in angle from the previous stop to the current stop and the current stop to the next stop is greater than the value specified in this parameter. In this situation, the stop will revert to the normal network locating behavior and will snap to the closest nonrestricted network edge.

Specify the value in units of degrees between 0 and 180. The default is 65.

Double

arcpy.conversion.GenerateShapesFeaturesFromGTFS(in_gtfs_folder, out_shape_lines, out_shape_stops, out_gtfs_trips, {network_modes}, {network_data_source}, {travel_mode}, {drive_side}, {bearing_tolerance}, {max_bearing_angle})
NameExplanationData Type
in_gtfs_folder

A folder containing a valid GTFS dataset for which you want to create a new shapes.txt file. The folder must contain the GTFS stops.txt, trips.txt, routes.txt, and stop_times.txt files.

Folder
out_shape_lines

A line feature class representing the estimated route shapes calculated by this tool. Each line in the output represents a unique shape required for this GTFS dataset. You can edit the line geometry and use this feature class as input to the Features To GTFS Shapes tool.

Feature Class
out_shape_stops

A point feature class of GTFS transit stops with an ID associating them with each shape line to be created by the tool. In cases where the same GTFS stop is visited by multiple shapes, this feature class will contain multiple copies of that stop, one for each shape with which it is associated. This feature class is useful with definition queries when editing one shape line at a time. Use this feature class as input to the Features To GTFS Shapes tool.

Note:

This output feature class is not equivalent to the output of the GTFS Stops To Features tool. That tool produces a feature class of the GTFS stops exactly as they are in the original dataset; this tool may produce multiple copies of each stop to associate them with different shapes. Use this output feature class in conjunction with the other outputs of the Generate Shapes Features From GTFS tool to create a shapes.txt file.

Feature Class
out_gtfs_trips

The output GTFS trips.txt file. This file will be equivalent to the trips.txt file in the input GTFS folder but will include the shape_id field added and populated with values corresponding to the shape_id field in the Output Transit Shape Lines feature class.

File
network_modes
[network_modes,...]
(Optional)

Specifies the modes of transit for which line shapes will be generated along the road network rather than with straight lines. Shapes for all modes not selected will be generated using straight lines.

You should typically select modes that run on streets, such as buses, since those modes are most accurately represented by the road network. Do not select modes that are not modeled by your road network. For example, unless your network explicitly models ferry lanes, don't use the network to represent the paths traveled by ferries.

The modes are specified using the codes in the table below. These correspond to the valid GTFS routes.txt file's route_type field values from the GTFS documentation.

Modes 3, 5, and 11 are used by default.

  • 0 Tram, streetcar, light rail. This mode corresponds to GTFS route_type 0.
  • 1 Subway or metro. This mode corresponds to GTFS route_type 1.
  • 2 Rail. This mode corresponds to GTFS route_type 2.
  • 3 Bus. This mode corresponds to GTFS route_type 3.
  • 4 Ferry. This mode corresponds to GTFS route_type 4.
  • 5 Cable tram. This mode corresponds to GTFS route_type 5.
  • 6 Aerial lift, suspended cable car, gondola lift, aerial tramway. This mode corresponds to GTFS route_type 6.
  • 7 Funicular. This mode corresponds to GTFS route_type 7.
  • 11 Trolleybus. This mode corresponds to GTFS route_type 11.
  • 12 Monorail. This mode corresponds to GTFS route_type 12.
  • OTHERThis option corresponds to any mode of public transit not encompassed by the other options.
String
network_data_source
(Optional)

The network dataset or service that will be used for calculating route shapes along a road network. You can use a catalog path to a network dataset, a network dataset layer object, the string name of the network dataset layer, or a portal URL for a network analysis service. The network must have at least one travel mode.

To use a portal URL, you must be signed in to the portal with an account that has routing privileges.

Running the tool will consume credits if you use ArcGIS Online as the network data source.

Learn more about estimating credit usage for this tool

This parameter is required when any network modes are selected.

Note:

The network dataset you choose should be appropriate for modeling transit vehicles, such as buses, driving on streets. Don't use a network dataset configured to use public transit data with the Public Transit evaluator because this type of network models passengers riding on public transit, not public transit vehicles driving on streets.

Network Data Source
travel_mode
(Optional)

The travel mode on the network data source that will be used when calculating route shapes along a road network. You can specify the travel mode as a string name of the travel mode or as an arcpy.nax.TravelMode object.

Use the travel mode most appropriate for modeling vehicles in your transit system driving along the road network.

This parameter is required when any network modes are selected.

Note:

Do not use a travel mode with an impedance attribute that uses the Public Transit evaluator because that travel mode models passengers riding on public transit, not transit vehicles driving on streets.

Network Travel Mode
drive_side
(Optional)

Specifies the side of the road on which vehicles drive in your transit system. This is used to ensure that stops are visited on the correct side of the road.

  • LEFTVehicles drive on the left side of the road.
  • RIGHTVehicles drive on the right side of the road. This is the default.
String
bearing_tolerance
(Optional)

The maximum allowed angle between a transit vehicle's estimated direction of travel at a stop and the angle of the network edge where the stop could locate. If the angles differ by more than this value, it is assumed that this is not the correct network edge on which to locate the stop, and Network Analyst will continue searching other nearby network edges for a more appropriate edge.

When calculating route shapes along a road network, bearing and bearing tolerance are used to more accurately locate transit stops along the road network. The transit vehicle's bearing is estimated at each stop based on the angles between the current stop and the previous and next stops along the transit route.

Specify the value in units of degrees between 0 and 180. The default is 30.

Double
max_bearing_angle
(Optional)

The maximum allowable difference in bearing angle between the previous stop and the current stop and the current stop to the next stop.

The transit vehicle's bearing is estimated at each stop based on the angles between the current stop and the previous and next stops along the transit route. When the transit route follows a relatively straight road, this angle is a good representation of the bearing. However, if the route goes around a corner, makes a U-turn, follows a twisty road, or diverts into a parking lot or side road, the average angle is not a good estimate of bearing and using this estimate can cause the stop to locate on the network far away from where it should and worsen the quality of the tool output.

The tool will ignore the bearing estimate if the difference in angle from the previous stop to the current stop and the current stop to the next stop is greater than the value specified in this parameter. In this situation, the stop will revert to the normal network locating behavior and will snap to the closest nonrestricted network edge.

Specify the value in units of degrees between 0 and 180. The default is 65.

Double

Code sample

GenerateShapesFeaturesFromGTFS example 1 (Python window)

The following script demonstrates how to use the GenerateShapesFeaturesFromGTFS function in the Python window using a local network dataset:

Legacy:

This tool was moved to the Public Transit Tools toolbox at ArcGIS Pro 2.9. The syntax in the code sample uses the transit toolbox alias associated with the tool's new location. However, the conversion toolbox alias continues to work. You do not need to modify existing scripts, but you should use the transit alias for new scripts.

arcpy.transit.GenerateShapesFeaturesFromGTFS(
    r"C:\Data\GTFS",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Shapes",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Stops",
    r"C:\Data\GTFSShapes\trips_new.txt",
    ["3", "5", "11"],
    r"C:\Data\NetworkDatasets\Network.gdb\Routing\Routing_ND",
    "Bus Driving Time", "Right", 30, 65
)
GenerateShapesFeaturesFromGTFS example 2 (Python window)

The following script demonstrates how to use the GenerateShapesFeaturesFromGTFS function in the Python window using the ArcGIS Online services to generate shapes for some transit modes:

Legacy:

This tool was moved to the Public Transit Tools toolbox at ArcGIS Pro 2.9. The syntax in the code sample uses the transit toolbox alias associated with the tool's new location. However, the conversion toolbox alias continues to work. You do not need to modify existing scripts, but you should use the transit alias for new scripts.

arcpy.transit.GenerateShapesFeaturesFromGTFS(
    r"C:\Data\GTFS",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Shapes",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Stops",
    r"C:\Data\GTFSShapes\trips_new.txt",
    ["0", "3", "5", "11", "OTHER"],
    "https://www.arcgis.com/",
    "Driving Time", "Right", 30, 65
)
GenerateShapesFeaturesFromGTFS example 3 (Python window)

The following script demonstrates how to generate straight-line shapes for all transit modes using an empty list for the network_modes parameter:

Legacy:

This tool was moved to the Public Transit Tools toolbox at ArcGIS Pro 2.9. The syntax in the code sample uses the transit toolbox alias associated with the tool's new location. However, the conversion toolbox alias continues to work. You do not need to modify existing scripts, but you should use the transit alias for new scripts.

arcpy.transit.GenerateShapesFeaturesFromGTFS(
    r"C:\Data\GTFS",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Shapes",
    r"C:\Data\GTFSShapes\GTFSShapes.gdb\Stops",
    r"C:\Data\GTFSShapes\trips_new.txt",
    []
)

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes