ttc-api

A fully typed TypeScript wrapper for the Tbilisi Transport Company (TTC) API, providing real-time access to public transport data in Tbilisi, Georgia.

Features

• 🚌 Real-time bus locations and arrival times
• 🗺️ Route planning and navigation
• 🎯 Bus stop information
• ⌚ Live arrival predictions
• 📝 Full TypeScript support
• 🌍 Multilingual support (Georgian and English)

Installation

# npm
npm install ttc-api

# yarn
yarn add ttc-api

# pnpm
pnpm add ttc-api

Usage

Basic Examples

import { ttc } from "ttc-api";

// Set preferred language (optional, defaults to 'en')
ttc.setLocale("en"); // or "ka" for Georgian

// Get all bus stops
const stops = await ttc.stops();

// Get arrival times for a specific stop
const arrivals = await ttc.arrivalTimes({
  stopId: "1946",
  ignoreScheduledArrivalTimes: false,
});

// Get real-time bus locations
const busLocations = await ttc.locations({
  busId: "123",
  forward: true,
});

// Plan a route
const journey = await ttc.plan({
  from: [41.7151, 44.8271], // [latitude, longitude]
  to: [41.7099, 44.7929],
  locale: "en",
});

Advanced Usage

Get Routes for a Specific Stop

const stopRoutes = await ttc.stopRoutes({
  stopId: "1946",
  locale: "en",
});

stopRoutes.forEach((route) => {
  console.log(`Bus ${route.shortName}: ${route.longName}`);
});

Monitor Real-time Arrivals

const monitorArrivals = async (stopId: string) => {
  const arrivals = await ttc.arrivalTimes({ stopId });

  arrivals.forEach((arrival) => {
    console.log(
      `Bus ${arrival.shortName} arriving in ${arrival.realtimeArrivalMinutes} minutes`
    );
    console.log(`Status: ${arrival.realtime ? "Real-time" : "Scheduled"}`);
  });
};

API Reference

Core Functions

setLocale(locale: "ka" | "en")

Set the preferred language for responses.

stops(params?: { locale?: "ka" | "en" })

Get all bus stops in the network.

stop(stopId: string)

Get detailed information about a specific stop.

routes(params?: { locale?: "ka" | "en" })

Get all bus routes.

plan(options: PlanOptions)

Plan a journey between two points.

interface PlanOptions {
  from: [number, number]; // [latitude, longitude]
  to: [number, number]; // [latitude, longitude]
  locale?: "ka" | "en";
}

locations(options: LocationOptions)

Get real-time locations of buses on a route.

interface LocationOptions {
  busId: string;
  forward?: boolean;
}

arrivalTimes(options: ArrivalOptions)

Get arrival predictions for a stop.

interface ArrivalOptions {
  stopId: string;
  locale?: "ka" | "en";
  ignoreScheduledArrivalTimes?: boolean;
}

Types

The library includes comprehensive TypeScript definitions for all API responses. Key types include:

type Locale = "ka" | "en";

interface BusStop {
  id: string;
  code: string | null;
  name: string;
  lat: number;
  lon: number;
  vehicleMode: "BUS" | "GONDOLA" | "SUBWAY";
}

interface BusArrival {
  shortName: string;
  color: string;
  headsign: string;
  realtime: boolean;
  realtimeArrivalMinutes: number;
  scheduledArrivalMinutes: number;
}

// ... and more

Acknowledgments

• Built with requestly for HTTP requests

Support

If you encounter any issues or have questions, please open an issue on GitHub.