@simrail-sdk/api NPM

SimRail API SDK

This is a simple SDK (community edition) for interacting with the SimRail APIs.

This API module builds a layer on top of a Core API module (like @simrail-sdk/api-core-node) by providing:

Methods to request single resources. (A single server, station or train)
Automatic pulling of remote data updates.
Update event subcriptions.
Caching of remote API responses.

This API module is only about interacting with SimRail's remote APIs. If you are looking for a more developer-friendly SDK, checkout:

@simrail-sdk/core for an SDK consuming only live data.
@simrail-sdk/sdk for an SDK providing extended data about the game. (upcoming)

This module requires the use of a Core API module to be able to extend it. By default this module will use @simrail-sdk/api-core-node. To provide another Core API module or a custom one, check out the example providing a (custom) Core API class below.

Content index

Usage details
- Installation
- Examples
API reference

About this module

- [Module dependencies][module-dependencies]

    - [Module package dependencies][module-package-dependencies]

    - [Internal module dependencies][internal-module-dependencies]

- [Module code statistics][module-code-statistics]

Usage details

Installation

Using NPM:

$ npm i @simrail-sdk/api

$ npm i github:simrail-sdk/api#VERSION

Where VERSION specifies the version to install.

Examples

Simple API usage

import Api from "@simrail-sdk/api";

const api = new Api({
    endpoints: {
        liveData: "https://panel.simrail.eu:8084",
        timetable: "https://api1.aws.simrail.eu:8082/api",
    },
});
const serverCode: Api.ServerCode = "en1";

api.getActiveServers().then(...);
api.getActiveServer(serverCode).then(...);
// {
//     id: "638fec40d089346098624eb5",
//     isActive: true,
//     serverCode: "en1",
//     serverName: "EN1 (English)",
//     serverRegion: "Europe",
// },

api.getActiveStations(serverCode).then(...);
api.getActiveStation(serverCode, "KO").then(...);
// {
//     additionalImage1URL: "https://api.simrail.eu:8083/Thumbnails/Stations/ko2.jpg",
//     additionalImage2URL: "https://api.simrail.eu:8083/Thumbnails/Stations/ko3.jpg",
//     difficultyLevel: 5,
//     dispatchedBy: [],
//     id: "644133f3858f72cc3d476e42",
//     latitude: 50.25686264038086,
//     longitude: 19.01921844482422,
//     mainImageURL: "https://api.simrail.eu:8083/Thumbnails/Stations/ko1m.jpg",
//     name: "Katowice",
//     prefix: "KO"
// },

api.getActiveTrains(serverCode).then(...);
api.getActiveTrain(serverCode, "446004").then(...);
// {
//     endStation: "Częstochowa",
//     id: "662f96b3766d379b4f3f525f",
//     runId: "73c0f0ea-20d9-4317-8339-8bc7d098bd35",
//     serverCode: "en1",
//     startStation: "Jaworzno Szczakowa",
//     trainData: {
//     inBorderStationArea: true,
//     latitude: 50.262142181396484,
//     longitude: 19.269641876220703,
//     vdDelayedTimetableIndex: 1,
//     velocity: 40,
//     distanceToSignalInFront: 386.6281433105469,
//     signalInFront: "SMA_G@7129,82510,8",
//     signalInFrontSpeed: 40
//     },
//     trainName: "PWJ",
//     trainNoLocal: "446004",
//     type: "bot",
//     vehicles: [ "EN57/EN57-1003", "EN57/EN57-614", "EN57/EN57-1755" ]
// },

api.getTimetable(serverCode).then(...);
api.getTimetable(serverCode, "446004").then(...);
// {
//     endStation: "Częstochowa",
//     endsAt: "03:53:00",
//     locoType: "EN57 (5B+6B+5B)",
//     runId: "73c0f0ea-20d9-4317-8339-8bc7d098bd35",
//     startStation: "Jaworzno Szczakowa",
//     startsAt: "02:15:00",
//     timetable: [
//       {
//         departureTime: "2024-08-05 02:15:00",
//         displayedTrainNumber: "446004",
//         line: 133,
//         maxSpeed: 100,
//         kilometrage: 15.81,
//         nameForPerson: "Jaworzno Szczakowa",
//         nameOfPoint: "Jaworzno Szczakowa",
//         pointId: "1472",
//         stopType: "NoStopOver",
//         trainType: "PWJ",
//         supervisedBy: "Jaworzno Szczakowa"
//       },
//       ...
//     ],
//     trainLength: 60,
//     trainName: "PWJ",
//     trainNoLocal: "446004",
//     trainWeight: 60
// }

Automatic updates

import Api from "@simrail-sdk/api";

const api = new Api(...);
const serverCode: Api.ServerCode = "en1";

// Start auto updates using data from "en1".
api.startAutoUpdates(serverCode);

// Stop auto updates.
api.stopAutoUpdates();

// Restart auto updates.
api.startAutoUpdates();

// Or, do the same thing using accessors
api.autoUpdateServer = serverCode;
api.autoUpdate = true;
const updatesEnabled = api.autoUpdate;

Handling events

import Api from "@simrail-sdk/api";

const api = new Api(...);

// Subscribe to API events.
const eventSubscription = api.events.subscribe((event) => {
    switch (event.type) {
        case Api.Event.Type.ActiveServersUpdated:  event.activeServers[0].id;       break;
        case Api.Event.Type.ActiveStationsUpdated: event.activeStations[0].code;    break;
        case Api.Event.Type.ActiveTrainsUpdated:   event.activeTrains[0].id;        break;
        case Api.Event.Type.AutoUpdateChanged:     event.autoUpdate === true;       break;
        case Api.Event.Type.TimetableUpdated:      event.timetable[0].trainNoLocal; break;
    }
});

// Unsubscribe from events.
eventSubscription.unsubscribe();

Working with result caching

import Api from "@simrail-sdk/api";

// Cache configuration can be specified at API class construction.
const api = new Api({

    /** Specifies a config for requests to the timetable endpoint. */
    timetable: {
        cache: {
            /**
             * Specifies if caching is enabled.
             * @default true
             */
            enabled: true,
            /**
             * Specifies for how long a timetable record is cached in seconds.
             * This value also specifies the update interval for auto updates.
             * @default 1440
             */
            retention: 1440,
            /**
             * Specifies if only one timetable record should be cached.
             *
             * When set to:
             * - `true` only the last timetable record will be cached.
             * - `false` a timetable record will be cached for
             *   each server that was queried for a timetable.
             *   Use this when you are actively querying multiple servers.
             *
             * @default true
             */
            singleRecordOnly: true,
        },
    },

    /** Specifies a config for requests to the live data endpoint. */
    liveData: {
        cache: {
            // Values displayed are the defaults.
            activeServers:  { enabled: true, retention: 30 },
            activeStations: { enabled: true, retention: 30 },
            activeTrains:   { enabled: true, retention: 5  },
        },
    },

    ...

});


// Independent of the cache config you can prevent a cached result
//   to be returned by specifying the `noCache` argument.
const serverCode: Api.ServerCode = "de1";
const noCache: Api.NoCache = true;
const nonCachedServers        = await api.getActiveServers(noCache);
const nonCachedServer         = await api.getActiveServer(serverCode, noCache);
const nonCachedStations       = await api.getActiveStations(serverCode, noCache);
const nonCachedStation        = await api.getActiveStation(serverCode, "KO", noCache);
const nonCachedTrains         = await api.getActiveTrains(serverCode, noCache);
const nonCachedTrain          = await api.getActiveTrain(serverCode, "446004", noCache);
const nonCachedTimetable      = await api.getTimetable(serverCode, noCache);
const nonCachedTrainTimetable = await api.getTimetable(serverCode, "446004", noCache);


// If you need to, flush cached data.
api.flushCache();
// Or
api.flushActiveServerCache();
api.flushActiveStationCache();
api.flushActiveTrainCache();
api.flushTimetableCache();

Providing a (custom) Core API class

import Api from "@simrail-sdk/api";
import Core from "different-api-core";

// By default the API will use the Core API class from package `@simrail-sdk/api-core-node`.
// To provide another Core API class or a custom one, just include the instance in the API config.
const core = new Core({ endpoints });
const api = new Api({ core });

API reference

NOTE: The API reference section doesn't account for namespaces, this unfortunately means the documentation below is not entirely complete. Please investigate the TypeScript definition files for the full API.

class Api
- new Api.constructor(config)
- property Api.autoUpdateServer
- property Api.config
- property Api.core
- property Api.events
- property Api.autoUpdate
- method Api.flushActiveServerCache()
- method Api.flushActiveStationCache()
- method Api.flushActiveTrainCache()
- method Api.flushCache()
- method Api.flushTimetableCache()
- method Api.getActiveServer(serverCode, noCache)
- method Api.getActiveServers(noCache)
- method Api.getActiveStation(serverCode, stationCode, noCache)
- method Api.getActiveStations(serverCode, noCache)
- method Api.getActiveTrain(serverCode, trainNoLocal, noCache)
- method Api.getActiveTrains(serverCode, noCache)
- method Api.getTimetable(serverCode, noCache)
- method Api.getTimetable(serverCode, trainNoLocal, noCache)
- method Api.getTimetable(serverCode, trainNoOrNoCache, noCache)
- method Api.startAutoUpdates(autoUpdateServer)
- method Api.stopAutoUpdates()
const DEFAULT_ACTIVE_SERVER_RETENTION
const DEFAULT_ACTIVE_STATION_RETENTION
const DEFAULT_ACTIVE_TRAIN_RETENTION
const DEFAULT_TIMETABLE_RETENTION
const VERSION
const VMAX
const VMAX_VALUE
enum Type
- member Type.ActiveServersUpdated
- member Type.ActiveStationsUpdated
- member Type.ActiveTrainsUpdated
- member Type.AutoUpdateChanged
- member Type.TimetableUpdated
interface ActiveServer
interface ActiveServers
- property ActiveServers.map
- property ActiveServers.timestamp
interface ActiveServersUpdated
- property ActiveServersUpdated.activeServers
interface ActiveStation
- property ActiveStation.code
interface ActiveStationsUpdated
- property ActiveStationsUpdated.activeStations
interface ActiveTrain
interface ActiveTrainsUpdated
- property ActiveTrainsUpdated.activeTrains
interface AutoUpdateChanged
- property AutoUpdateChanged.autoUpdate
interface Base
- property Base.api
- property Base.type
interface Cache
- property Cache.activeServers
- property Cache.activeStations
- property Cache.activeTrains
- property Cache.timetables
interface Config
- property Config.endpoints
interface Data
- property Data.continuesAs
- property Data.endStation
- property Data.endsAt
- property Data.locoType
- property Data.runId
- property Data.startStation
- property Data.startsAt
- property Data.timetable
- property Data.trainLength
- property Data.trainName
- property Data.trainNoInternational
- property Data.trainNoLocal
- property Data.trainWeight
interface Disabled
interface DispatchedBy
- property DispatchedBy.ServerCode
- property DispatchedBy.SteamId
interface Enabled
- property Enabled.retention
- property Enabled.singleRecordOnly
interface Endpoints
- property Endpoints.liveData
- property Endpoints.timetable
interface Error
interface LiveData
- property LiveData.cache
interface Regular
interface Server
- property Server.id
- property Server.isActive
- property Server.serverCode
- property Server.serverName
- property Server.serverRegion
interface Station
- property Station.code
interface Stations
- property Stations.map
- property Stations.timestamp
interface Successful
- property Successful.count
- property Successful.data
- property Successful.description
interface Timetable
- property Timetable.map
- property Timetable.timestamp
interface TimetableUpdated
- property TimetableUpdated.timetable
interface Train
- property Train.endStation
- property Train.id
- property Train.runId
- property Train.serverCode
- property Train.startStation
- property Train.trainData
- property Train.trainName
- property Train.trainNoLocal
- property Train.type
- property Train.vehicles
interface TrainData
- property TrainData.controlledBySteamId
- property TrainData.distanceToSignalInFront
- property TrainData.inBorderStationArea
- property TrainData.latitude
- property TrainData.longitude
- property TrainData.signalInFront
- property TrainData.signalInFrontSpeed
- property TrainData.vdDelayedTimetableIndex
- property TrainData.velocity
interface Trains
- property Trains.map
- property Trains.timestamp
interface WithCore
- property WithCore.core
type ActiveServers
type ActiveStations
type ActiveTrains
type ApiResponse
type ArrivalTime
type AutoUpdate
type AutoUpdateServer
type Cache
type Code
type Config
type ContinuesAs
type ControlledBySteamId
type Count
type DepartureTime
type Description
type DifficultyLevel
type DisplayedTrainNumber
type DistanceToSignalInFront
type Emitter
type EndsAt
type EndStation
type Event
type Id
type ImageUrl
type InBorderStationArea
type IsActive
type Kilometrage
type Latititude
type Latititute
type Latitude
type Line
type List
type LocoType
type Longitude
type Longitute
type Map
type MaxSpeed
type Mileage
type Name
type NameForPerson
type NameOfPoint
type NoCache
type Platform
type PointId
type Prefix
type RadioChannel
type RadioChannels
type Result
type Retention
type RunId
type ServerCode
type ServerName
type ServerRegion
type SignalInFront
type SignalInFrontSpeed
type SingleRecordOnly
type StartsAt
type StartStation
type StationCategory
type SteamId
type StopType
type SupervisedBy
type Timestamp
type Timetables
type Track
type TrainLength
type TrainName
type TrainNoInternational
type TrainNoLocal
type TrainType
type TrainWeight
type Type
type Url
type VdDelayedTimetableIndex
type Vehicle
type Vehicles
type Velocity
type Version

api-reference-@simrail-sdk/api: @simrail-sdk/api "View module \"@simrail-sdk/api\"" api-reference-index: index "View module \"index\"" api-reference-index.d.ts: index.d.ts "View module \"index.d.ts\"" api-reference-node_modules/@simrail-sdk/api-core-node/index.d.ts: node_modules/@simrail-sdk/api-core-node/index.d.ts "View module \"node_modules/@simrail-sdk/api-core-node/index.d.ts\"" api-reference-node_modules/@simrail-sdk/api-core-node/types/liveData/index.d.ts: node_modules/@simrail-sdk/api-core-node/types/liveData/index.d.ts "View module \"node_modules/@simrail-sdk/api-core-node/types/liveData/index.d.ts\"" api-reference-node_modules/@simrail-sdk/api-core-node/types/timetable/index.d.ts: node_modules/@simrail-sdk/api-core-node/types/timetable/index.d.ts "View module \"node_modules/@simrail-sdk/api-core-node/types/timetable/index.d.ts\"" api-reference-index.ts: index.ts "View module \"index.ts\""

`class Api` ↑

Specifies an API class instance for interacting with SimRail's remote API.

Implements: Omit<Api.Core, "config">

Since: 0.1.0

Definition: index.ts:29

`new Api.constructor(config)` ↑

Arguments:	Type
`config`	`Config`

Returns: Api

Since: 0.1.0

Definition: index.ts:94

`property Api.autoUpdateServer` ↑

optional

Specifies the unique code of the server to automatically retrieve data from.

Type: string

Since: 0.1.0

Definition: index.ts:47

`property Api.config` ↑

read-only

Specifies the configuration of the API.

Type: Config

Since: 0.1.0

Definition: index.ts:35

`property Api.core` ↑

read-only

Specifies a reference to the Core API.

Type: Api.Core

Since: 0.1.0

Definition: index.ts:32

`property Api.events` ↑

read-only

Specifies the event emitter for API events.

Type: Emitter

Since: 0.1.0

Definition: index.ts:38

`property Api.autoUpdate` ↑

Since: 0.1.0

Definition: index.ts:73