MTA GTFS Wrapper API

A developer-friendly Go API for NYC MTA subway real-time data

About

The MTA API returns all of their data in GTFS format, making it difficult to work with as a developer. This wrapper API simplifies the MTA real-time data by providing clean, developer-friendly endpoints that separate the 36 subway lines and present data in an easy-to-consume JSON format.

Note: The arrival time window is configurable in config/constants.go and is currently set to 20 minutes.

Getting Started

Prerequisites

Installation

# Clone the repository
git clone https://github.com/conniexu444/mta-wrapper.git
cd mta-wrapper

# Download dependencies
go mod tidy

# Run the server
go run main.go

The server will start on http://localhost:8080

Configuration

You can modify the arrival time window by editing config/constants.go:

const ArrivalWindowMinutes = 20  // Change this value as needed

API Endpoints

GET/feed

Returns the entire GTFS feed data in JSON format for a specific subway line.

Parameter Type Required Description
route string Yes Subway line identifier (e.g., A, B, C, 1, 2, 3, L, etc.)
Example:
GET /feed?route=B
Returns all feed data for the B train.

GET/arrivals

Returns upcoming train arrivals with various filtering options.

Parameter Type Required Description
route string Yes Subway line (e.g., L, A, 1) or "ALL" for all lines
station string No Station name (kebab-case, e.g., bedford-av, times-sq-42-st)
direction string No Travel direction: "N" (Northbound) or "S" (Southbound)

Use Cases

1. All arrivals for a route

GET /arrivals?route=L
Returns all L train arrivals in both directions within the next 20 minutes.

2. Arrivals at a specific station

GET /arrivals?route=L&station=bedford-av
Returns all L train arrivals at Bedford Avenue station.

3. All trains at a station (any line)

GET /arrivals?route=ALL&station=times-sq-42-st
Returns all trains stopping at Times Square-42nd Street within the next 20 minutes.

4. Directional filtering

GET /arrivals?route=L&station=bedford-av&direction=N
Returns only northbound L trains at Bedford Avenue.
GET /arrivals?route=ALL&direction=S
Returns all southbound trains across all lines.
GET /arrivals?route=A&direction=N
Returns all northbound A trains.
Fuzzy Station Matching: If you misspell a station name, the API will suggest corrections using Levenshtein distance matching. 
# Request with typo:
GET /arrivals?route=L&station=times-sq-42

# Response:
{
  "error": "unknown station: times-sq-42",
  "did_you_mean": ["times-sq-42-st"]
}

Example Responses

Arrivals Response

[
  {
    "Route": "L",
    "StopID": "L06N",
    "TripID": "123456",
    "Time": "2025-10-01T14:32:00Z"
  },
  {
    "Route": "L",
    "StopID": "L06N",
    "TripID": "123457",
    "Time": "2025-10-01T14:45:00Z"
  }
]

Error Response with Suggestions

{
  "error": "unknown station: bedfor",
  "did_you_mean": [
    "bedford-av",
    "bedford-park-blvd",
    "bedford-park-blvd-lehman-coll"
  ]
}