gtfs-bods/README.md

A CLI tool for processing UK Bus Open Data Service (BODS) GTFS data - import, export, and query transit data with ease

# GTFS BODS CLI

[![npm version](https://badge.fury.io/js/gtfs-bods.svg)](https://badge.fury.io/js/gtfs-bods)
[![Node.js Version](https://img.shields.io/node/v/gtfs-bods.svg)](https://nodejs.org)

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:

```bash
npm install -g gtfs-bods
```

### Basic Usage

```bash
# 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:

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

**Examples:**
```bash
# 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:

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

**Examples:**
```bash
# 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:

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

**Examples:**
```bash
# 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:

```bash
gtfs-bods info <file>
```

**Examples:**
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```typescript
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](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/DRFR0ST/gtfs-bods/issues)
- **Documentation**: [README](https://github.com/DRFR0ST/gtfs-bods#readme)
- **UK BODS**: [Bus Open Data Service](https://www.bus-data.dft.gov.uk/)

## 🙏 Acknowledgments

- [gtfs library](https://github.com/BlinkTagInc/node-gtfs) for GTFS processing
- [UK Department for Transport](https://www.gov.uk/government/organisations/department-for-transport) for BODS
- [Commander.js](https://github.com/tj/commander.js) for CLI framework
- [Chalk](https://github.com/chalk/chalk) for terminal styling

---

Made with ❤️ for the UK transit community