mta.subway.direction() — resolve a destination to a direction

GET

https://www.mtaapi.dev

api

subway

direction

Resolve subway direction from an intermediate destination

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.mtaapi.dev/api/v1/subway/direction', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "route": {
    "id": "<string>",
    "shortName": "<string>",
    "longName": "<string>",
    "type": 123,
    "color": "<string>",
    "textColor": "<string>"
  },
  "destination": "<string>",
  "normalizedDestination": "<string>",
  "resolved": true,
  "displayDirection": "<string>",
  "terminal": "<string>",
  "fromStop": {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "parentId": "<string>"
  },
  "destinationStop": {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "parentId": "<string>"
  },
  "matches": [
    {
      "id": "<string>",
      "name": "<string>",
      "displayName": "<string>",
      "lat": 123,
      "lon": 123,
      "parentId": "<string>"
    }
  ],
  "reason": "<string>"
}

The mta.subway.direction method resolves a rider-facing destination string (such as "Union Sq") into a typed direction of travel, the terminal the train heads toward, and a ready-to-display label. Use it when a rider tells you where they want to go and you need to translate that into the north / south direction the realtime feed uses — for example, to pre-select the correct direction in an arrivals UI. This method requires a hosted API key. It resolves destinations against the hosted API’s static GTFS route order and is not available in direct-feed mode.

`mta.subway.direction(params)`

Parameters

route

string

required

The subway route the rider is traveling on (for example, 'L').

fromStopId

string

required

The stop ID the rider is departing from (for example, 'L08' for Bedford Av).

destination

string

required

A rider-facing destination string to resolve against the route’s stop order (for example, 'Union Sq'). Matching tolerates casing and common station-name variations.

TypeScript signature

interface SubwayDirectionQuery {
  route: SubwayRoute
  fromStopId: SubwayStopId
  destination: string
}

// Subway feed directions are always north/south, even on east-west lines
type SubwayResolvedDirection = 'north' | 'south'

interface SubwayDirectionResolution {
  route: Route
  destination: string             // the string you passed in
  normalizedDestination: string   // cleaned form used for matching
  resolved: boolean               // whether a direction was determined
  direction?: SubwayResolvedDirection
  displayDirection?: string       // e.g. "toward 8 Av"
  terminal?: string               // terminal station the train heads toward
  fromStop?: Stop
  destinationStop?: Stop
  matches?: Stop[]                // candidate stops when the match is ambiguous
  reason?: string                 // why resolution failed, when resolved is false
}

mta.subway.direction(params: SubwayDirectionQuery): Promise<SubwayDirectionResolution>

The method always resolves to a SubwayDirectionResolution object — it does not return null. Branch on resolved: when true, direction, displayDirection, terminal, and destinationStop are populated; when false, reason explains why, and matches may list ambiguous candidates.

Response fields

route

Route

required

The resolved route object: id, plus optional shortName, longName, color, textColor, and type.

destination

string

required

The destination string exactly as passed in.

normalizedDestination

string

required

The cleaned/normalized form of the destination used for matching.

resolved

boolean

required

Whether a direction was successfully determined. When false, inspect reason and matches.

direction

string

The resolved feed direction: 'north' or 'south'. Present when resolved is true.

displayDirection

string

A human-readable label such as "toward 8 Av". Present when resolved is true.

terminal

string

The name of the terminal station the train heads toward in the resolved direction.

fromStop

Stop

The resolved origin stop object for fromStopId.

destinationStop

Stop

The resolved destination stop object that matched destination.

matches

Stop[]

Candidate stops when the destination is ambiguous and could not be narrowed to a single stop.

reason

string

A short explanation of why resolution failed. Present when resolved is false.

Code example

import { MTA } from 'mta-js'

const mta = new MTA({ apiKey: process.env.MTA_API_KEY })

// A rider at Bedford Av (L08) wants to reach Union Sq — which way do they go?
const resolution = await mta.subway.direction({
  route: 'L',
  fromStopId: 'L08',
  destination: 'Union Sq',
})

if (resolution.resolved) {
  console.log(resolution.direction)         // "north"
  console.log(resolution.displayDirection)  // "toward 8 Av"
  console.log(resolution.terminal)          // "8 Av"

  // Feed the resolved direction straight into arrivals
  const arrivals = await mta.subway.arrivals({
    stopId: 'L08',
    route: 'L',
    direction: resolution.direction,
  })
  console.log(arrivals)
} else {
  console.warn(`Couldn't resolve a direction: ${resolution.reason}`)
}

Example response

{
  "route": { "id": "L", "shortName": "L", "color": "#A7A9AC" },
  "destination": "Union Sq",
  "normalizedDestination": "union sq",
  "resolved": true,
  "direction": "north",
  "displayDirection": "toward 8 Av",
  "terminal": "8 Av",
  "fromStop": { "id": "L08", "name": "Bedford Av" },
  "destinationStop": { "id": "L02", "name": "14 St-Union Sq" }
}

NYC Subway realtime feeds use NYCT’s north / south stop directions, even on east-west lines like the L. mta.subway.direction always resolves to one of those two feed directions, and mta.subway.arrivals accepts the same direction value — along with the rider-facing east / west and uptown / downtown aliases.

This method is only available with a hosted apiKey. It calls the hosted endpoint and resolves against the managed static GTFS snapshot; it is not available in direct-feed mode.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

route

string

required

Minimum string length: 1

fromStopId

string

required

Minimum string length: 1

destination

string

required

Minimum string length: 1

Response

200 - application/json

Response for status 200

route

object

required

Hide child attributes

route.id

string

required

route.shortName

string

route.longName

string

route.type

number

route.color

string

route.textColor

string

destination

string

required

normalizedDestination

string

required

resolved

boolean

required

direction

enum<string>

Available options:

north,

south

displayDirection

string

terminal

string

fromStop

object

Hide child attributes

fromStop.id

string

required

fromStop.name

string

required

fromStop.displayName

string

fromStop.lat

number

fromStop.lon

number

fromStop.mode

enum<string>

Available options:

subway,

bus

fromStop.parentId

string

destinationStop

object

Hide child attributes

destinationStop.id

string

required

destinationStop.name

string

required

destinationStop.displayName

string

destinationStop.lat

number

destinationStop.lon

number

destinationStop.mode

enum<string>

Available options:

subway,

bus

destinationStop.parentId

string

matches

object[]

Hide child attributes

matches.id

string

required

matches.name

string

required

matches.displayName

string

matches.lat

number

matches.lon

number

matches.mode

enum<string>

Available options:

subway,

bus

matches.parentId

string

reason

string

BusReference for mta.bus in mta-js. Retrieve live bus vehicle positions, GPS coordinates, heading, next stop, and occupancy for any MTA route.

⌘I

Resolve subway direction from an intermediate destination

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.mtaapi.dev/api/v1/subway/direction', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "route": {
    "id": "<string>",
    "shortName": "<string>",
    "longName": "<string>",
    "type": 123,
    "color": "<string>",
    "textColor": "<string>"
  },
  "destination": "<string>",
  "normalizedDestination": "<string>",
  "resolved": true,
  "displayDirection": "<string>",
  "terminal": "<string>",
  "fromStop": {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "parentId": "<string>"
  },
  "destinationStop": {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "parentId": "<string>"
  },
  "matches": [
    {
      "id": "<string>",
      "name": "<string>",
      "displayName": "<string>",
      "lat": 123,
      "lon": 123,
      "parentId": "<string>"
    }
  ],
  "reason": "<string>"
}

Documentation Index

​mta.subway.direction(params)

​Parameters

​TypeScript signature

​Response fields

​Code example

​Example response

Authorizations

Query Parameters

Response

`mta.subway.direction(params)`

Parameters

TypeScript signature

Response fields

Code example

Example response