scotty-api-adapter
v1.0.6
Published
This is a simple adapter for the Austrian OEBB Scotty (Hafas) Transport API. This is **unofficial** as there is no public documentation available for the original API.
Downloads
23
Readme
Scotty API Adapter
Preface
This is a simple adapter for the Austrian OEBB Scotty (Hafas) Transport API. This is unofficial as there is no public documentation available for the original API.
Sulphire does not guarantee that this adapter will work in the future as the API is not officially supported. As of right now, our adapter is working for most routes. The official API structure is very outdated, please see the disclaimer below for more details.
Disclaimer
The original API is using time based on IP address geolocation and does not return the time in the timezone of departure. It is also not possible to change the timezone at the moment. The time the API returns is a simple "hhmmss" string, same goes for the date. There is no timezone info.
You can use standalone methods to format the time appropriately and calculate delays. Please see below.
Currently supported apps
Other apps may be supported, but we have not tested them yet.
- VVV/vmobil.at (
https://fahrplan.vmobil.at/bin/mgate.exe
)
Installation
npm install scotty-api-adapter
Usage example
const ScottyAdapter = require('scotty-api-adapter');
const scotty = new scottyAdapter.ScottyAPI("https://fahrplan.vmobil.at/bin/mgate.exe")
const startLocationQuery = await scotty.getLocations("Bregenz Bahnhof")
const endLocationQuery = await scotty.getLocations("Hohenems Bahnhof")
const startLocation = startLocationQuery[0].name; // get the first result
const endLocation = endLocationQuery[0].name;
const date = new Date(); // get journeys for current time (this might sometimes throw an error if there are no journeys in the near future)
const journeys = await scotty.getTransportOptions(startLocation, endLocation, date)
// journeys is an array of Journey objects, see below for more info
Objects
General Info
real
time object might be undefined, please use scheduled time if real time is undefined
Journey
A journey as returned by getTransportOptions
. start
and end
's scheduled and real are objects with { hours, minutes, seconds} as integers. timeline
is an array of Timeline objects. stopName
is the name of the stop. platform
is the platform number, if available. timelineHash
is a hash of the timeline array, this is only used for internal duplicate checking.
{
"timeline": Timeline[],
"start": { scheduled, real, stopName, (platform) },
"end": { scheduled, real, stopName, (platform) },
"timelineHash": string,
}
Timeline (array)
This is the order of a journey. dep
and arr
times are objects with { hours, minutes, seconds } as integers. id
is the Bus number or the train number. stopName
is the name of the stop. platform
is the platform number, if available.
A journey where you start in a Bus and have to switch to train or a different Bus would look like this:
JNY -> TNSF -> JNY
{
"type": "JNY" | "WALK" | "TNSF",
"dep": { scheduled, real, stopName, (platform) },
"arr": { scheduled, real, stopName, (platform) },
"id": string,
"mode": TransportMode
}[]
TransportMode
Transport mode as returned by the API. Type values are similar to "Bus" or "Train", depending on the source.
{
"type": string,
"num": string,
"admin": string,
}
Methods
ScottyAPI Class
getLocations(locationName)
Returns an array of locations matching the given name. The array is sorted by relevance, the first result is the most relevant one. The array is empty if no results were found.
const locations = await scotty.getLocations("Bregenz Bahnhof")
getTransportOptions(startLocation, endLocation, date, lang, raw)
Returns an array of journeys. startLocation
and endLocation
are strings, date
is a JavaScript Date object. Depending on the date and time, the API might not return any journeys. (Please read Disclaimer for time formats and zones) lang
is the language of the response, default is "eng". raw
is a boolean, if true, the raw response from the API is returned. Default is false.
const journeys = await scotty.getTransportOptions("Bregenz Bahnhof", "Hohenems Bahnhof", new Date())
Standalone functions
formatTime(time)
Formats a time object from the API to a readable format (hh:mm:ss).
const time = { hours: 12, minutes: 30, seconds: 0 }
const formattedTime = scottyAdapter.formatTime(time) // 12:30:00
calculateTimeDifference(time1, time2)
Calculates the difference between two time objects from the API. Returns an object with { hours, minutes, seconds } as integers. Useful for calculating the delays or the duration of a journey.
const time1 = { hours: 12, minutes: 30, seconds: 0 }
const time2 = { hours: 12, minutes: 45, seconds: 0 }
const timeDifference = scottyAdapter.calculateTimeDifference(time1, time2) // { hours: 0, minutes: 15, seconds: 0 }