GTFS BODS CLI

A powerful command-line tool for processing UK Bus Open Data Service (BODS) GTFS data. Import GTFS zip files into SQLite databases, query transit data, and export back to GTFS format with ease.

🚀 Quick Start

Installation

Install globally via npm:

npm install -g gtfs-bods

Basic Usage

# Import GTFS zip file to SQLite database
gtfs-bods import ./data.zip ./gtfs.db

# Query the database
gtfs-bods query ./gtfs.db --report

# Export back to GTFS format
gtfs-bods export ./gtfs.db ./output-gtfs/

# Get file information
gtfs-bods info ./data.zip

📋 Commands

import - Import GTFS Data

Convert a GTFS zip file into a SQLite database:

gtfs-bods import <zip-file> <db-file> [options]

Examples:

# Basic import
gtfs-bods import ./london-buses.zip ./london.db

# Import with custom agency key
gtfs-bods import ./data.zip ./gtfs.db --agency-key london-transport

Options:

• -k, --agency-key <key> - Custom agency key (default: 'gtfs-data')
• -v, --verbose - Enable verbose logging

export - Export to GTFS Format

Export SQLite database back to GTFS text files:

gtfs-bods export <db-file> <output-dir> [options]

Examples:

# Export to directory
gtfs-bods export ./gtfs.db ./exported-gtfs/

# Export with custom agency key
gtfs-bods export ./gtfs.db ./output/ --agency-key london-transport

Options:

• -k, --agency-key <key> - Agency key to export (default: 'gtfs-data')
• -v, --verbose - Enable verbose logging

query - Query Database

Query and analyze GTFS data:

gtfs-bods query <db-file> [options]

Examples:

# Basic statistics
gtfs-bods query ./gtfs.db

# Comprehensive report
gtfs-bods query ./gtfs.db --report

# List all agencies
gtfs-bods query ./gtfs.db --agencies

# List routes
gtfs-bods query ./gtfs.db --routes

# List stops
gtfs-bods query ./gtfs.db --stops

# Find stops in geographic area (London area example)
gtfs-bods query ./gtfs.db --area "51.3,-0.5,51.7,0.3"

# Get route details
gtfs-bods query ./gtfs.db --route-id "12345"

# Filter by agency
gtfs-bods query ./gtfs.db --routes --agency-key london-transport

Options:

• -r, --report - Generate comprehensive report
• -a, --agencies - List all agencies
• -R, --routes - List all routes
• -s, --stops - List all stops
• -k, --agency-key <key> - Filter by agency key
• --route-id <id> - Get details for specific route
• --area <bounds> - Find stops in area (format: minLat,minLon,maxLat,maxLon)

info - File Information

Display information about GTFS files or databases:

gtfs-bods info <file>

Examples:

# Analyze GTFS zip file
gtfs-bods info ./data.zip

# Analyze SQLite database
gtfs-bods info ./gtfs.db

🌟 Features

• 🚌 GTFS Processing: Full support for GTFS specification
• 🗄️ SQLite Storage: Efficient database storage and querying
• 🔍 Data Analysis: Comprehensive reporting and statistics
• 🗺️ Geographic Queries: Find stops within geographic boundaries
• 📤 Data Export: Export processed data back to GTFS format
• 🎨 Colored Output: Beautiful terminal output with chalk
• ⚡ Fast Performance: Optimized for large datasets
• 🛠️ TypeScript: Fully typed with modern ES modules

📊 Example Workflows

Basic Data Processing

# 1. Download GTFS data from UK BODS
wget https://data.bus-data.dft.gov.uk/timetable/download/gtfs-file/all/ -O uk-bods.zip

# 2. Import into database
gtfs-bods import uk-bods.zip uk-transit.db

# 3. Generate report
gtfs-bods query uk-transit.db --report

# 4. Export for use in other tools
gtfs-bods export uk-transit.db ./gtfs-export/

Transit Analysis

# Analyze London area transit
gtfs-bods query ./uk-transit.db --area "51.28,-0.51,51.69,0.33" > london-stops.txt

# Find all bus routes
gtfs-bods query ./uk-transit.db --routes | grep -i "bus" > bus-routes.txt

# Get agency information
gtfs-bods query ./uk-transit.db --agencies

Data Migration

# Convert old GTFS data to new format
gtfs-bods import ./old-data.zip ./temp.db
gtfs-bods export ./temp.db ./new-gtfs-format/

📁 Database Schema

The SQLite database follows the GTFS specification:

• agencies - Transit agencies and operators
• routes - Bus/transit routes
• stops - Bus stops and stations
• trips - Individual trip instances
• stop_times - Detailed timetable data
• calendar - Service periods and schedules
• shapes - Route geometry for mapping (if available)

🛠️ Development

Local Development

# Clone repository
git clone https://github.com/DRFR0ST/gtfs-bods.git
cd gtfs-bods

# Install dependencies
npm install

# Build project
npm run build

# Test CLI locally
npm run dev:cli -- import ./test.zip ./test.db

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run dev:cli | Run CLI in development mode | | npm start | Build and run main application | | npm run prepublishOnly | Pre-publish build step |

🚀 API Usage

You can also use the tool programmatically:

import { importGtfs, exportGtfs } from 'gtfs';
import { GTFSQueries } from 'gtfs-bods/dist/queries.js';

// Import GTFS data
const config = {
  agencies: [
    {
      agency_key: 'my-transit',
      path: './data.zip'
    }
  ],
  sqlitePath: './transit.db'
};

await importGtfs(config);

// Query data
const agencies = await GTFSQueries.getAllAgencies();
const routes = await GTFSQueries.getAllRoutes();

🔧 Requirements

• Node.js 18.0.0 or higher
• npm 6.0.0 or higher

📦 Data Sources

This tool works with GTFS data from various sources:

• UK Bus Open Data Service (BODS): https://data.bus-data.dft.gov.uk/
• Any GTFS-compliant data source
• Transit agencies worldwide

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: README
• UK BODS: Bus Open Data Service

🙏 Acknowledgments

• gtfs library for GTFS processing
• UK Department for Transport for BODS
• Commander.js for CLI framework
• Chalk for terminal styling

Made with ❤️ for the UK transit community