mta.stops.near() — find stops by geolocation

GET

https://www.mtaapi.dev

api

stops

near

Find route-aware nearby stops

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

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

[
  {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "distanceMeters": 123,
    "parentId": "<string>",
    "servedRoutes": [
      {
        "id": "<string>",
        "shortName": "<string>",
        "longName": "<string>",
        "type": 123,
        "color": "<string>",
        "textColor": "<string>",
        "headsigns": [
          "<string>"
        ],
        "directionHeadsigns": {},
        "directions": [
          123
        ]
      }
    ],
    "routeMatch": true,
    "routeHeadsigns": [
      "<string>"
    ],
    "directionHeadsigns": {}
  }
]

The mta.stops namespace lets you discover MTA stops near any point on the map. Use mta.stops.near to find subway stations, bus stops, or both, sorted by distance from a given latitude and longitude. You can also pass a route to return only stops served by that route — for example, only L train stops or only M23 SBS bus stops within walking distance. This is the recommended starting point when you need stop IDs for use with mta.subway.arrivals or mta.bus.arrivals, or to power a “stops near me” feature in your application.

`mta.stops.near(params)`

Returns a list of MTA stops within a configurable radius of the provided coordinates, sorted by distance ascending. You can limit results to subway stops, bus stops, or both by passing the modes parameter, and further filter to stops served by a specific route.

Parameters

lat

number

required

The latitude of the center point for the search, in decimal degrees (WGS 84). For example, 40.7128 for lower Manhattan.

lon

number

required

The longitude of the center point for the search, in decimal degrees (WGS 84). For example, -74.0060 for lower Manhattan.

modes

string[]

An array of transit modes to include in the results. Accepted values are 'subway' and 'bus'. Pass ['subway'] to return only subway stations, ['bus'] to return only bus stops, or ['subway', 'bus'] to return both. Defaults to both modes if omitted.

route

string

Optional route filter. When supplied, only stops served by this route are returned. For example, 'L' returns nearby stops served by the L train, and 'M23' returns nearby M23 SBS bus stops. Route IDs are case-sensitive and match MTA’s published identifiers.

includeRoutes

boolean

When true, each returned stop includes route metadata: a servedRoutes array of ServedRoute objects and a directionHeadsigns map. Defaults to false to keep responses small when you only need stop identity and distance.

radiusMeters

number

Search radius in meters. Defaults to 500. Increase this when querying sparse areas or to widen a “stops near me” view.

limit

number

Maximum number of stops to return. Must be between 1 and 100. Results remain sorted by distance ascending.

TypeScript signature

type TransitMode = 'subway' | 'bus' | 'lirr' | 'metro-north'

interface StopsNearParams {
  lat: number
  lon: number
  modes?: TransitMode[]
  route?: string
  includeRoutes?: boolean
  radiusMeters?: number
  limit?: number
}

interface Stop {
  id: string
  name: string
  displayName?: string     // human-friendly label (may differ from GTFS name)
  lat?: number
  lon?: number
  parentStation?: string   // GTFS parent_station ID
  parentId?: string        // resolved parent station ID
  mode?: TransitMode
}

interface Route {
  id: string
  shortName?: string
  longName?: string
  color?: string
  textColor?: string
  type?: number
}

// Headsigns keyed by direction, e.g. { "north": ["8 Av"], "south": ["Canarsie"] }
type DirectionHeadsigns = Record<string, string[]>

// A route serving a stop — a Route plus headsign/direction metadata
type ServedRoute = Route & {
  headsigns?: string[]
  directionHeadsigns?: DirectionHeadsigns
  directions?: number[]
}

type NearbyStop = Stop & {
  distanceMeters?: number
  servedRoutes?: ServedRoute[]          // requires includeRoutes: true
  routeMatch?: boolean                  // true when the stop matches the `route` filter
  routeHeadsigns?: string[]             // headsigns for the filtered route
  directionHeadsigns?: DirectionHeadsigns
  note?: string
}

mta.stops.near(params: StopsNearParams): Promise<NearbyStop[]>

Response fields

stops

NearbyStop[]

required

An array of nearby stops, sorted by distanceMeters ascending. Returns an empty array if no stops are found within the search radius.

Show NearbyStop properties

string

required

The MTA stop ID. Use this as the stopId parameter in mta.subway.arrivals.

name

string

required

The GTFS stop name (e.g. 'Jay St-MetroTech').

displayName

string

A human-friendly display label that may differ slightly from the raw GTFS name (e.g. 'Jay St–MetroTech').

parentStation

string

The GTFS parent_station ID, when the stop is a child platform of a larger station.

parentId

string

The resolved parent station ID. Use this to group platform-level stops under the same station.

lat

number

required

The latitude of the stop in decimal degrees (WGS 84).

lon

number

required

The longitude of the stop in decimal degrees (WGS 84).

mode

string

required

The transit mode: 'subway' or 'bus'.

distanceMeters

number

Straight-line distance from the queried coordinates to this stop, in meters. Always present on results from mta.stops.near.

servedRoutes

ServedRoute[]

Routes serving this stop. Each is a Route (id, shortName, longName, color, textColor, type) extended with optional headsigns, directionHeadsigns, and directions. Only included when includeRoutes: true is passed.

routeMatch

boolean

When a route filter was supplied, indicates whether this stop is served by that route.

routeHeadsigns

string[]

Headsigns for the filtered route at this stop, when a route filter was supplied.

directionHeadsigns

DirectionHeadsigns

A Record<string, string[]> mapping each direction to its headsigns (e.g. { "north": ["8 Av"], "south": ["Canarsie"] }). Useful for building direction-picker UIs. Only included when includeRoutes: true is passed.

note

string

An optional advisory note about the stop.

Code example

import { MTA } from 'mta-js'

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

// Find subway stops near Prospect Park in Brooklyn
const stops = await mta.stops.near({
  lat: 40.6602,
  lon: -73.9690,
  modes: ['subway'],
  includeRoutes: true,
})

for (const stop of stops) {
  const distance = Math.round(stop.distanceMeters)
  const routes = stop.servedRoutes?.map((r) => r.shortName).join(', ') ?? ''
  console.log(`${stop.displayName ?? stop.name} (${stop.id}) — ${distance}m away — routes: ${routes}`)
}

Example response

[
  {
    "id": "F21",
    "name": "Prospect Park",
    "displayName": "Prospect Park",
    "lat": 40.6612,
    "lon": -73.9622,
    "mode": "subway",
    "distanceMeters": 612,
    "servedRoutes": [
      {
        "id": "F",
        "shortName": "F",
        "color": "#FF6319",
        "directionHeadsigns": {
          "north": ["Jamaica-179 St"],
          "south": ["Coney Island-Stillwell Av"]
        }
      },
      {
        "id": "G",
        "shortName": "G",
        "color": "#6CBE45",
        "directionHeadsigns": {
          "north": ["Court Sq"],
          "south": ["Church Av"]
        }
      }
    ]
  },
  {
    "id": "D24",
    "name": "Parkside Av",
    "displayName": "Parkside Av",
    "lat": 40.6554,
    "lon": -73.9614,
    "mode": "subway",
    "distanceMeters": 870,
    "servedRoutes": [
      { "id": "B", "shortName": "B", "color": "#FF6319" },
      { "id": "Q", "shortName": "Q", "color": "#FCCC0A" }
    ]
  }
]

Route-aware example

Filter to nearby stops served by a specific route. This is useful when you want to find the closest stop on the M23 SBS or the nearest L train station without sorting through every nearby stop yourself.

import { MTA } from 'mta-js'

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

// Find nearby M23 SBS bus stops within 800m, with route metadata
const stops = await mta.stops.near({
  lat: 40.7356,
  lon: -73.9804,
  modes: ['bus'],
  route: 'M23',
  includeRoutes: true,
  radiusMeters: 800,
  limit: 5,
})

for (const stop of stops) {
  const routes = stop.servedRoutes?.map((r) => r.shortName).join(', ') ?? ''
  console.log(`${stop.displayName ?? stop.name} — ${Math.round(stop.distanceMeters)}m — ${routes}`)
}

Pass the id from a result directly into mta.subway.arrivals or mta.bus.arrivals to build a two-step “find stops near me, then show arrivals” flow without any additional configuration.

Authorizations

Authorization

string

header

required

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

Query Parameters

lat

number

required

Required range: -90 <= x <= 90

lon

number

required

Required range: -180 <= x <= 180

modes

string

Comma-separated transit modes to search, such as subway,bus.

route

string

Optional route filter. For example, L returns nearby stops served by the L train, and M23 returns nearby M23 SBS bus stops.

Minimum string length: 1

includeRoutes

boolean

Include route metadata for each returned stop.

radiusMeters

number

Search radius in meters. Defaults to 500.

Required range: x >= 1

limit

number

Required range: 1 <= x <= 100

Response

200 - application/json

Response for status 200

string

required

name

string

required

displayName

string

required

lat

number

required

lon

number

required

distanceMeters

number

required

mode

enum<string>

Available options:

subway,

bus

parentId

string

servedRoutes

object[]

Hide child attributes

servedRoutes.id

string

required

servedRoutes.shortName

string

servedRoutes.longName

string

servedRoutes.type

number

servedRoutes.color

string

servedRoutes.textColor

string

servedRoutes.headsigns

string[]

servedRoutes.directionHeadsigns

object

Hide child attributes

servedRoutes.directionHeadsigns.{key}

string[]

servedRoutes.directions

number[]

routeMatch

boolean

routeHeadsigns

string[]

directionHeadsigns

object

Hide child attributes

directionHeadsigns.{key}

string[]

Subway Arrival BoardReference for GET /api/v1/subway/arrival-board. Find nearby subway stations and group their upcoming arrivals by direction in a single request.

⌘I

Find route-aware nearby stops

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

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

[
  {
    "id": "<string>",
    "name": "<string>",
    "displayName": "<string>",
    "lat": 123,
    "lon": 123,
    "distanceMeters": 123,
    "parentId": "<string>",
    "servedRoutes": [
      {
        "id": "<string>",
        "shortName": "<string>",
        "longName": "<string>",
        "type": 123,
        "color": "<string>",
        "textColor": "<string>",
        "headsigns": [
          "<string>"
        ],
        "directionHeadsigns": {},
        "directions": [
          123
        ]
      }
    ],
    "routeMatch": true,
    "routeHeadsigns": [
      "<string>"
    ],
    "directionHeadsigns": {}
  }
]

Documentation Index

​mta.stops.near(params)

​Parameters

​TypeScript signature

​Response fields

​Code example

​Example response

​Route-aware example

Authorizations

Query Parameters

Response

`mta.stops.near(params)`

Parameters

TypeScript signature

Response fields

Code example

Example response

Route-aware example