> ## Documentation Index
> Fetch the complete documentation index at: https://mtaapi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# mta.subway.direction() — resolve a destination to a direction
> Reference for mta.subway.direction in mta-js. Resolve a rider-facing destination string into a typed north/south direction, terminal, and display label.
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
The subway route the rider is traveling on (for example, `'L'`).
The stop ID the rider is departing from (for example, `'L08'` for Bedford Av).
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
```typescript theme={null}
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
```
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
The resolved route object: `id`, plus optional `shortName`, `longName`, `color`, `textColor`, and `type`.
The destination string exactly as passed in.
The cleaned/normalized form of the destination used for matching.
Whether a direction was successfully determined. When `false`, inspect `reason` and `matches`.
The resolved feed direction: `'north'` or `'south'`. Present when `resolved` is `true`.
A human-readable label such as `"toward 8 Av"`. Present when `resolved` is `true`.
The name of the terminal station the train heads toward in the resolved direction.
The resolved origin stop object for `fromStopId`.
The resolved destination stop object that matched `destination`.
Candidate stops when the destination is ambiguous and could not be narrowed to a single stop.
A short explanation of why resolution failed. Present when `resolved` is `false`.
### Code example
```typescript theme={null}
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
```json theme={null}
{
"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`](/api-reference/subway) 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.
## OpenAPI
````yaml GET /api/v1/subway/direction
openapi: 3.0.3
info:
title: MTA API
description: Managed, API-key protected access to MTA realtime and static data.
version: 0.1.0
servers:
- url: https://www.mtaapi.dev
description: Production
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: subway
description: Subway realtime data
- name: bus
description: BusTime realtime data
- name: alerts
description: Service alerts
- name: stops
description: Route-aware static GTFS stop lookup
- name: system
description: Health and database status
paths:
/api/v1/subway/direction:
get:
tags:
- subway
summary: Resolve subway direction from an intermediate destination
description: >-
Resolve rider-entered destination text such as Union Sq into a subway
direction using ordered static GTFS stop data.
operationId: getApiV1SubwayDirection
parameters:
- name: route
in: query
required: true
schema:
minLength: 1
type: string
- name: fromStopId
in: query
required: true
schema:
minLength: 1
type: string
- name: destination
in: query
required: true
schema:
minLength: 1
type: string
responses:
'200':
description: Response for status 200
content:
application/json:
schema:
type: object
required:
- route
- destination
- normalizedDestination
- resolved
properties:
route:
type: object
required:
- id
properties:
id:
type: string
shortName:
type: string
longName:
type: string
type:
type: number
color:
type: string
textColor:
type: string
destination:
type: string
normalizedDestination:
type: string
resolved:
type: boolean
direction:
type: string
enum:
- north
- south
displayDirection:
type: string
terminal:
type: string
fromStop:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
displayName:
type: string
lat:
type: number
lon:
type: number
mode:
enum:
- subway
- bus
type: string
parentId:
type: string
destinationStop:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
displayName:
type: string
lat:
type: number
lon:
type: number
mode:
enum:
- subway
- bus
type: string
parentId:
type: string
matches:
type: array
items:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
displayName:
type: string
lat:
type: number
lon:
type: number
mode:
enum:
- subway
- bus
type: string
parentId:
type: string
reason:
type: string
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````