GTFS View

GTFS View

The Admin Panel product contains the GTFS view, which allows you to manage the intake of GTFS into Swiftly's system and more quickly diagnose issues with GTFS files that may cause problems in Swiftly's software. You must have permission within the Swiftly dashboard to make any changes to your agency’s GTFS files, intake methods, or settings. To get permission, reach out to [e-mail] or your Customer Success Manager.

 

GTFS Settings

The “Edit GTFS Settings” is where you can update GTFS information in Swiftly.

“Method” is where you choose whether you would like to update the GTFS automatically via a fetch location, or manually via a file upload.

Automatic GTFS Setting

 If you are uploading your data automatically, you will need to add a URL next to “GTFS URL.”. The URL must be stable, and can not change from one file upload to the next. 

This “automatic” GTFS setting means that any new file that is posted to this URL will be automatically detected by Swiftly, and uploaded into the Swiftly platform. 

The “Advanced Features” allow you to select the frequency with which our system checks for GTFS file changes, and add or edit HTTP Headers to our requests for your GTFS file. The most common reason to include HTTP Headers is to include an API key that is needed to download the GTFS file.

Most agencies will not need to use the advanced features. If you are uncertain about a setting in this section, please contact [e-mail] or your Customer Success Manager.

The Advanced settings allow you to select the frequency with which Swiftly checks for GTFS file changes from the URL, and add or edit HTTP Headers to our requests for your GTFS file. The most common reason to include HTTP Headers is to include an API key that is needed to download the GTFS file.

Most agencies will not need to use the Advanced settings. If you are uncertain about a setting in this section, please contact [e-mail] or your Customer Success Manager.

Manual GTFS Setting

When using a manual upload, you will need to upload a zipped GTFS file directly from your computer. There is a box to enter a description to give context as to why you are uploading a file manually or what changes are contained in that file - a description is required for all manual file uploads.

It is important to note that when you switch to manual upload, Swiftly will no longer pick up automatic GTFS updates from the entered URL until it is changed back. Once automatic updates are turned back on, our system will update the GTFS if the files are different from those uploaded manually. If they are the same, our system will not upload a new GTFS. 

To learn more about Swiftly’s GTFS Intake process, you can read about it here. 

 

GTFS Intake History

The GTFS Intake History section This where you can see a history of all of the GTFS files uploaded to Swiftly. This section provides a space to investigate problems that may crop up from new GTFS file uploads.

• File Status: Shows "Active" for the currently-active GTFS file, and "Future" if a GTFS file has been processed and is waiting to become active.
• File Received: Shows the date and time that Swiftly received the GTFS file.
• Method: Shows the method that Swiftly received the GTFS file.
• Description: Shows the added description (if the file was added automatically, an automatic description is generated that lists the files changed from the previous version).
• Processing Status: Shows whether GTFS was successfully processed, processed with issues, or failed processing.

Click on the arrow to the left of file status to see more details about the GTFS file upload to Swiftly.

• File: Download
  • Download a zipped file of this GTFS version.
• Description: Shows the added description (if the file was added automatically, an automatic description is generated that lists the exact GTFS files that were changed from the previous version).
• Service Dates: Shows the active dates for that GTFS file.

 

GTFS Validation Results

When Swiftly receives new GTFS data, it will automatically validate it for a variety of common quality and accuracy issues, so that users can fix problems before riders or agency staff are impacted.

Starting after October 9th, 2025, each GTFS processing event will include validation information. GTFS validation results can be found under the dropdown for a given processing event.

What do validation results look like?

If a given GTFS file was successfully processed, that means there were no validation issues detected by Swiftly. If a given GTFS file was processed with the status "Processed with Issues", then the file can be used by the platform, but there may be unexpected impacts due to problems in the GTFS. 

To evaluate issues more closely, users can view specific examples of the problem along with other supplementary data to support troubleshooting.

Failed Processing Events

If issues in GTFS would have severe impacts on riders or agency staff, Swiftly will prevent the file from being ingested. These issues may include details about the problem when available. We recommend contacting Swiftly Technical Support when processing failures occur.

Common GTFS Issues

In all of the following cases, we recommend taking action to fix GTFS issues, so all consumers (e.g. Swiftly, rider apps, etc.) have accurate information about your scheduled service.

• "Stop to Shape Distance Too High": One or more stops on a given shape are too far from the shape path. These issues typically occur when GTFS contains incomplete shapes, when shapes are not accurate to routes, or when stops are not correctly located. 
  
  
• "Stops Out of Order On Shape": A trip shape cannot be drawn with the provided stop sequence. This usually means the sequence of stops is incorrect or the shape itself has some underlying issues that lead to backtracking when attempting to create a trip/route path.
  
  
• "Significant drop in percentage of trips with block ids": There are fewer trips with block IDs than expected. Swiftly calculates this by comparing a given file against other recent GTFS processing events.
  
  
• "Not all supplied block translations were found in trips.txt": If your agency uses block translations to modify the block IDs in your GTFS file, this error indicates that the translation file may need to be corrected and that some blocks may not be getting translated. This can lead to unfamiliar block IDs appearing in the Swiftly platform and vehicle assignment issues.
  
  
• "There are multiple route_ids that have the same short_name in routes.txt": Swiftly uses short_names to uniquely identify routes. In cases where multiple routes share the same short name, their data will be merged in Swiftly. If you would prefer each route be treated separately by the platform, please add unique short_names.
  
  
• "Trips in trips.txt have no shape_id. We will create a simple trip shape connecting consecutive stops": One or more trips have been provided without a shape. Because Swiftly has no way of inferring the shape of the route, straight lines will connect stops. This can have major impacts on real-time and historical data quality if not corrected. This issue also means other downstream consumers (like rider apps) have no agency-created shape information to display to riders.
  
  
• "Encountered the same stop_id twice in a row": Within the "stop_times.txt" file, we encountered the same stop_id multiple times in a row. If the stop_times appear to be identical, we will simply ignore the second one. If there are differences (such as differing arrival times), we will merge them into a single stop_time.
  
  
• "Small Amount of Service": The first service date of the file has less service than expected. This is calculated by comparing the number of trips on the first service date to the average number of trips on the same day of the week in past GTFS files.