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.
This library has three parts: the GTFS import script, the query methods and the GTFS export script
The GTFS-to-HTML app 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.
The GTFS-to-geojson app 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.
The GTFS-to-chart app 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.
If you would like to use this library as a command-line utility, you can install it globally directly from npm:
npm install gtfs -g
If you are using this as a node module as part of an application, you can include it in your project's package.json
file.
gtfs-import [--configPath /path/to/your/custom-config.json]
const gtfs = require('gtfs');
const config = require('./config.json');
gtfs.import(config)
.then(() => {
console.log('Import Successful');
})
.catch(err => {
console.error(err);
});
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. |
csvOptions |
object | Options passed to csv-parse for parsing GTFS CSV files. Optional. |
sqlitePath |
string | A path to an 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. |
{Array} Specify the GTFS files to be imported in an agencies
array. GTFS files can be imported via a url
or a local path
.
Each file needs an agency_key
, a short name you create that is specific to that GTFS file. 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.
To find an agency's GTFS file, visit transitfeeds.com. You can use the URL from the agency's website or you can use a URL generated from the transitfeeds.com API along with your API token.
- Specify a download URL:
{
"agencies": [
{
"agency_key": "county-connection",
"url": "http://countyconnection.com/GTFS/google_transit.zip"
}
]
}
- Specify a download URL with custom headers:
{
"agencies": [
{
"agency_key": "county-connection",
"url": "http://countyconnection.com/GTFS/google_transit.zip",
"headers: {
"Content-Type": "application/json",
"Authorization": "bearer 1234567890"
},
}
]
}
- Specify a path to a zipped GTFS file:
{
"agencies": [
{
"agency_key": "myAgency",
"path": "/path/to/the/gtfs.zip"
}
]
}
- Specify a path to an unzipped GTFS file:
{
"agencies": [
{
"agency_key": "myAgency",
"path": "/path/to/the/unzipped/gtfs/"
}
]
}
- Exclude files - if you don't want all GTFS files to be imported, you can specify an array of files to exclude.
{
"agencies": [
{
"agency_key": "myAgency",
"path": "/path/to/the/unzipped/gtfs/",
"exclude": [
"shapes",
"stops"
]
}
]
}
{Object} Add options to be passed to csv-parse
wiith the key csvOptions
. This is an optional paramenter.
For instance, if you wanted to skip importing invalid lines in the GTFS file:
"csvOptions": {
"skip_lines_with_error": true
}
See full list of options.
{String} A path to an SQLite database. Optional, defaults to using an in-memory database with a value of :memory:
.
"sqlitePath": "/dev/sqlite/gtfs"
{Boolean} If you don't want the import script to print any output to the console, you can set verbose
to false
. Defaults to true
.
{
"agencies": [
{
"agency_key": "localAgency",
"path": ""/path/to/the/unzipped/gtfs/"
}
],
"verbose": false
}
If you want to route logs to a custom function, you can pass a function that takes a single text
argument as logFunction
. This can't be defined in config.json
but instead passed in a config object to gtfs.import()
. For example:
const gtfs = require('gtfs');
const config = {
agencies: [
{
agency_key: 'county-connection',
url: 'http://countyconnection.com/GTFS/google_transit.zip',
exclude: [
'shapes'
]
}
],
logFunction: function(text) {
// Do something with the logs here, like save it or send it somewhere
console.log(text);
}
};
gtfs.import(config);
The gtfs-import
script reads from a JSON configuration file and imports the GTFS files specified to a SQLite database. Read more on setting up your configuration file.
gtfs-import
By default, it will look for a config.json
file in the project root. To specify a different path for the configuration file:
gtfs-import --configPath /path/to/your/custom-config.json
Use gtfs.import()
in your code to run an import of a GTFS file specified in a config.json file.
const gtfs = require('gtfs');
const config = require('config.json');
gtfs.import(config)
.then(() => {
console.log('Import Successful');
})
.catch(err => {
console.error(err);
});
Configuration can be a JSON object in your code
const gtfs = require('gtfs');
const config = {
sqlitePath: '/dev/sqlite/gtfs',
agencies: [
{
agency_key: 'county-connection',
url: 'http://countyconnection.com/GTFS/google_transit.zip',
exclude: [
'shapes'
]
}
]
};
gtfs.import(config)
.then(() => {
console.log('Import Successful');
})
.catch(err => {
console.error(err);
});
The gtfs-export
script reads from a JSON configuration file and exports data in GTFS format from a SQLite database. Read more on setting up your configuration file.
This could be used to export a GTFS file from SQLite after changes have been made to the data in the database manually.
Nothing will be exported if there is no data to export. See the GTFS import script.
gtfs-export
By default, it will look for a config.json
file in the project root. To specify a different path for the configuration file:
gtfs-export --configPath /path/to/your/custom-config.json
You can specify the path to a config file to be used by the export script.
gtfs-export --configPath /path/to/your/custom-config.json
Show all command line options
gtfs-export --help
Use gtfs.export()
in your code to run an export of a GTFS file specified in a config.json file.
const gtfs = require('gtfs');
const config = {
sqlitePath: '/dev/sqlite/gtfs',
agencies: [
{
agency_key: 'county-connection',
url: 'http://countyconnection.com/GTFS/google_transit.zip',
exclude: [
'shapes'
]
}
]
};
gtfs.export(config)
.then(() => {
console.log('Export Successful');
})
.catch(err => {
console.error(err);
});
This library includes many methods you can use in your project to query GTFS data. These methods return promises.
Most methods accept three optional arguments: query
, fields
and sortBy
.
For example, to get a list of all routes with just route_id
, route_short_name
and route_color
sorted by route_short_name
:
const db = await gtfs.openDb(config);
const routes = await gtfs.getRoutes(
{},
[
'route_id',
'route_short_name',
'route_color'
],
[
['route_short_name', 'ASC']
]
);
To get a list of all trips with for a specific route:
const db = await gtfs.openDb(config);
const trips = await gtfs.getTrips(
{
route_id: '123'
}
);
To get a few stops by specific stop_ids:
const db = await gtfs.openDb(config);
const stops = await gtfs.getStops(
{
stop_id: [
'123',
'234'
'345'
]
}
);
Include this library.
const gtfs = require('gtfs');
Open database before making any queries
const db = await gtfs.openDb(config);
Queries agencies and returns a promise. The result of the promise is an array of agencies.
// Get all agencies
gtfs.getAgencies();
// Get a specific agency
gtfs.getAgencies({
agency_id: 'caltrain'
});
Queries attributions and returns a promise. The result of the promise is an array of attributions.
// Get all attributions
gtfs.getAttributions();
// Get a specific attribution
gtfs.getAttributions({
attribution_id: '123'
});
Queries routes and returns a promise. The result of the promise is an array of routes.
// Get all routes, sorted by route_short_name
gtfs.getRoutes(
{},
[],
[
['route_short_name', 'ASC']
]
);
// Get a specific route
gtfs.getRoutes({
route_id: 'Lo-16APR'
});
getRoutes
allows passing a stop_id
in the query and it will query stoptimes and trips to find all routes that serve that stop_id
.
// Get routes that serve a specific stop, sorted by `stop_name`.
gtfs.getRoutes(
{
stop_id: '70011'
},
[],
[
['stop_name', 'ASC']
]
);
Queries stops and returns a promise. The result of the promise is an array of stops.
// Get all stops
gtfs.getStops();
// Get a specific stop by stop_id
gtfs.getStops({
stop_id: '70011'
});
getStops
allows passing a route_id
in the query and it will query trips and stoptimes to find all stops served by that route_id
.
// Get all stops for a specific route
gtfs.getStops({
route_id: 'Lo-16APR'
});
getStops
allows passing a trip_id
in the query and it will query stoptimes to find all stops on that trip_id
.
// Get all stops for a specific trip
gtfs.getStops({
trip_id: '37a'
});
Queries stops and returns a promise. The result of the promise is an geoJSON object of stops. All valid queries for gtfs.getStops()
work for gtfs.getStopsAsGeoJSON()
.
// Get all stops for an agency as geoJSON
gtfs.getStopsAsGeoJSON();
// Get all stops for a specific route as geoJSON
gtfs.getStopsAsGeoJSON({
route_id: 'Lo-16APR'
});
Queries stop_times
and returns a promise. The result of the promise is an array of stop_times
.
// Get all stoptimes
gtfs.getStoptimes();
// Get all stoptimes for a specific stop
gtfs.getStoptimes({
stop_id: '70011'
});
// Get all stoptimes for a specific trip, sorted by stop_sequence
gtfs.getStoptimes(
{
trip_id: '37a'
},
[],
[
['stop_sequence', 'ASC']
]
);
// Get all stoptimes for a specific stop and service_id
gtfs.getStoptimes({
stop_id: '70011',
service_id: 'CT-16APR-Caltrain-Weekday-01'
});
Queries trips and returns a promise. The result of the promise is an array of trips.
// Get all trips
gtfs.getTrips();
// Get trips for a specific route and direction
gtfs.getTrips({
route_id: 'Lo-16APR',
direction_id: 0
});
// Get trips for a specific route and direction limited by a service_id
gtfs.getTrips({
route_id: 'Lo-16APR',
direction_id: 0,
service_id: '
});
Queries shapes and returns a promise. The result of the promise is an array of shapes.
// Get all shapes for an agency
gtfs.getShapes();
getShapes
allows passing a route_id
in the query and it will query trips to find all shapes served by that route_id
.
// Get all shapes for a specific route and direction
gtfs.getShapes({
route_id: 'Lo-16APR',
});
getShapes
allows passing a trip_id
in the query and it will query trips to find all shapes served by that trip_id
.
// Get all shapes for a specific trip_id
gtfs.getShapes({
trip_id: '37a'
});
getShapes
allows passing a service_id
in the query and it will query trips to find all shapes served by that service_id
.
// Get all shapes for a specific service_id
gtfs.getShapes({
service_id: 'CT-16APR-Caltrain-Sunday-02'
});
Queries shapes and returns a promise. The result of the promise is an geoJSON object of shapes. All valid queries for gtfs.getShapes()
work for gtfs.getShapesAsGeoJSON()
.
Returns geoJSON of shapes.
// Get geoJSON of all stops in an agency
gtfs.getShapesAsGeoJSON();
// Get geoJSON of stops along a specific route
gtfs.getShapesAsGeoJSON({
route_id: 'Lo-16APR'
});
// Get geoJSON of stops for a specific trip
gtfs.getShapesAsGeoJSON({
trip_id: '37a'
});
// Get geoJSON of stops for a specific `service_id`
gtfs.getShapesAsGeoJSON({
service_id: 'CT-16APR-Caltrain-Sunday-02'
});
Queries calendars and returns a promise. The result of the promise is an array of calendars.
// Get all calendars for an agency
gtfs.getCalendars();
// Get calendars for a specific `service_id`
gtfs.getCalendars({
service_id: 'CT-16APR-Caltrain-Sunday-02'
});
Queries calendar_dates and returns a promise. The result of the promise is an array of calendar_dates.
// Get all calendar_dates for an agency
gtfs.getCalendarDates();
// Get calendar_dates for a specific `service_id`
gtfs.getCalendarDates({
service_id: 'CT-16APR-Caltrain-Sunday-02'
});
Queries fare_rules and returns a promise. The result of the promise is an array of fare_rules.
// Get all `fare_rules` for an agency
gtfs.getFareRules();
// Get fare_rules for a specific route
gtfs.getFareRules({
route_id: 'Lo-16APR'
});
Queries feed_info and returns a promise. The result of the promise is an array of feed_infos.
// Get feed_info
gtfs.getFeedInfo();
Queries frequencies and returns a promise. The result of the promise is an array of frequencies.
// Get all frequencies
gtfs.getFrequencies();
// Get frequencies for a specific trip
gtfs.getFrequencies({
trip_id: '1234'
});
Queries levels and returns a promise. The result of the promise is an array of levels.
// Get levels
gtfs.getLevels();
Queries pathways and returns a promise. The result of the promise is an array of pathways.
// Get pathways
gtfs.getPathways();
Queries transfers and returns a promise. The result of the promise is an array of transfers.
// Get all transfers
gtfs.getTransfers();
// Get transfers for a specific stop
gtfs.getTransfers({
from_stop_id: '1234'
});
Queries translations and returns a promise. The result of the promise is an array of translations.
// Get translations
gtfs.getTranslations();
Queries stop_attributes and returns a promise. The result of the promise is an array of stop_attributes. These are from the non-standard stop_attributes.txt
file. See documentation and examples of this file.
// Get all stop attributes
gtfs.getStopAttributes();
// Get stop attributes for specific stop
gtfs.getStopAttributes({
stop_id: '1234'
});
Queries timetables and returns a promise. The result of the promise is an array of timetables. These are from the non-standard timetables.txt
file. See [documentation and examples of this file](https://gtfstohtml.com/docs/timetables.
// Get all timetables for an agency
gtfs.getTimetables();
// Get a specific timetable
gtfs.getTimetables({
timetable_id: '1'
});
Queries timetable_stop_orders and returns a promise. The result of the promise is an array of timetable_stop_orders. These are from the non-standard timetable_stop_order.txt
file. See documentation and examples of this file.
// Get all timetable_stop_orders
gtfs.getTimetableStopOrders();
// Get timetable_stop_orders for a specific timetable
gtfs.getTimetableStopOrders({
timetable_id: '1'
});
Queries timetable_pages and returns a promise. The result of the promise is an array of timetable_pages. These are from the non-standard timetable_pages.txt
file. See documentation and examples of this file.
// Get all timetable_pages for an agency
gtfs.getTimetablePages();
// Get a specific timetable_page
gtfs.getTimetablePages({
timetable_page_id: '2'
});
Pull requests are welcome, as is feedback and reporting issues.
To run tests:
npm test
To run a specific test:
NODE_ENV=test mocha ./test/mocha/gtfs.get-stoptimes.js
npm run lint