irctc-api 🚆

The official, ultra-fast Python SDK for the IRCTC Developer Network. Zero external dependencies, typed exceptions, and sub-10ms response times for Indian Railways train intelligence, live GPS status, station boards, and PNR enquiries.

⚡ Highlights

• Zero Dependencies: Pure Python standard library (urllib). Installs in <0.3s, zero dependency conflicts, lightweight (<20 KB).
• Sub-10ms Offline Lookups: Instant train schedules, route halts, and station autocomplete from an in-memory 10,647-route corpus.
• Multi-Provider Failover: PNR checks resolve in 2.9s with passenger berth allocations (LOWER, MIDDLE, SIDE UPPER), platform numbers, and coach positions.
• Live GPS Telemetry: Dual-engine failover (~180–350ms) for real-time train running status, delay minutes, and upcoming stations.
• 10,000 Free Credits: Get your API key in 5 seconds with 1-click Google Login at irctc.dev (no credit card required).

📦 Installation

pip install irctc-api

🚀 Quickstart

from irctc import RailEngine

# Initialize with your API key from https://irctc.dev
rail = RailEngine("YOUR_API_KEY")

# 1. Check PNR Status (2.9s multi-provider resolution)
pnr = rail.pnr.check("2265248473")
print(f"Train: {pnr['train_name']} ({pnr['train_number']})")
for p in pnr.get("passengers", []):
    print(f"  Passenger {p['number']}: {p['current_status']} [Berth: {p['berth']}]")

# 2. Live Train GPS Running Status (~180ms latency)
live = rail.live.get_status("12557")
print(f"Current Station: {live['current_station_name']} | Delay: {live['delay_minutes']} mins")

# 3. Calculate Ticket Fare Breakup (Base, GST, Superfast, Catering)
fare = rail.trains.get_fare("12558", from_station="ANVT", to_station="MFP", travel_class="all")
for cls, details in fare.get("classes", {}).items():
    print(f"Class {cls}: ₹{details['totalFare']}")

# 4. Today's Cancelled Trains Across Indian Railways
cancelled = rail.trains.get_cancelled()
print(f"Total cancelled trains today: {len(cancelled)}")

🛠️ Complete Method Catalog

🚆 Trains Namespace (rail.trains)

📍 Stations Namespace (rail.stations)

📡 Live Status Namespace (rail.live)

🎫 PNR Namespace (rail.pnr)

🩺 System Health (rail.health)

health = rail.health()
print(health) # {'status': 'healthy', 'uptime': 34210, 'corpus': '10,647 routes loaded'}

🛡️ Error Handling

The client provides typed exceptions mapped directly to API responses:

from irctc import RailEngine
from irctc.exceptions import (
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    NotFoundError,
    TimeoutError,
    IrctcApiError
)

rail = RailEngine("YOUR_API_KEY")

try:
    pnr = rail.pnr.check("2265248473")
except AuthenticationError:
    print("Invalid or missing API key. Get one at https://irctc.dev")
except InsufficientCreditsError:
    print("Zero credits remaining. Recharge ₹99 for 100,000 credits on irctc.dev")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except NotFoundError:
    print("Train or PNR not found.")
except TimeoutError:
    print("Network request timed out.")
except IrctcApiError as e:
    print(f"API Error [{e.status_code}]: {e.message}")

⚙️ Configuration & Environment Variables

You can configure the client via environment variables instead of hardcoding keys:

export IRCTC_API_KEY="re_live_your_secret_key"
export IRCTC_API_BASE_URL="https://api.irctc.dev" # Optional

import os
from irctc import RailEngine

# Automatically reads from IRCTC_API_KEY
rail = RailEngine()

Custom timeout and headers:

rail = RailEngine(
    api_key="re_live_...",
    timeout=15.0,  # 15 seconds timeout
    headers={"x-custom-tag": "telegram-bot"}
)

🤝 Community & Support

• Portal & API Keys: https://irctc.dev
• Documentation: https://irctc.dev/docs
• Interactive Playground: https://irctc.dev/playground
• Email: support@irctc.dev

📄 License

MIT License. Copyright (c) 2026 IRCTC Developer Network.