# ATL Transit Live LLM Context

## Project

ATL Transit Live is an unofficial MARTA service data project. It tracks bus reliability from MARTA alert and GTFS-derived data, integrates MARTA rail realtime arrivals, detects major bus and rail delays, and exposes metered API endpoints for REST, SSE output, webhooks, and bulk historical exports.

This service is not affiliated with, endorsed by, or sponsored by MARTA.

## Human Pages

- Home: https://atltransit.live/
- Bus Routes: https://atltransit.live/routes
- Rail Routes: https://atltransit.live/rail
- Alerts: https://atltransit.live/alerts
- Status: https://atltransit.live/status
- Developer API: https://atltransit.live/developers
- API Docs: https://atltransit.live/api-docs

## Machine-Readable Docs

- OpenAPI: https://atltransit.live/api/v1/openapi.yaml
- Short LLM guide: https://atltransit.live/llms.txt

## API Authentication

The public API uses bearer API keys:

```http
Authorization: Bearer mf_live_...
```

Launch scopes:

- `read:routes`
- `read:alerts`
- `read:rail`
- `read:history`
- `write:webhooks`

## REST Endpoints

### `GET /api/v1/rail`

Rail line metadata and related links, including `/api/v1/rail/realtime` and rail-filtered alerts.

### `GET /api/v1/rail/realtime`

Normalized MARTA rail realtime arrivals. Supports `line`, `station`, `minutes`, `limit`, and `cursor`. The response includes `rail_status.lines[].stations[].trains[]`, line and station delay summaries, and source metadata. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/rail/{line}/reliability`

Rail line reliability rollups. Supports `period` and `breakdown`. Empty record sets are valid when no retained reliability rows exist for the requested rail line/window. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/rail/alerts`

Rail alerts read stored `generated_service_alerts` rows from PostgreSQL when persistence is configured. Supports `status`, `route_or_line`, `station`, `source`, `limit`, and `cursor`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/bus`

Bus route metadata and reliability snapshots.

### `GET /api/v1/bus/realtime`

GTFS-RT bus vehicle positions. Supports `route_id`, `minutes`, `limit`, and `cursor`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/bus/{route_id}/realtime`

GTFS-RT bus vehicle positions for one route. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/bus/{route_id}/reliability`

Reliability rollups. Supports `period` and `breakdown`. Records preserve `data_source` values such as `wmb`, `email`, and `realtime`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/bus/alerts`

Bus alerts read stored `generated_service_alerts` rows from PostgreSQL when persistence is configured. Supports `status`, `route_or_line`, `station`, `source`, `limit`, and `cursor`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/streetcar`

Streetcar route metadata and related alert links.

### `GET /api/v1/streetcar/realtime`

GTFS-RT streetcar vehicle positions. Supports `route_id`, `minutes`, `limit`, and `cursor`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/streetcar/{route_id}/reliability`

Streetcar reliability rollups when retained records are available. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/streetcar/alerts`

Streetcar alerts read stored `generated_service_alerts` rows from PostgreSQL when persistence is configured. Supports `status`, `route_or_line`, `station`, `source`, `limit`, and `cursor`. Returns JSON by default or SSE with `Accept: text/event-stream` / `format=sse`.

### `GET /api/v1/history/exports`

Historical export manifests for Parquet files on R2. Supports `dataset`, `start`, and `end`.

## SSE Output

SSE is a representation option for refreshed resources, not a separate primary resource. Request `Accept: text/event-stream` or `format=sse` on alert, realtime, and reliability resources.

## Webhooks

### `POST /api/v1/webhooks/endpoints`

Registers webhook endpoints with event type subscriptions and filters. Endpoint persistence requires production database wiring.

### `GET /api/v1/webhooks/deliveries`

Returns webhook delivery attempt history.

Webhook deliveries include:

```http
Marta-Fail-Signature: t=1780000000,v1=<hmac_sha256>
```

The signed payload is `${timestamp}.${body}`. Consumers should reject signatures outside a five-minute timestamp tolerance.

## Event Envelope

```json
{
  "id": "evt_...",
  "type": "rail.alert.created",
  "api_version": "v1",
  "created_at": "2026-05-27T16:00:00.000Z",
  "resource": "rail:BLUE",
  "data": {}
}
```

Launch event types:

- `rail.alert.created`
- `rail.alert.updated`
- `rail.alert.resolved`
- `rail.realtime.updated`
- `rail.reliability.updated`
- `bus.alert.created`
- `bus.alert.updated`
- `bus.alert.resolved`
- `bus.realtime.updated`
- `bus.reliability.updated`
- `streetcar.alert.created`
- `streetcar.alert.updated`
- `streetcar.alert.resolved`
- `streetcar.realtime.updated`
- `streetcar.reliability.updated`
- `history.export.ready`

## Metering

Stripe meter units:

- `api_request`
- `sse_connection_minute`
- `sse_event`
- `webhook_event`
- `bulk_export`

The intended production request path writes local usage ledger records. A batch job reports aggregate usage to Stripe.

## Current Plans

These limits are a snapshot. Read `GET /api/v1/billing/plans` for the effective
catalogue.

Free:

- REST: 20 requests/5 minutes, 300/day.
- SSE output: unavailable.
- Webhooks: unavailable.
- API keys: 1.
- Max query `limit=20`.
- History exports: unavailable.

Regular:

- REST: 600 requests/5 minutes, 50,000/day.
- SSE output: 2 concurrent connections.
- Webhooks: 5 endpoints.
- API keys: 5.
- Max query `limit=100`.
- History exports: unavailable.

Max:

- REST: 6,000 requests/5 minutes, 1,000,000/day.
- SSE output: 25 concurrent connections.
- Webhooks: 25 endpoints.
- API keys: 25.
- Max query `limit=1,000`.
- History exports: enabled.

## API Value Add

Public API responses should expose ATL Transit Live enriched data, not only raw MARTA records:

- Generated delay alerts.
- Rail line and station delay summaries.
- Average and maximum delay times.
- Major-delay counts.
- Incident state and throttled alert state.
- Cursor pagination metadata.

## Source Alert Structures

LLM-structured service alerts use JSON schema fields that API consumers should treat as arrays:

- `impact_type`: one or more impact labels, such as `cancellation`, `delay`, or `single_tracking`.
- `affected_ids`: source entity IDs such as bus routes, rail lines, stations, or services.
- `microblog_message`: one or more short display-safe message segments.

The public API normalizes these into `impact.impact_types`, `affected.affected_ids`, and `message.microblog_messages`.

## Data Sources

- MARTA static GTFS.
- MARTA GTFS realtime bus vehicle and trip updates.
- MARTA rail realtime arrivals API.
- MARTA service alert emails processed into structured data.

## Storage

- Hot realtime observations and generated alerts live in PostgreSQL.
- Older rail realtime history and incident rollups should be swept into Parquet files on R2.
- Bulk export APIs should expose manifests rather than repeatedly regenerating the same export.