py-nycmta 0.2.0

Lightweight Python library for NYC MTA train arrival times

py-nycmta

A lightweight Python library for getting NYC MTA train arrival times. Simple, fast, and focused.

Installation

pip install py-nycmta

Quick Start

from py_nycmta import Train

# Create a train instance for any line
f_train = Train('F')

# Get arrivals at 7 Av (F24)
arrivals = f_train.get_arrivals('F24')

for arrival in arrivals:
    print(f"{arrival.train_id} train in {arrival.minutes_away} minutes ({arrival.direction}bound)")

Features

• Ultra-lightweight: Only 3 dependencies (httpx, gtfs-realtime-bindings, protobuf)
• Simple: Just one Train class for all subway lines
• Fast: Direct GTFS feed access, no unnecessary abstractions
• Type-safe: Full type hints for better IDE support

Usage

Basic Usage

from py_nycmta import Train

# Create train instances for any line
f_train = Train('F')
n_train = Train('N')
a_train = Train('A')
one_train = Train('1')

# Get arrivals at a stop
arrivals = f_train.get_arrivals('F24')  # 7 Av

Filter by Direction

f_train = Train('F')

# Get only northbound trains
northbound = f_train.get_arrivals('F24', direction='N')

# Get only southbound trains
southbound = f_train.get_arrivals('F24', direction='S')

Get Next Few Arrivals

f_train = Train('F')

# Get next 2 arrivals
next_trains = f_train.get_next_arrivals('F24', count=2)

Working with Arrival Data

f_train = Train('F')
arrivals = f_train.get_arrivals('F24')

for arrival in arrivals:
    print(f"Train: {arrival.train_id}")
    print(f"Minutes away: {arrival.minutes_away}")
    print(f"Direction: {arrival.direction}")
    print(f"Status: {arrival.status}")
    print(f"Arrival time: {arrival.arrival_time}")
    print(f"Stop ID: {arrival.stop_id}")
    print("---")

Supported Train Lines

All NYC subway lines are supported using the single Train class:

from py_nycmta import Train

# Letter trains
Train('A'), Train('B'), Train('C'), Train('D'), Train('E')
Train('F'), Train('G'), Train('J'), Train('L'), Train('M')
Train('N'), Train('Q'), Train('R'), Train('W'), Train('Z')

# Number trains  
Train('1'), Train('2'), Train('3'), Train('4'), Train('5'), Train('6'), Train('7')

Stop IDs

Use MTA stop IDs without the direction suffix:

• F24 - 7 Av
• A41 - Jay St-MetroTech
• R16 - Times Sq-42 St
• R20 - 14 St-Union Sq

The library automatically handles northbound (N) and southbound (S) directions.

Error Handling

from py_nycmta import Train

try:
    # Invalid train line
    train = Train('X')  # Raises ValueError
except ValueError as e:
    print(f"Error: {e}")  # Shows valid train options

try:
    train = Train('F')
    arrivals = train.get_arrivals('INVALID_STOP')
except Exception as e:
    print(f"Error: {e}")

Development

git clone https://github.com/dvd-rsnw/py-nycmta
cd py-nycmta
pip install -e ".[dev]"
pytest

Requirements

• Python 3.8+
• Internet connection (for MTA GTFS feeds)

License

MIT License - see LICENSE file for details.