@simrail-sdk/api-core-node NPM

SimRail Core API for Node.JS

This is a Core API module (community edition) for interacting with the SimRail APIs.

This Core API module just provides an interface with SimRail's remote APIs. If you are looking for a more usable SDK module, check out:

@simrail-sdk/api if you need an SDK just for retrieving live data.
@simrail-sdk/core for a more developer-friendly SDK consuming only live data.
@simrail-sdk/sdk for a developer-friendly SDK providing extended data about the game. (upcoming)

Content index

Usage details
- Installation
- Examples
  - Simple API usage
  - Disable data conversion
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-core-node

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

Where VERSION specifies the version to install.

Examples

Simple API usage

For regular usage you only need to construct the API class and provide it with the endpoint URLs for live data and the timetable.

NOTE: API SDK will do some simple conversion on data received from endpoints to fix typos and enable continuity with other SDK projects. To disable this functionality, please refer to the second example below.

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

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

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

api.getActiveStations("en1").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("en1").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("en1").then(...);
api.getTimetable("en1", "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
// }

Disable data conversion

Use option convertData to enable or disable result conversion. (default: true)

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

const endpoints: Api.Endpoints = {
    liveData: "https://panel.simrail.eu:8084",
    timetable: "https://api1.aws.simrail.eu:8082/api",
};

new Api({ convertData: false, endpoints }).getActiveStations("en1").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'
//         Latititude: 50.25686264038086,
//         Longitude: 19.01921844482422,
//         MainImageURL: 'https://api.simrail.eu:8083/Thumbnails/Stations/ko1m.jpg',
//         Name: 'Katowice',
//         Prefix: 'KO',
//     },
//     ...
// ]

new Api({ convertData: true, endpoints }).getActiveStations("en1").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 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.

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

`class Api` ↑

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

Type params:	Extends	Optional	Default	Description
`ConvertData`	`Api.ConvertData`	Yes	`true`	Specifies if responses are converted or if the raw API response is returned. (default: `true`)

Since: 0.1.0

Definition: index.ts:30

`new Api(config)` ↑

Type params:	Extends	Optional	Default
`ConvertData`	`boolean`	Yes	`true`

Arguments:	Type
`config`	`Config`<`ConvertData`>

Returns: Api<ConvertData>

Since: 0.1.0

Definition: index.ts:35

`property Api.config` ↑

read-only

Specifies the configuration of the API.

Type: Config<ConvertData>

Since: 0.1.0

Definition: index.ts:33

`method Api.getActiveServers()` ↑

Method to retrieve servers from the live data endpoint.

Returns: Promise<ConvertData extends true ? Array<Server> : Array<Server.Raw>> - A list of multiplayer servers.

Since: 0.1.0

Definition: index.ts:44

`method Api.getActiveStations(serverCode)` ↑

Method to retrieve active dispatch stations from the live data endpoint.

Arguments:	Type	Description
`serverCode`	`string`	The unique code of the multiplayer server.

Returns: Promise<ConvertData extends true ? Array<Station> : Array<Station.Raw>> - A list of active dispatch stations.

Since: 0.1.0

Definition: index.ts:57

`method Api.getActiveTrains(serverCode)` ↑

Method to retrieve active trains from the live data endpoint.

Arguments:	Type	Description
`serverCode`	`string`	The unique code of the multiplayer server.

Returns: Promise<ConvertData extends true ? Array<Train> : Array<Train.Raw>> - A list of active trains.

Since: 0.1.0

Definition: index.ts:70

`method Api.getTimetable(serverCode)` ↑

Method to retrieve timetable data from the timetable endpoint.

Arguments:	Type	Description
`serverCode`	`string`	The unique code of the multiplayer server.

Returns: Promise<ConvertData extends true ? Array<Timetable> : Array<Timetable.Raw>>

Since: 0.1.0

Definition: index.ts:83

`method Api.getTimetable(serverCode, trainNoLocal)` ↑

Method to retrieve timetable data from the timetable endpoint.

Arguments:	Type	Description
`serverCode`	`string`	The unique code of the multiplayer server.
`trainNoLocal`	`string`	The national train number of a train. If left `undefined`, this function will return data for all trains in the timetable.

Returns: Promise<ConvertData extends true ? Data : Raw>

Since: 0.1.0

Definition: index.ts:83

`method Api.getTimetable(serverCode, trainNoLocal)` ↑

Method to retrieve timetable data from the timetable endpoint.

Arguments:	Type	Optional	Description
`serverCode`	`string`	No	The unique code of the multiplayer server.
`trainNoLocal`	`string`	Yes	The national train number of a train. If left `undefined`, this function will return data for all trains in the timetable.

Returns: Promise<ConvertData extends false ? (Raw | List) : (Data | List)>

Since: 0.1.0

Definition: index.ts:83

`const VERSION` ↑

Specifies the version of the API.

Type: Version

Since: 0.1.0

Definition: index.ts:277

`const VMAX` ↑

Specifies the maximum allowable operating speed. (Vmax)

Type: "vmax"

Since: 0.1.0

Definition: types/liveData/index.ts:15

`const VMAX_VALUE` ↑

Specifies the "speed" value that will indicate "vmax".

Type: 32767

Since: 0.1.0

Definition: types/liveData/index.ts:18

`interface Base` ↑

Type params:	Extends
`ResponseResult`	`Result`

Since: 0.1.0

Definition: types/liveData/index.ts:30

`property Base.result` ↑

Specifies if the request succeeded.

Type: ResponseResult

Since: 0.1.0

Definition: types/liveData/index.ts:32

`interface Config` ↑

Specifies the configuration of the API.

Type params:	Extends	Description
`ApiConvertData`	`ConvertData`	Specifies if responses are converted or if the raw API response is returned.

Since: 0.1.0

Definition: index.ts:289

`property Config.convertData` ↑

read-only optional

Specifies if responses are converted or if the raw API response is returned.

Type: ApiConvertData

Since: 0.1.0

Definition: index.ts:295

`property Config.endpoints` ↑

read-only

Specifies the configuration for API endpoints.

Type: Endpoints

Since: 0.1.0

Definition: index.ts:297

`interface Data` ↑

Specifies information about a train in a timetable.

Since: 0.1.0

Definition: types/timetable/index.ts:15

`property Data.continuesAs` ↑

optional

Specifies under which train number the train will continue.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:17

`property Data.endStation` ↑

Specifies the name of the destination station.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:19

`property Data.endsAt` ↑

Specifies when the train arrives at it's destination. Format: hh:mm:ss

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:21

`property Data.locoType` ↑

Specifies the name of the train's locomotive.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:23

`property Data.runId` ↑

Specifies the unique ID of the train. (independent from the train number)

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:25

`property Data.startStation` ↑

Specifies the name of the origin station.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:27

`property Data.startsAt` ↑

Specifies when the train departs from it's origin. Format: hh:mm:ss

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:29

`property Data.timetable` ↑

Specifies a list of timetable entries for this train.

Type: List

Since: 0.1.0

Definition: types/timetable/index.ts:31

`property Data.trainLength` ↑

Specifies the length of the train in meters.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:33

`property Data.trainName` ↑

Specifies the name of the train or train series.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:35

`property Data.trainNoInternational` ↑

optional

Specifies the international train number of this train.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:37

`property Data.trainNoLocal` ↑

Specifies the national train number of this train.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:39

`property Data.trainWeight` ↑

Specifies the weight of this train in metric tonnes.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:41

`interface DispatchedBy` ↑

Specifies a player dispatching at a station in the raw API format.

Since: 0.1.0

Definition: types/liveData/index.ts:196

`property DispatchedBy.ServerCode` ↑

Specifies the unique code of the server the player is using in the raw API format.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:198

`property DispatchedBy.SteamId` ↑

Specifies the Steam ID of the player in the raw API format.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:200

`interface Endpoints` ↑

Since: 0.1.0

Definition: index.ts:303

`property Endpoints.liveData` ↑

read-only

Specifies the URL for the live data API endpoint.

Type: string

Since: 0.1.0

Definition: index.ts:305

`property Endpoints.timetable` ↑

read-only

Specifies the URL for the timetable API endpoint.

Type: string

Since: 0.1.0

Definition: index.ts:307

`interface Error` ↑

Specifies a response for a failed request.

Extends: Base<false>

Since: 0.1.0

Definition: types/liveData/index.ts:39

`interface Raw` ↑

Specifies a timetable entry for a train in the raw API format.

Since: 0.1.0

Definition: types/timetable/index.ts:180

`property Raw.arrivalTime` ↑

Specifies when the train arrives at this point in the raw API format.

Type: ArrivalTime

Since: 0.1.0

Definition: types/timetable/index.ts:182

`property Raw.mileage` ↑

Specifies at what distance this point will be passed in kilometers and in the raw API format.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:184

`property Raw.platform` ↑

Specifies at which platform the train will stop in Roman numerals in the raw API format.

Type: Platform

Since: 0.1.0

Definition: types/timetable/index.ts:190

`property Raw.radioChanels` ↑

Specifies the radio channels required after this point as a comma-separated string in the raw API format.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:196

`property Raw.stationCategory` ↑

Specifies the category of the station in the raw API format.

Type: StationCategory

Since: 0.1.0

Definition: types/timetable/index.ts:198

`property Raw.stopType` ↑

Specifies the type of stop the train will make in the raw API format.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:200

`property Raw.supervisedBy` ↑

Specifies the name of the dispatch station this point belongs to in the raw API format.

Type: SupervisedBy

Since: 0.1.0

Definition: types/timetable/index.ts:202

`property Raw.track` ↑

Specifies the number of the track this train will stop at in the raw API format.

Type: Track

Since: 0.1.0

Definition: types/timetable/index.ts:204

`interface Server` ↑

Specifies a multiplayer server.

Since: 0.1.0

Definition: types/liveData/index.ts:64

`property Server.id` ↑

Specifies the unique ID of the server. (independent of code)

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:66

`property Server.isActive` ↑

Specifies if the server is active.

Type: boolean

Since: 0.1.0

Definition: types/liveData/index.ts:68

`property Server.serverCode` ↑

Specifies the unique code of the server.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:70

`property Server.serverName` ↑

Specifies the name of the server.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:72

`property Server.serverRegion` ↑

Specifies in which region the server is located.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:74

`interface Station` ↑

Specifies an active dispatch station.

Since: 0.1.0

Definition: types/liveData/index.ts:115

`property Station.additionalImage1URL` ↑

Specifies the URL of the first secondary image for this station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:117

`property Station.additionalImage2URL` ↑

Specifies the URL of the second secondary image for this station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:119

`property Station.difficultyLevel` ↑

Specifies the difficulty level for this station. (from 1 to 5)

Type: DifficultyLevel

Since: 0.1.0

Definition: types/liveData/index.ts:121

`property Station.dispatchedBy` ↑

optional

Specifies a list of players dispatching at this station.

Type: Array<DispatchedBy>

Since: 0.1.0

Definition: types/liveData/index.ts:123

`property Station.id` ↑

Specifies the unique ID of this station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:125

`property Station.latitude` ↑

Specifies the global latitude of this station.

Type: number

Since: 0.1.0

Definition: types/liveData/index.ts:127

`property Station.longitude` ↑

Specifies the global longitude of this station.

Type: number

Since: 0.1.0

Definition: types/liveData/index.ts:129

`property Station.mainImageURL` ↑

Specifies the URL of the main image of this station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:131

`property Station.name` ↑

Specifies the name of the station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:133

`property Station.prefix` ↑

Specifies the prefix of this station.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:135

`interface Successful` ↑

Specfies a response for a successful request.

Extends: Base<true>

Type params:	Description
`ResponseData`	The requested data.

Since: 0.1.0

Definition: types/liveData/index.ts:47

`property Successful.count` ↑

Specifies the number of results.

Type: number

Since: 0.1.0

Definition: types/liveData/index.ts:49

`property Successful.data` ↑

Specifies the requested data.

Type: ResponseData

Since: 0.1.0

Definition: types/liveData/index.ts:51

`property Successful.description` ↑

Specifies a description for the response.

Type: string

Since: 0.1.0

Definition: types/liveData/index.ts:53

`interface Timetable` ↑

Specifies a timetable entry for a train.

Since: 0.1.0

Definition: types/timetable/index.ts:88

`property Timetable.arrivalTime` ↑

optional

Specifies when the train arrives at this point.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:90

`property Timetable.departureTime` ↑

Specifies when the train departs at this point.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:92

`property Timetable.displayedTrainNumber` ↑

Specifies which train number is displayed for this train.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:94

`property Timetable.kilometrage` ↑

Specifies at what distance this point will be passed.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:100

`property Timetable.line` ↑

Specifies the number of the line that the train will follow.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:96

`property Timetable.maxSpeed` ↑

Specifies the maximum speed at this point.

Type: number

Since: 0.1.0

Definition: types/timetable/index.ts:98

`property Timetable.nameForPerson` ↑

Specifies the name of the dispatcher for this point.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:102

`property Timetable.nameOfPoint` ↑

Specifies the name of this point.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:104

`property Timetable.platform` ↑

optional

Specifies at which platform the train will stop in Roman numerals.

Type: string

Since: 0.1.0

Definition: types/timetable/index.ts:110

`property Timetable.pointId` ↑

[api-re

simrail sdk api core rest

12 months ago

12 months ago

12 months ago