GTFS-Ride

About GTFS-Ride

gtfs-ride is a command-line utility for creating GTFS-Ride formatted data. GTFS-Ride is a format for storing transit ridership data. It takes two inputs: a GTFS file and Automated Passenger Counter (APC) data and exports GTFS-Ride data.

gtfs-ride can import APC data in the following ways:

• From a local CSV file
• From a CSV file available at a URL
• From the Swiftly API

Supported APC data formats

Currently, gtfs-ride works for ridership data in the following APC data formats:

• GMV
• Swiftly
• Passio
• LTD
• RVTD
• WETA

The type of APC data format is auto-detected based on the field names in the APC data. If gtfs-ride can not detect the type, it will throw an error.

How it works

gtfs-ride allows you to specify which GTFS and APC data to use as command-line arguments or by using a JSON configuration file. An example of a configuration file is located in this repo as config-sample.json.

1. Run gtfs-ride command-line tool
2. Specify GTFS file and APC data covering the same time period using command-line arguments or via JSON configuration file.
3. gtfs-ride imports specified GTFS into SQLite using node-gtfs
4. gtfs-ride imports specified APC data into SQLite. The type of APC data is auto-detected.
5. Errors and issues while importing APC data are logged to a log.txt file included in the output folder.
6. Valid GTFS-Ride data is exported to the output folder.

Command Line Usage

Setup

• Install node.js https://nodejs.org/en/download/

• Install gtfs-ride globally directly from npm:

  npm install gtfs-ride -g

Updating

npm update gtfs-ride -g

Usage

See command-line options below for more information.

gtfs-ride --gtfsPath /path/to/gtfs --apcPath /path/to/apc/data.csv

or

gtfs-ride --configPath /path/to/your/custom-config.json

This will import APC and GTFS data from the paths specified and output a GTFS-Ride file.

Command-line options

configPath

Allows specifying a path to a configuration json file. By default, gtfs-ride will look for a config.json file in the directory it is being run from.

gtfs-ride --configPath /path/to/your/custom-config.json

gtfsPath

Specify a local path to GTFS, either zipped or unzipped.

gtfs-ride --gtfsPath /path/to/your/gtfs.zip

or

gtfs-ride --gtfsPath /path/to/your/unzipped/gtfs

gtfsUrl

Specify a URL to a zipped GTFS file.

gtfs-ride --gtfsUrl http://www.bart.gov/dev/schedules/google_transit.zip

apcPath

Specify a local path to APC CSV data.

gtfs-ride --apcPath /path/to/your/apcdata.csv

apcUrl

Specify a URL to APC CSV data.

gtfs-ride --apcUrl http://www.myagency.com/apcdata.csv

exportPath

Specify where to export GTFS Ride data to. Defaults to ./output.

gtfs-ride --exportPath /path/where/data/should/go

Configuration

Copy config-sample.json to config.json and then add your projects configuration to config.json.

cp config-sample.json config.json

option	type	description
apcPath	string	The local path to an APC CSV data file.
apcUrl	string	A URL to of an APC CSV data file.
exportPath	string	The path where GTFS Ride data should be exported.
gtfsPath	string	The local path to a static GTFS file.
gtfsUrl	string	A URL of an agency's static GTFS.
startDate	int	Optional. Ignore all APC data before this date.
endDate	int	Optional. Ignore all APC data after this date.
mergeDuplicateBoardAlights	boolean	Whether or not to merge duplicate board-alight records by summing them. Defaults to false.
ignoreMissingGTFSDates	string	Ignore errors caused by no service in GTFS.
sqlitePath	string	A path to an SQLite database. Optional, defaults to using an in-memory database.
swiftlyAgencyKey	string	The Swiftly agency key to request data for.
swiftlyAPIKey	string	The API key for the Swiftly API.
swiftlyEndDate	string	The end date for requesting data from the Swiftly API.
swiftlyStartDate	string	The start date for requesting data from the Swiftly API.

apcPath

{String} The local path to an APC CSV file. Either apcUrl, apcPath or swiftlyAgencyKey is required.

    "apcPath": "/path/to/the/apc.csv"

apcUrl

{String} A URL to of an APC CSV. Either apcUrl, apcPath or swiftlyAgencyKey is required.

    "apcUrl": "https://bart.gov/data/apc.csv"

exportPath

{String} The path where GTFS Ride data should be exported. Optional, defaults to the directory output in the directory where the script was run.

    "exportPath": "/path/where/gtfs/ride/data/should/go"

gtfsPath

{String} The local path to a static GTFS file. Can be zipped or unzipped. Either gtfsUrl or gtfsPath is required.

• Specify a path to a zipped GTFS file:

    "gtfsPath": "/path/to/the/gtfs.zip"

• Specify a path to an unzipped GTFS file:

    "gtfsPath": "/path/to/the/unzipped/gtfs"

gtfsUrl

{String} A URL of an agency's static GTFS. Either gtfsUrl or gtfsPath is required.

    "gtfsUrl": "https://bart.gov/data/google_transit.zip"

startDate

{Integer} If present, exclude importing APC data from before this date, formatted as YYYYMMDD format. Optional.

    "startDate": 20210101

endDate

{Integer} If present, exclude importing APC data from after this date, formatted as YYYYMMDD format. Optional.

    "endDate": 20210301

mergeDuplicateBoardAlights

{Boolean} Whether or not to merge duplicate board-alight records by summing them. Defaults to false.

    "mergeDuplicateBoardAlights": "false

ignoreMissingGTFSDates

{Boolean} Whether or not to ignore errors caused by no service defined for a specific date in GTFS. Defaults to false.

    "ignoreMissingGTFSDates": "false

sqlitePath

{String} A path to an SQLite database. Optional, defaults to using an in-memory database.

    "sqlitePath": "/tmp/gtfs"

swiftlyAgencyKey

{String} The Swiftly agency key to request data for, for example rtamaryland. Only required if using the Swiftly API for fetching APC data.

    "swiftlyAgencyKey": "rtamaryland"

swiftlyAPIKey

{String} The API key for the Swiftly API. Only required if using the Swiftly API for fetching APC data.

    "swiftlyAPIKey": "YOUR-SWIFTLY-API-KEY"

swiftlyEndDate

{String} The end date for requesting data from the Swiftly API in MM-DD-YYYY format. Only used if using the Swiftly API for fetching APC data. If omitted, the current date is used.

    "swiftlyEndDate": "05-20-2022"

swiftlyStartDate

{String} The start date for requesting data from the Swiftly API in MM-DD-YYYY format. Only used if using the Swiftly API for fetching APC data. If omitted, the date from 1 week ago is used to fetch data from the previous week.

    "swiftlyStartDate": "05-10-2022"

Visualizing and Exporting GTFS Ride data

Use the Ridership App to visualize and export ridership data.

Notes

gtfs-ride uses the node-gtfs library to handle importing and querying GTFS data.

Contributing

Pull requests are welcome, as is feedback and reporting issues.