github.com/BlinkTagInc/node-gtfs @4.19.2

➡️ Installation | Quick Start | TypeScript Support | Configuration | Query Methods ⬅️

Import and Export GTFS transit data into SQLite. Query or change routes, stops, times, fares and more.

---

node-GTFS loads transit data in GTFS format into a SQLite database and provides some methods to query for agencies, routes, stops, times, fares, calendars and other GTFS data. It also offers spatial queries to find nearby stops, routes and agencies and can convert stops and shapes to geoJSON format. Additionally, this library can export data from the SQLite database back into GTFS (csv) format.

The library also supports importing GTFS-Realtime data into the same database. In order to keep the realtime database fresh, it uses SQLITE REPLACE which makes it very effective.

You can use it as a command-line tool or as a node.js module.

This library has four parts: the GTFS import script, GTFS export script and GTFS-Realtime update script and the query methods

Installation

To use this library as a command-line utility, install it globally with npm:

npm install gtfs -g

This will add the gtfs-import and gtfs-export scripts to your path.

If you are using this as a node module as part of an application, include it in your project's package.json file.

npm install gtfs

Quick Start

Command-line examples

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

or

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

or

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

or

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

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

Code example

import { importGtfs } from 'gtfs';
import { readFile } from 'fs/promises';
import path from 'node:path';

const config = JSON.parse(
  await readFile(path.join(import.meta.dirname, 'config.json'), 'utf8')
);

try {
  await importGtfs(config);
} catch (error) {
  console.error(error);
}

Example Applications

	GTFS-to-HTML uses `node-gtfs` for downloading, importing and querying GTFS data. It provides a good example of how to use this library and is used by over a dozen transit agencies to generate the timetables on their websites.
	GTFS-to-geojson creates geoJSON files for transit routes for use in mapping. It uses `node-gtfs` for downloading, importing and querying GTFS data. It provides a good example of how to use this library.
	GTFS-to-chart generates a stringline chart in D3 for all trips for a specific route using data from an agency's GTFS. It uses `node-gtfs` for downloading, importing and querying GTFS data.
	GTFS Accessibility Validator checks for accessiblity-realted fields and files and flags any issues. It uses `node-gtfs` for downloading, importing and querying GTFS data.
	GTFS-Text-to-Speech app tests GTFS stop name pronunciation for text-to-speech. It uses `node-gtfs` for loading stop names from GTFS data.
	Transit Departures Widget creates a realtime transit departures widget from GTFS and GTFS-Realtime data.
	GTFS-to-Blocks reads transit data from GTFS and exports all trip segments sorted by block_id and their departure times in CSV format.

Command-Line Usage

The gtfs-import command-line utility will import GTFS into SQLite3.

The gtfs-export command-line utility will create GTFS from data previously imported into SQLite3.

gtfs-import Command-Line options

configPath

Allows specifying a path to a configuration json file. By default, node-gtfs will look for a config.json file in the directory it is being run from. Using a config.json file allows you specify more options than CLI arguments alone - see below.

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

gtfsPath

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

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

or

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

gtfsUrl

Specify a URL to a zipped GTFS file.

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

TypeScript Support

Basic TypeScript typings are included with this library. Please open an issue if you find any inconsistencies between the declared types and underlying code.

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
agencies	array	An array of GTFS files to be imported, and which files to exclude.
csvOptions	object	Options passed to csv-parse for parsing GTFS CSV files. Optional.
db	database instance	An existing database instance to use instead of relying on node-gtfs to connect. Optional.
downloadTimeout	integer	The number of milliseconds to wait before throwing an error when downloading GTFS. Optional.
exportPath	string	A path to a directory to put exported GTFS files. Optional, defaults to gtfs-export/<agency_name>.
gtfsRealtimeExpirationSeconds	integer	Amount of time in seconds to allow GTFS-Realtime data to be stored in database before allowing to be deleted. Optional, defaults to 0.
ignoreDuplicates	boolean	Whether or not to ignore unique constraints on ids when importing GTFS, such as trip_id, calendar_id. Optional, defaults to false.
ignoreErrors	boolean	Whether or not to ignore errors during the import process. If true, failed files will be skipped while the rest are processed. Optional, defaults to false.
includeImportReport	boolean	Whether to return a report object from importGtfs() containing details about what was imported and any errors encountered. Optional, defaults to false.
sqlitePath	string	A path to a SQLite database. Optional, defaults to using an in-memory database.
verbose	boolean	Whether or not to print output to the console. Optional, defaults to true.

agencies

{Array} Specify the GTFS files to be imported in an agencies array. GTFS files can be imported via a url or a local path.

For GTFS files that contain more than one agency, you only need to list each GTFS file once in the agencies array, not once per agency that it contains.

agencies options

option	type	description
url	string	The URL to a zipped GTFS file. Required if path not present.
path	string	A path to a zipped GTFS file or a directory of unzipped .txt files. Required if url is not present.
headers	object	An object of HTTP headers in key:value format to use when fetching GTFS from the url specified. Optional.
prefix	string	A prefix to be added to every ID field maintain uniqueness when importing multiple GTFS from multiple agencies. Optional.
exclude	array	An array of GTFS file names (without .txt) to exclude when importing. Optional.
fillEmptyAgencyId	boolean	When true, fills empty agency_id on routes, fares, and other files for single-agency feeds. Useful for shared databases. Defaults to false. Optional.
agencyId	string	Explicit agency_id to use when fillEmptyAgencyId is true and agency.txt does not define one. Also backfills the agency_id on the agency row itself. If agency.txt already defines an agency_id, that value takes precedence. Optional.
realtimeAlerts	object	An object containing a url field for GTFS-Realtime alerts and a headers field in key:value format to use when fetching GTFS-Realtime data. Optional.
realtimeTripUpdates	object	An object containing a url field for GTFS-Realtime trip updates and a headers field in key:value format to use when fetching GTFS-Realtime data. Optional.
realtimeVehiclePositions	object	An object containing a url field for GTFS-Realtime vehicle positions and a headers field in key:value format to use when fetching GTFS-Realtime data. Optional.

• Specify a url to download GTFS:

{
  "agencies": [
    {
      "url": "https://www.bart.gov/dev/schedules/google_transit.zip"
    }
  ]
}

• Specify a download URL with custom headers using the headers field:

```json { "agencies": [ { "url": "https://www.bart.gov/dev/schedules/google_transit.zip", "headers": { "Content-