Skip to main content

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-js uses an API key from mtaapi.dev — the hosted version of this SDK — to authenticate every data request. You pass the key once when you create the MTA client, and the SDK handles the rest automatically. This page explains how to get a key, store it safely, and troubleshoot authentication failures.
Never hardcode your API key directly in source code. If you commit a key to a public repository, anyone can use it to make requests on your behalf. Always load keys from environment variables.

​
Get your API key

API keys are free and issued through mtaapi.dev. Using the hosted API is the fastest and easiest way to use mta-js — no MTA developer registration, no BusTime key, no GTFS imports.
  1. Go to mtaapi.dev and sign up for a free account.
  2. Copy your API key from the dashboard.
Your key is a long alphanumeric string. Keep it somewhere safe — you’ll add it to your environment in the next step.
Prefer to self-host and call MTA feeds directly? See Direct MTA feeds on the Quick Start page. The rest of this page assumes you’re using the hosted mtaapi.dev API.

​
Configure your environment

Store your API key as an environment variable so it stays out of your source code. Add the following line to a .env file at the root of your project:
.env
MTA_API_KEY=your_api_key_here
Then make sure .env is listed in your .gitignore:
.gitignore
.env
Most JavaScript frameworks (Next.js, Remix, Astro) and runtimes load .env files automatically. For plain Node.js projects, install dotenv and call require('dotenv').config() at the top of your entry file, or use the --env-file flag available in Node.js 20+.

​
Initialize the client

Pass your API key to the MTA constructor as apiKey. With an apiKey set, requests are routed to https://www.mtaapi.dev/api/v1 automatically. 
import { MTA } from 'mta-js'

const mta = new MTA({ apiKey: process.env.MTA_API_KEY })
Create one client instance and reuse it across your application. Instantiating multiple clients is unnecessary and won’t improve performance. If you’re working in a serverless environment (Vercel Functions, Cloudflare Workers, AWS Lambda), initialize the client inside the request handler to ensure your environment variables are available at invocation time: 
import { MTA } from 'mta-js'

export async function GET(request: Request) {
  const mta = new MTA({ apiKey: process.env.MTA_API_KEY })
  const arrivals = await mta.subway.arrivals({ stopId: 'A27', route: 'A' })
  return Response.json(arrivals)
}

​
Authentication errors

If your API key is missing, incorrect, or expired, the API returns an HTTP error and mta-js surfaces it as a thrown error.
Status codeMeaning
401 UnauthorizedThe API key was not provided or is malformed. Check that MTA_API_KEY is set in your environment and that you’re passing it correctly to the constructor.
403 ForbiddenThe API key is recognized but not authorized to access the requested resource. Your key may have expired or been revoked.
Troubleshooting steps:
  1. Confirm the environment variable is set by logging process.env.MTA_API_KEY before initializing the client. It should not be undefined.
  2. Double-check that the key you copied from mtaapi.dev does not have leading or trailing whitespace.
  3. If you recently regenerated your key, update it in every environment where it’s used (local .env, hosting platform secrets, CI/CD variables).
  4. If the problem persists, log in to mtaapi.dev to verify your key is still active.