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.