gtfs-sqljs

Load GTFS data into sql.js SQLite database for querying in browser and Node.js

Try Demo View on GitHub

Features

🌐 Universal

Works in both browser and Node.js environments

📦 ZIP Loading

Load GTFS data directly from ZIP files (URL or local path)

🔍 Powerful Queries

Query stops, routes, trips, calendars with efficient SQLite indexes

💾 Export/Import

Export databases to ArrayBuffer for persistence

📘 TypeScript

Full TypeScript support with comprehensive GTFS types

✅ Tested

77+ tests covering all features with real GTFS data

Installation

npm install gtfs-sqljs sql.js

Quick Start

import { GtfsSqlJs } from 'gtfs-sqljs';
import { createSqlJsAdapter } from 'gtfs-sqljs/adapters/sql-js';

// Load from ZIP file (skip shapes.txt to reduce memory)
const gtfs = await GtfsSqlJs.fromZip('https://example.com/gtfs.zip', {
  adapter: await createSqlJsAdapter(),
  skipFiles: ['shapes.txt']
});

// Get all routes (using flexible API)
const routes = await gtfs.getRoutes();

// Get stops for a trip
const stops = await gtfs.getStops({ tripId: 'trip_id' });

// Get active trips for a date
const trips = await gtfs.getTrips({ date: '20240115' });

// Clean up
await gtfs.close();

API Methods

⭐ Flexible Filter-Based Methods (Recommended)

Pass optional filter objects to combine multiple criteria:

getStops(filters?) - Filter by: stopId, stopCode, name, tripId, limit
getRoutes(filters?) - Filter by: routeId, agencyId, limit
getTrips(filters?) - Filter by: tripId, routeId, date, directionId, limit
getStopTimes(filters?) - Filter by: tripId, stopId, routeId, date, directionId, limit

// Example: Get trips for a route on a specific date going one direction
const trips = await gtfs.getTrips({
  routeId: 'ROUTE_1',
  date: '20240115',
  directionId: 0
});

Calendar Methods

getActiveServiceIds(date) - Get active services for a date (YYYYMMDD)
getCalendarByServiceId(serviceId) - Get calendar by service ID
getCalendarDates(serviceId) - Get calendar date exceptions
getCalendarDatesForDate(date) - Get exceptions for a specific date

Shape Methods

getShapes(filters?) - Get shape points, optionally filtered by shapeId
getShapesToGeojson(filters?, precision?) - Get shapes as a GeoJSON FeatureCollection
buildOrderedStopList(tripIds) - Build the ordered stop list for a set of trips

GTFS-Realtime Methods

setRealtimeFeedUrls(urls) - Configure RT feed URLs
fetchRealtimeData(urls?) - Fetch and load RT data
loadRealtimeDataFromBuffers(buffers) - Load pre-fetched protobuf buffers
clearRealtimeData() - Clear loaded RT data
getAlerts(filters?) - Get service alerts
getVehiclePositions(filters?) - Get vehicle positions
getTripUpdates(filters?) - Get trip updates
getStopTimeUpdates(filters?) - Get stop-time updates

Database Methods

export() - Export database to ArrayBuffer (async; throws ExportNotSupportedError on file-backed adapters)
getDatabase() - Get the underlying GtfsDatabase adapter handle (async prepare/run/export/close)
close() - Close database connection (async)

All query methods return Promise<T>. Direct lookups like getStopById / getRouteById / getTripById / getAgencyById have been replaced by the filter-based methods above (e.g. getStops({ stopId })).

Author

Théophile Helleboid / SysDevRun

Email: contact@sys-dev-run.fr

Website: www.sys-dev-run.fr

License

MIT License