A simple and easy way to parse data from Amtrak's train tracking API.
This library and its creator have no relation to Amtrak. Amtrak and the Amtrak
Logo are trademarks of The National Railroad Passenger Corporation (NRPC). The
API endpoint used is originally intended for with
Amtrak's Train Tracking map.
Any version below 3.0.0 WILL NO LONGER WORK due to:
- Amtrak blocking all requests from any Node.js REST client, or at least the
ones that I have tried.
- The deprecation of the Amtraker v1 and v2 APIs.
While v3 code syntax is the same, the resulting types are different, please
check the docs section for more information.
Using NPM:
npm install amtrak
Using Yarn:
yarn add amtrak
Using PNPM:
pnpm add amtrak
Not complete, check back later.
The Amtraker oEmbed endpoint is https://api.amtraker.com/v3/oembed, following the standard oEmbed Spec.
Amtrak.js has a pretty basic schema with 4 different functions:
- fetchAllTrains(): Fetches all active Amtrak trains.
- fetchTrain(trainId: string): Fetches a train by its number or ID.
- fetchAllStations(): Fetches metadata for all Amtrak stations.
- fetchStation(stationId: string): Fetches metadata for a station by its ID.
- Fetches all active Amtrak trains.
- Returns Promise where each key is a train number and the
value is a list of Train objects.
- Associated endpoint: https://api-v3.amtraker.com/v3/trains
#### Example
``ts
const { fetchAllTrains } = require("amtrak"); // CommonJS
import { fetchAllTrains } from "amtrak"; // ES6
// JS
fetchAllTrains().then((trains) => {
console.log(trains);
});
// TS
fetchAllTrains().then((trains: TrainResponse) => {
console.log(trains);
});
`
- Fetches a train by its number or ID.
- Returns Promise with a single key (the train number) and theTrain
value is a list of objects.5-9
- If a valid Train ID is provided, the value will be a list of length 1.
- If the train number/ID is not found, the promise will resolve with an empty
array.
- A train ID is comprised of the train number and the day of the month the train
originated.
- For example, a California Zephyr train (train #5) that originated on
02/09/2023 would have an ID of ;https://api-v3.amtraker.com/v3/trains/:trainId
- Associated endpoint:
#### Example
`ts
const { fetchTrain } = require("amtrak"); // CommonJS
import { fetchTrain } from "amtrak"; // ES6
// JS
fetchTrain("5-9").then((train) => {
console.log(train);
});
// TS
fetchTrain("5-9").then((train: TrainResponse) => {
console.log(train);
});
`
- Fetches metadata for all Amtrak stations.
- Returns Promise where each key is a station ID and theStationMeta
value is a object.https://api-v3.amtraker.com/v3/stations
- Associated endpoint:
#### Example
`ts
const { fetchAllStations } = require("amtrak"); // CommonJS
import { fetchAllStations } from "amtrak"; // ES6
// JS
fetchAllStations().then((stations) => {
console.log(stations);
});
// TS
fetchAllStations().then((stations: StationResponse) => {
console.log(stations);
});
`
- Fetches metadata for a station by its ID.
- Returns Promise with a single key (the station ID) and theStationMeta
value is a object.https://api-v3.amtraker.com/v3/stations/:stationId
- If the station ID is not found, the promise will resolve with an empty object.
- Associated endpoint:
#### Example
`ts
const { fetchStation } = require("amtrak"); // CommonJS
import { fetchStation } from "amtrak"; // ES6
// JS
fetchStation("CHI").then((station) => {
console.log(station);
});
// TS
fetchStation("CHI").then((station: StationResponse) => {
console.log(station);
});
`
- Fetches info on the state of the Amtraker API.
- Returns Promise.https://api-v3.amtraker.com/v3/stale
- Associated endpoint:
#### Example
`ts
const { fetchStaleStatus } = require("amtrak"); // CommonJS
import { fetchStaleStatus } from "amtrak"; // ES6
// JS
fetchStaleStatus().then((status) => {
console.log(status);
});
// TS
fetchStaleStatus().then((status: StaleStatusResponse) => {
console.log(status);
});
`
There are a handful of types that are used throughout the library. Below is a
list:
`tsprovider
interface Train {
routeName: string; // Name of the train route
trainNum: string; // Train number
trainNumRaw: string; // Train number, minus any prefix (ie v for via rail and b for brightline)
trainID: string; // Train ID
lat: number; // Latitude of the train
lon: number; // Longitude of the train
trainTimely: string; // Deprecated
iconColor: string; // Calculated icon color for the frontend
stations: Station[]; // List of stations the train has and will pass through
heading: string; // Direction the train is heading in the 8 cardinal directions
eventCode: string; // Upcoming/current station
eventTZ: string; // Timezone of the upcoming/current station
eventName: string; // Name of the upcoming/current station
origCode: string; // Origin station code
originTZ: string; // Timezone of the origin station
origName: string; // Name of the origin station
destCode: string; // Destination station code
destTZ: string; // Timezone of the destination station
destName: string; // Name of the destination station
trainState: string; // Either "Predeparture" or "Active"
velocity: number; // Speed of the train in MPH
statusMsg: string; // Status message associated with the train, if any
createdAt: string; // Timestamp of when the train data was stored in Amtrak's DB
updatedAt: string; // Timestamp of when the train data was last updated
lastValTS: string; // Timestamp of when the train data was last received
objectID: number; // ID of the train data in Amtrak's DB
provider: string; // The provider of this train, either "Amtrak", "Via", or "Brightline"
providerShort: string; // A shortened version of , 4 or less characters, either "AMTK", "VIA", or "BLNE"`
onlyOfTrainNum: boolean; // If this is the only train with its number (IE if there is only a single 3 active)
alerts: TrainAlert[]; // Array of alerts
}
ts
export interface TrainAlert {
message: string;
}
`$3
ts
interface Station {
name: string; // Name of the station in plain english
code: string; // Station code
tz: string; // Timezone of the station
bus: boolean; // Whether or not the station is a bus stop
schArr: string; // Scheduled arrival time
schDep: string; // Scheduled departure time
arr: string; // Actual arrival time
dep: string; // Actual departure time
arrCmnt: string; // Deprecated
depCmnt: string; // Deprecated
platform: string; // Platform name/number, if available
status: string; // One of "Enroute", "Station", "Departed", or "Unknown"
}
`$3
ts
interface StationMeta {
name: string; // Name of the station in plain english
code: string; // Station code
tz: string; // Timezone of the station
lat: number; // Latitude of the station
lon: number; // Longitude of the station
hasAddress: boolean; // Whether or not the station has address data. Usually true for Amtrak, usually false for Via Rail.
address1: string; // Address line 1 of the station
address2: string; // Address line 2 of the station, usually empty
city: string; // City of the station
state: string; // State of the station
zip: number; // Zip code of the station
trains: string[]; // List of train IDs that pass through the station
}
`$3
ts
interface TrainResponse {
[key: string]: Train[];
}
`$3
ts
interface StationResponse {
[key: string]: StationMeta;
}
`$3
ts
interface StaleData {
avgLastUpdate: number; // Average time in milliseconds since train data was last updated in Amtrak's database
activeTrains: number; // Number of trains that are currently active
stale: boolean; // Whether or not the data is stale
}
`Endpoints
As mentioned above in the Functions section, each function is
associated with an endpoint. Below is a list of all endpoints used by the
library, where the associated function returns the same data as the endpoint,
allowing you to use the library with your own HTTP client.
-
- Associted with
-
- Associted with
-
- Associted with
-
- Associted with
-
- Associted with