StationAPI

A gRPC-Web API that provides nearby Japanese train stations.

Documentation

• For automation agent and contributor workflows, see AGENTS.md.
• For contribution guidelines, see CONTRIBUTING.md.
• For system architecture and design decisions, see docs/architecture.md.
• For technical debt analysis and architectural concerns, see docs/technical_debt.md.

Data Contribution

This project includes a comprehensive dataset of Japanese railway information in the data/ directory. The data is maintained in CSV format and contributions are primarily targeted at Japanese speakers. For detailed information about data structure and contribution guidelines, please refer to data/README.md.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Kanta Demizu 🔣 🚇 💻

SAIGUSA Tomotada 🤔 🔣

mittan12 🔣

CodeRabbit 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

Join our community(Japanese only)

Do you like this project? Join our Discord community! https://discord.gg/tsemdME9Nz

Development

Running Tests

This project includes comprehensive tests for the repository layer:

Unit Tests (No database required)

# Using Cargo directly
cargo test --lib --package stationapi

# Or using Make
make test-unit

Integration Tests (Requires PostgreSQL)

# Set up environment and run integration tests
source .env.test
cargo test --lib --package stationapi --features integration-tests

# Or using Make
make test-integration

All Tests

# Run unit tests followed by integration tests
make test-all

For detailed testing information, see docs/repository_testing.md.

Test Coverage

Repository layer tests cover:

• ✅ Data conversion logic (Row → Entity)
• ✅ Database query operations
• ✅ Error handling and edge cases
• ✅ Filtering conditions (e_status, pass fields)
• ✅ Alias handling (line names)
• ✅ Type conversions (u32 ↔ i32, u32 ↔ i64)

Testing Philosophy

We follow Rust best practices for testing:

• Unit tests run without external dependencies (fast, always available)
• Integration tests controlled by feature flags (opt-in when database is available)
• Cargo-native test execution using standard cargo test commands
• Makefile shortcuts for common testing workflows

Data Sources

• Bus-related data provided by Tokyo Metropolitan Bureau of Transportation (Toei), licensed under CC BY 4.0
• Bus-related data provided by Seibu Bus Co., Ltd. (西武バス) via the Public Transportation Open Data Center, licensed under the Public Transportation Open Data Basic License
• Station data provided by 駅データ.jp
• Speed calibration data (speed_table.rs) derived from GTFS timetables provided by Kyoto City Transportation Bureau (京都市交通局), Yokohama City Transportation Bureau (横浜市交通局), Tokyo Metro (東京メトロ), Metropolitan Intercity Railway (首都圏新都市鉄道), Tokyo Tama Intercity Monorail (多摩都市モノレール), and Tokyo Waterfront Area Rapid Transit (東京臨海高速鉄道) via the Public Transportation Open Data Center, licensed under the Public Transportation Open Data Basic License; by Tokyo Metropolitan Bureau of Transportation (Toei), licensed under CC BY 4.0; and by Hakodate City Enterprise Bureau Transportation Department (函館市企業局交通部), licensed under GTFS-RUL (ODPT)
• Average inter-station distances (average_distance) computed from railway track geometry © OpenStreetMap contributors, licensed under ODbL