ttc-api/README.md

A fully typed Tbilisi Transport Company API Wrapper

# 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.

[![npm version](https://img.shields.io/npm/v/ttc-api.svg)](https://www.npmjs.com/package/ttc-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
# npm
npm install ttc-api

# yarn
yarn add ttc-api

# pnpm
pnpm add ttc-api
```

## Usage

### Basic Examples

```typescript
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

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

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

#### Monitor Real-time Arrivals

```typescript
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.

```typescript
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.

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

#### `arrivalTimes(options: ArrivalOptions)`

Get arrival predictions for a stop.

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

### Types

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

```typescript
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](https://www.npmjs.com/package/requestly) for HTTP requests

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/sunneydev/ttc-api/issues) on GitHub.