\n\nImport [GTFS](https://gtfs.org/schedule/) transit data into SQLite, PostgreSQL,\nor MySQL. Query, update with GTFS-Realtime, and export SQLite data from Node.js\nor the command line.\n\n## Choose what you want to do\n\n- **Import and explore a feed locally:** follow the [SQLite quick start](#quick-start).\n- **Use node-GTFS in an application:** see [Using JavaScript](#using-javascript).\n- **Load an existing PostgreSQL or MySQL database:** see [PostgreSQL and MySQL](#postgresql-and-mysql).\n- **Refresh GTFS-Realtime data:** see [GTFS-Realtime](#gtfs-realtime).\n- **Export a database back to GTFS files:** see [Export GTFS](#export-gtfs).\n\n## Database support\n\n| Feature | SQLite | PostgreSQL | MySQL |\n| ------------------------------ | :----: | :-----------------: | :-----------------: |\n| Import static GTFS | Yes | Yes, through Kysely | Yes, through Kysely |\n| Synchronous query helpers | Yes | No | No |\n| Import GTFS-Realtime | Yes | No | No |\n| Export GTFS files | Yes | No | No |\n| Manage GTFS tables and indexes | Yes | Optional | Optional |\n\nPostgreSQL and MySQL imports use a caller-owned Kysely connection. See\n[Database portability](docs/database-portability.md) for storage details.\n\n> **Note:** PostgreSQL and MySQL support is new. The interface, configuration\n> options, and functions related to it may change in a future release.\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) 22 or newer\n\n## Quick start\n\nThis example downloads BART's public GTFS feed and saves it as a persistent\nSQLite database.\n\n### 1. Create a project\n\n```bash\nmkdir gtfs-demo\ncd gtfs-demo\nnpm init -y\nnpm install gtfs\n```\n\n### 2. Import GTFS\n\n```bash\nnpx gtfs-import \\\n --gtfsUrl https://www.bart.gov/dev/schedules/google_transit.zip \\\n --sqlitePath ./gtfs.sqlite\n```\n\nThe import creates `gtfs.sqlite` in the current directory. If you don't\nspecify a SQLite path when using the command line, it will default to an\nin-memory database which will be discarded when the command exits.\n\n> **Warning:** A static import drops and recreates the GTFS tables in its\n> destination database. Use a new database or back up data you need to keep.\n\nYou can import your own ZIP file or directory instead:\n\n```bash\nnpx gtfs-import --gtfsPath ./data/gtfs.zip --sqlitePath ./gtfs.sqlite\n```\n\n### 3. Query the database\n\nCreate a file named `query.mjs`:\n\n```js\nimport { closeDb, getAgencies, getRoutes, openDb } from 'gtfs';\n\nconst db = openDb({ sqlitePath: './gtfs.sqlite' });\n\ntry {\n const agencies = getAgencies({}, ['agency_id', 'agency_name']);\n const routes = getRoutes(\n {},\n ['route_id', 'route_short_name', 'route_long_name'],\n [['route_short_name', 'ASC']],\n );\n\n console.table(agencies);\n console.table(routes);\n} finally {\n closeDb(db);\n}\n```\n\nRun it:\n\n```bash\nnode query.mjs\n```\n\nThe `.mjs` extension lets Node.js run the example as an ES module without any\nadditional project configuration.\n\n## Using JavaScript\n\nInstall node-GTFS in your application:\n\n```bash\nnpm install gtfs\n```\n\nImport a feed and query it in the same process using an in-memory database:\n\n```js\nimport { closeDb, getStops, importGtfs, openDb } from 'gtfs';\n\nconst config = {\n agencies: [{ path: './data/gtfs.zip' }],\n};\n\nawait importGtfs(config);\nconst db = openDb(config);\n\ntry {\n const stops = getStops(\n { stop_id: ['123', '234', '345'] },\n ['stop_id', 'stop_name'],\n [['stop_name', 'ASC']],\n );\n console.table(stops);\n} finally {\n closeDb(db);\n}\n```\n\nMethods that read SQLite data are synchronous. Import, export, and\nGTFS-Realtime updates are asynchronous.\n\n## Common tasks\n\n### Use a configuration file\n\nA configuration file is useful for multiple feeds, custom HTTP headers,\nGTFS-Realtime endpoints, and other import options. Create `config.json` in the\ndirectory where you run the command:\n\n```json\n{\n \"agencies\": [\n {\n \"url\": \"https://www.bart.gov/dev/schedules/google_transit.zip\"\n }\n ],\n \"sqlitePath\": \"./gtfs.sqlite\"\n}\n```\n\nThen run:\n\n```bash\nnpx gtfs-import\n```\n\nUse a configuration file in another location with `--configPath`:\n\n```bash\nnpx gtfs-import --configPath ./config/production.json\n```\n\nSee the [configuration reference](docs/configuration.md) for every option and\nexamples for multiple feeds, prefixes, exclusions, and custom logging. A\n[comprehensive sample](config-sample-full.json) is also available.\n\n### Command-line tools\n\nInstalling `gtfs` provides three commands:\n\n| Command | Purpose |\n| --------------------- | --------------------------------------- |\n| `gtfs-import` | Import static GTFS into SQLite |\n| `gtfsrealtime-update` | Refresh GTFS-Realtime data in SQLite |\n| `gtfs-export` | Export an SQLite database to GTFS files |\n\nRun any command with `--help` to see its options:\n\n```bash\nnpx gtfs-import --help\nnpx gtfsrealtime-update --help\nnpx gtfs-export --help\n```\n\nYou can install the commands globally with `npm install --global gtfs`, but a\nlocal installation with `npx` makes it easier to keep each project on a known\nversion.\n\n### Query GTFS\n\nMost getters have the same four optional arguments:\n\n```js\ngetRoutes(query, fields, orderBy, options);\n```\n\n- `query` filters rows by field. An array means SQL `IN`; an empty array\n returns no rows.\n- `fields` selects returned columns. An empty array returns every column.\n- `orderBy` contains `[field, 'ASC' | 'DESC']` pairs.\n- `options` can contain an explicit SQLite `db` connection.\n\nFor example, find trips for a route on a service date:\n\n```js\nimport { getTrips } from 'gtfs';\n\nconst trips = getTrips(\n { route_id: '12', date: 20260817 },\n ['trip_id', 'trip_headsign'],\n [['trip_headsign', 'ASC']],\n { db },\n);\n```\n\nSpecialized helpers support route, trip, service, time, geographic, and\nGeoJSON queries. See the [query API guide](docs/query-api.md).\n\n### Case-insensitive comparisons\n\nFields marked `caseInsensitiveComparison` in the schema use SQLite's\n`COLLATE NOCASE`. Equality, `IN`, and default ordering ignore ASCII letter\ncase for those fields:\n\n```js\nconst agencies = getAgencies({ agency_name: 'metro transit' });\n```\n\nGTFS identifiers remain case-sensitive. SQLite `NOCASE` is not Unicode-aware.\nPostgreSQL and MySQL use the collation configured for their database or column.\n\n### GTFS-Realtime\n\nAdd one or more realtime endpoints to a feed in `config.json`:\n\n```json\n{\n \"agencies\": [\n {\n \"realtimeAlerts\": {\n \"url\": \"https://example.com/alerts.pb\"\n },\n \"realtimeTripUpdates\": {\n \"url\": \"https://example.com/trip-updates.pb\"\n },\n \"realtimeVehiclePositions\": {\n \"url\": \"https://example.com/vehicle-positions.pb\"\n }\n }\n ],\n \"sqlitePath\": \"./gtfs.sqlite\"\n}\n```\n\nRefresh the realtime tables:\n\n```bash\nnpx gtfsrealtime-update\n```\n\nThe command performs one update and exits. Use your operating system's task\nscheduler or a process manager to run it repeatedly. See the\n[GTFS-Realtime guide](docs/realtime.md) for headers, retention, and JavaScript\nusage.\n\n### Export GTFS\n\nExport an existing SQLite database:\n\n```bash\nnpx gtfs-export --sqlitePath ./gtfs.sqlite\n```\n\nOr use JavaScript:\n\n```js\nimport { exportGtfs } from 'gtfs';\n\nawait exportGtfs({\n sqlitePath: './gtfs.sqlite',\n exportPath: './gtfs-export',\n});\n```\n\nThe export directory is replaced when an export runs. Make sure it does not\ncontain files you need to keep.\n\n### PostgreSQL and MySQL\n\n`importGtfsToKysely()` imports static GTFS using a caller-owned Kysely\nconnection. Install the driver for your database in addition to `gtfs`.\n\n> **Note:** PostgreSQL and MySQL support is new. The interface, configuration\n> options, and functions related to it may change in a future release.\n\nPostgreSQL example:\n\n```bash\nnpm install pg\n```\n\n```js\nimport { importGtfsToKysely } from 'gtfs';\nimport { Kysely, PostgresDialect } from 'kysely';\nimport { Pool } from 'pg';\n\nconst db = new Kysely({\n dialect: new PostgresDialect({\n pool: new Pool({ connectionString: process.env.DATABASE_URL }),\n }),\n});\n\ntry {\n await importGtfsToKysely(\n { agencies: [{ path: './data/gtfs.zip' }] },\n { db, dialect: 'postgres' },\n );\n} finally {\n await db.destroy();\n}\n```\n\n> **Warning:** `manageSchema` defaults to `true`. The importer drops and\n> recreates the GTFS tables it manages. Set `manageSchema: false` when your\n> application owns the schema.\n\nUse Kysely's `MysqlDialect` with `mysql2` and `dialect: 'mysql'` for MySQL.\nStatic Kysely imports do not store configured GTFS-Realtime feeds. See\n[Database portability](docs/database-portability.md) for schema requirements\nand generated columns.\n\n## TypeScript\n\nTypeScript declarations are included. Configuration types include:\n\n- `GtfsSqliteImportConfig` for `importGtfs()`\n- `GtfsImportConfig` for `importGtfsToKysely()`\n- `GtfsExportConfig` for `exportGtfs()`\n- `GtfsRealtimeConfig` for `updateGtfsRealtime()`\n\nGetter query fields, selected fields, and return values are inferred from the\ntable schemas. Schema declarations and the `GtfsDatabase` Kysely type are\nexported from both `gtfs` and `gtfs/schema`. See the\n[schema manifest](docs/schema-manifest.md).\n\n## Supported data\n\nIn addition to GTFS Schedule and GTFS-Realtime, node-GTFS includes schema and\nimport support for:\n\n- [GTFS-Plus](https://github.com/osplanning-data-standards/GTFS-PLUS)\n- [GTFS-Ride](https://gtfsride.org/)\n- [GTFS-to-HTML timetable files](https://gtfstohtml.com/)\n- [Transit Operational Data Standard (TODS)](https://tods-transit.org/)\n- TIDES\n- NOPTIS\n\nThe [query API guide](docs/query-api.md) lists the public getters. Other\nimported tables can be read with SQL through the SQLite connection.\n\n## Troubleshooting\n\nStart with the [troubleshooting guide](docs/troubleshooting.md) if a command is\nnot found, the database is empty, the configuration cannot be parsed, or a\nnative dependency does not install. Include the node-GTFS version, Node.js\nversion, command, and complete error when opening an\n[issue](https://github.com/BlinkTagInc/node-gtfs/issues).\n\n## Example applications\n\n- [GTFS-to-HTML](https://gtfstohtml.com/) generates transit timetables.\n- [GTFS-to-GeoJSON](https://github.com/BlinkTagInc/gtfs-to-geojson) creates\n GeoJSON for transit routes.\n- [GTFS-to-Chart](https://github.com/BlinkTagInc/gtfs-to-chart) generates\n stringline charts.\n- [GTFS Accessibility Validator](https://github.com/BlinkTagInc/gtfs-accessibility-validator)\n checks accessibility-related GTFS fields.\n- [GTFS Text-to-Speech](https://github.com/BlinkTagInc/gtfs-tts) tests stop\n name pronunciation.\n- [Transit Departures Widget](https://github.com/BlinkTagInc/transit-departures-widget)\n displays realtime departures.\n- [GTFS-to-Blocks](https://github.com/BlinkTagInc/gtfs-to-blocks) exports trip\n segments grouped by block.\n\n## Documentation\n\n- [Configuration reference](docs/configuration.md)\n- [Query API guide](docs/query-api.md)\n- [GTFS-Realtime guide](docs/realtime.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Database portability](docs/database-portability.md)\n- [Schema manifest](docs/schema-manifest.md)\n\n## Contributing\n\nPull requests are welcome. Run the checks before submitting a change:\n\n```bash\npnpm test\npnpm typecheck\npnpm lint\npnpm docs:check\n```\n\nnode-GTFS is available under the [MIT license](LICENSE.md).\n","readmeFilename":"README.md","users":{"vgeorge":true}}
![\"node-GTFS\"](\"docs/images/node-gtfs-logo.svg\"){kind=logo}
\n![\"npm](\"https://img.shields.io/npm/v/gtfs.svg?style=flat\")
\n ![\"monthly](\"https://img.shields.io/npm/dm/gtfs.svg?style=flat\")
\n ![\"build](\"https://img.shields.io/github/actions/workflow/status/BlinkTagInc/node-gtfs/nodejs.yml?branch=master\")
![\"MIT](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n