Metadata-Version: 2.4
Name: trainfyi
Version: 0.1.1
Summary: Railway stations and train routes API client — trainfyi.com
Project-URL: Homepage, https://trainfyi.com
Project-URL: Documentation, https://trainfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/trainfyi
Project-URL: Issues, https://github.com/fyipedia/trainfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/trainfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: locomotive,rail,railway,route,station,train,transit,transport
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# trainfyi

[![PyPI version](https://agentgif.com/badge/pypi/trainfyi/version.svg)](https://pypi.org/project/trainfyi/)
[![Python](https://img.shields.io/pypi/pyversions/trainfyi)](https://pypi.org/project/trainfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/trainfyi/)

Python API client for railway data. Look up train stations worldwide, explore high-speed rail networks, query track gauge types, and retrieve railway operator information — all from [TrainFYI](https://trainfyi.com/), a railway reference platform covering passenger rail systems across continents.

TrainFYI catalogs railway stations with coordinates and operator associations, high-speed rail lines (Shinkansen, TGV, ICE, KTX), track gauge standards, signaling systems, and rolling stock — used by transit-tech developers, rail enthusiasts, and transportation analytics platforms.

> **Explore railways at [trainfyi.com](https://trainfyi.com/)** — browse by [country](https://trainfyi.com/countries/), search [stations](https://trainfyi.com/stations/), and explore rail networks.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/trainfyi/main/demo.gif" alt="trainfyi demo — railway station lookup, high-speed rail data, and route information in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [High-Speed Rail Networks](#high-speed-rail-networks)
  - [Track Gauge Types](#track-gauge-types)
  - [Railway Stations](#railway-stations)
  - [Signaling Systems](#signaling-systems)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Railways](#learn-more-about-railways)
- [Also Available](#also-available)
- [Transport FYI Family](#transport-fyi-family)
- [License](#license)

## Install

```bash
pip install trainfyi                # Core (zero deps)
pip install "trainfyi[cli]"         # + Command-line interface
pip install "trainfyi[mcp]"         # + MCP server for AI assistants
pip install "trainfyi[api]"         # + HTTP client for trainfyi.com API
pip install "trainfyi[all]"         # Everything
```

## Quick Start

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    # Look up a railway station
    station = api.get_station("tokyo-station")
    print(station["name"])          # Tokyo Station
    print(station["country"])       # Japan
    print(station["operator"])      # JR East
    print(station["lines"])         # Shinkansen, Chuo, Yamanote...

    # List stations by country
    stations = api.list_stations(country="france")
    for s in stations:
        print(f"{s['name']} — {s['city']}")

    # Search railway data
    results = api.search("shinkansen")
```

## What You Can Do

### High-Speed Rail Networks

High-speed rail (HSR) operates at speeds above 250 km/h on dedicated tracks. Japan pioneered the concept with the Shinkansen (1964), followed by France's TGV (1981). Today, China operates the world's largest HSR network at over 42,000 km, while Europe's network connects 10+ countries.

| System | Country | Max Speed | Network Length | Opened |
|--------|---------|-----------|---------------|--------|
| Shinkansen | Japan | 320 km/h | 3,000+ km | 1964 |
| TGV | France | 320 km/h | 2,800+ km | 1981 |
| ICE | Germany | 300 km/h | 1,600+ km | 1991 |
| AVE | Spain | 310 km/h | 3,600+ km | 1992 |
| KTX | South Korea | 305 km/h | 600+ km | 2004 |
| CRH | China | 350 km/h | 42,000+ km | 2007 |
| Frecciarossa | Italy | 300 km/h | 1,000+ km | 2009 |

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    # Search for high-speed rail lines
    results = api.search("shinkansen")
    for r in results:
        print(f"{r['name']} — {r.get('max_speed', 'N/A')} km/h")

    # Browse networks by country
    networks = api.list_networks(country="japan")
```

Learn more: [Rail Networks](https://trainfyi.com/networks/) · [Glossary](https://trainfyi.com/glossary/)

### Track Gauge Types

Track gauge — the distance between the inner faces of the rails — varies worldwide and determines rolling stock compatibility. Standard gauge (1,435 mm) is used by 60% of the world's railways, but significant networks operate on broad gauge (Russia, India, Iberia) or narrow gauge (Japan conventional, Southeast Asia).

| Gauge | Width | Where Used |
|-------|-------|-----------|
| Standard | 1,435 mm | Europe, China, US, Japan HSR, Korea |
| Russian/Finnish | 1,520/1,524 mm | Russia, CIS, Finland, Baltic states |
| Indian | 1,676 mm | India, Pakistan, Argentina |
| Iberian | 1,668 mm | Spain, Portugal (conventional) |
| Cape | 1,067 mm | Japan (conventional), South Africa, Australia |
| Meter | 1,000 mm | Southeast Asia, Switzerland, Brazil |
| Narrow | 762 mm | Heritage railways, mining |

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    # Look up gauge information by country
    country = api.get_country("japan")
    print(f"Gauges: {country.get('track_gauges')}")
    # Standard (Shinkansen), Cape gauge (conventional)
```

Learn more: [Track Gauges](https://trainfyi.com/guides/) · [Glossary](https://trainfyi.com/glossary/)

### Railway Stations

Railway stations range from major termini handling hundreds of thousands of daily passengers (Shinjuku: 3.5M/day, the world's busiest) to rural halts with a single platform. Station architecture often reflects the era of construction — grand 19th-century termini, modernist mid-century designs, and contemporary glass-and-steel structures.

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    # Get station details
    station = api.get_station("gare-du-nord")
    print(f"{station['name']}, {station['city']}")
    print(f"Operator: {station['operator']}")
    print(f"Lines: {station.get('lines', [])}")

    # List all stations in a country
    stations = api.list_stations(country="germany")
    print(f"{len(stations)} stations in Germany")
```

Learn more: [Station Directory](https://trainfyi.com/stations/) · [Guides](https://trainfyi.com/guides/)

### Signaling Systems

Railway signaling ensures safe train separation and routing. Modern systems range from traditional fixed-block signaling (trackside signals) to ERTMS/ETCS (European Train Control System) and CBTC (Communications-Based Train Control) for metros. Positive Train Control (PTC) is mandated in the United States.

| System | Type | Where Used |
|--------|------|-----------|
| ERTMS/ETCS | Moving block, cab signaling | EU interoperability standard |
| PTC | Overlay GPS/radio | United States (mandated) |
| ATC/ATS | Cab signaling | Japan (Shinkansen) |
| CBTC | Communications-based | Metro systems worldwide |
| TVM | Track-to-train transmission | France (TGV) |

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    # Search signaling systems
    results = api.search("ETCS")
    for r in results:
        print(r["name"])
```

Learn more: [Railway Technology](https://trainfyi.com/guides/) · [API Documentation](https://trainfyi.com/developers/)

## Command-Line Interface

```bash
pip install "trainfyi[cli]"

trainfyi station tokyo-station               # Station details
trainfyi search "gare du nord"               # Search stations
trainfyi country japan                       # All stations in Japan
trainfyi countries                           # List all countries
```

## MCP Server (Claude, Cursor, Windsurf)

```bash
pip install "trainfyi[mcp]"
```

```json
{
    "mcpServers": {
        "trainfyi": {
            "command": "uvx",
            "args": ["--from", "trainfyi[mcp]", "python", "-m", "trainfyi.mcp_server"]
        }
    }
}
```

## REST API Client

```python
from trainfyi.api import TrainFYI

with TrainFYI() as api:
    station = api.get_station("tokyo-station")       # GET /api/v1/stations/tokyo-station/
    stations = api.list_stations(country="france")    # GET /api/v1/stations/?country=france
    countries = api.list_countries()                  # GET /api/v1/countries/
    results = api.search("eurostar")                 # GET /api/v1/search/?q=eurostar
```

### Example

```bash
curl -s "https://trainfyi.com/api/v1/stations/tokyo-station/"
```

```json
{
    "slug": "tokyo-station",
    "name": "Tokyo Station",
    "city": "Tokyo",
    "country": "Japan",
    "operator": "JR East"
}
```

Full API documentation at [trainfyi.com/developers/](https://trainfyi.com/developers/).

## API Reference

| Function | Description |
|----------|-------------|
| `api.get_station(slug)` | Station details (location, operator, lines) |
| `api.list_stations(country)` | List stations, optionally by country |
| `api.list_countries()` | All countries with station counts |
| `api.get_country(slug)` | Country details with station list |
| `api.search(query)` | Search stations, networks, and operators |

## Learn More About Railways

- **Browse**: [Station Directory](https://trainfyi.com/stations/) · [Countries](https://trainfyi.com/countries/)
- **Guides**: [Railway Guides](https://trainfyi.com/guides/) · [Glossary](https://trainfyi.com/glossary/)
- **API**: [REST API Docs](https://trainfyi.com/developers/) · [OpenAPI Spec](https://trainfyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install trainfyi` | [npm](https://www.npmjs.com/package/trainfyi) |
| **MCP** | `uvx --from "trainfyi[mcp]" python -m trainfyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Transport FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — airports, airlines, aircraft, and railways.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| airportfyi | [PyPI](https://pypi.org/project/airportfyi/) | [npm](https://www.npmjs.com/package/airportfyi) | 4,500+ airports, IATA/ICAO codes, routes — [airportfyi.com](https://airportfyi.com/) |
| airlinefyi | [PyPI](https://pypi.org/project/airlinefyi/) | [npm](https://www.npmjs.com/package/airlinefyi) | Airlines, fleets, alliances, routes — [airlinefyi.com](https://airlinefyi.com/) |
| planefyi | [PyPI](https://pypi.org/project/planefyi/) | [npm](https://www.npmjs.com/package/planefyi) | Aircraft models, specifications, manufacturers — [planefyi.com](https://planefyi.com/) |
| **trainfyi** | [PyPI](https://pypi.org/project/trainfyi/) | [npm](https://www.npmjs.com/package/trainfyi) | **Railway stations, train routes, rail networks — [trainfyi.com](https://trainfyi.com/)** |

## License

MIT
