Socket
Socket
Sign inDemoInstall

mav-api

NodeJS module for the MÁV API (Hungarian Railway company).


Version published
Maintainers
1
0

Weekly downloads

Readme

Source

MÁV API

Unofficial NodeJS module for the new MÁV API (API from the Hungarian Railway company). Please contact MÁV if you want to use an API for monetary purposes. This is an information interface for hobby applications.

Implemented endpoints and usage

Every function returns a promise.

Import:

const api = require("mav-api");

informationApi

Station information (station data, arrivals, departures)

api.informationApi.getStationInformation(
    "005510033", // Should be string if it starts with zeros!
    new Date("2021-07-01T12:00:00+02:00") // Response is given in this time format. Use this to avoid issues! Optional, defaults to the current time.
).then(data => {
    console.log(data); // Data is in JSON format.
}).catch(err => {
    console.log(err);
})

Train information

Be aware, that the train ID might not be unique. There are usually international trains with the same ID.

api.informationApi.getTrainInformation(
    737, // Can be number if it does not start with zeros!
    new Date("2021-07-01T12:00:00+02:00")
).then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

Warning messages

These are (not so useful) warning messages, mostly of the website.

api.informationApi.getWarningMessages().then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

offerRequestApi

Station list

This gives back a list of stations, including their IDs.
If you want to get station info, you should get the ID of the station here (i.e.: array filter).
TODO: Accept parameters and resolve with filtered data.

api.offerRequestApi.getStationList().then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

Cities and postal codes

Cities with an array of corresponding postal codes.

api.offerRequestApi.getCitiesAndPostalCodes().then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

Services and search services

Search options and services for getOfferRequest.

api.offerRequestApi.getServicesAndSearchServices().then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

Customers and discounts

Customer type list and discount list. Useful for creating the passenger array for getOfferRequest.

api.offerRequestApi.getCustomersAndDiscounts().then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

Offer request

This is a more complex interface. It gives back a full trip and price offer.
If you want to use the ticket price offers and want to use special passenger types, you should create an array of passengers:

// Passengers is an array, even if it contains only one passenger type!
let passengers = [
    // This is the default passenger type
    {
    "passengerCount": 1, // Number of passengers of this type
    "passengerId": 0, // Incrementing at each type.
    "customerTypeKey": "HU_44_026-065", // Passenger type, can be obtained from getCustomersAndDiscounts
    "customerDiscountsKeys": [] // Discount keys for the passenger, i.e. student discount, can be obtained from getCustomersAndDiscounts
    }
]

Use it in the interface:

// Get offers from Szeged to Budapest-Nyugati, starting now, with the default passenger
api.offerRequestApi.getOfferRequest("005517228", "005510033", new Date() /* Optional, if passengers are not given */, passengers /* Optional */).then(data => {
    console.log(data);
}).catch(err => {
    console.log(err);
})

MÁV API documentation and discoveries

This section is not needed to use the library. This is kind of a behind the scenes part, however it might be useful.
All API requests are made to this host: https://jegy-a.mav.hu/
This is followed by this path: /IK_API_PROD/api/
GetTimetable and GetOfferRequest are the most important endpoints. Headers:

{
    "UserSessionId": "''",
    "Content-Type": "application/json; charset=utf-8"
}

UserSessionId is an empty string, but the aposthrophes must be included!

/InformationApi/GetTimetable (implemented)

Gets timetable information for station / train. Seems to be the main information interface. Hungary is +02:00 UTC offset, in this example the result will contain information past 14:00.

  • Train information
{
    "type": "TrainInfo",
    "trainNumber": "123",
    "travelDate": "2021-01-01T12:00:00.000Z",
    "minCount": "0",
    "maxCount": "9999999"
}
  • Station info
{
    "type": "StationInfo",
    "stationNumberCode": "123456789",
    "travelDate": "2021-01-01T12:00:00.000Z",
    "minCount": "0",
    "maxCount": "9999999"
}

/InformationApi/GetTrainNumbers (not implemented)

Returns with an array of train numbers. Might be categories, usage is unclear, therefore this is not implemented.

/InformationApi/SearchTrainNumbers (not implemented)

Not working.

/InformationApi/GetWarningMessages (implemented)

Gets warning messages. These messages are mostly general announcements.

/OfferRequestApi/GetOfferRequest (implemented)

Gets directions and prices between two stations.
For detailed search, see the GetServicesAndSearchServices endpoint, which gives the full list of possible discounts and customer types. This is a basic search query:

{
    "offerkind": "1",
    "isOneWayTicket": true,
    "startStationCode": "123456789",
    "endStationCode": "123456789",
    "travelStartDate": "2021-05-30T12:30:00+02:00",
    "passangers": [
        {
            "passengerCount": 1,
            "passengerId": 0,
            "customerTypeKey": "HU_44_026-065",
            "customerDiscountsKeys": []
        }
    ],
    "selectedServices": [],
    "selectedSearchServices": [],
    "isTravelEndTime": false,
    "innerStationsCodes": [
        {
            "stationCode": "123456789",
            "durationOfStay": 0
        }
    ],
    "isOfDetailedSearch": false
}  

Yes, "passangers" is a misspelling in the API. InnerStationsCodes is optional.

/OfferRequestApi/GetStationList (implemented)

Gets the station list. No query needed. This endpoint is important for getting timetables and directions, since it contains the station numbers.

/OfferRequestApi/GetCitiesAndPostalCodes (implemented)

Gets the cities with their postal codes. No query needed.

/OfferRequestApi/GetServicesAndSearchServices (implemented)

Gets the possible customer types and discounts. Every customer type has its own discounts.

{
    "offerKind": "InternalTicket"
}

/OfferRequestApi/GetCustomersAndDiscounts (implemented)

Similar to the previous endpoint, but it is a bit cleaner.

{
    "offerKind": "InternalTicket"
}

/OfferRequestApi/FrequentDiscountList (not implemented)

No information is available at the moment, seems to give an array of discounts, which is now blank. There might be special / frequent discounts for routes that'll show up here.

/InformationApi/GetSwVersions (not implemented)

Gets the API version. No query needed.

Miscellaneous endpoints (these are not implemented)

  • /BaseDataApi/GetExchangeRate (not working)
  • /BaseDataApi/GetCurrencies (gets currencies.)
  • /ProfileApi/GetPublicPlaceTypes (street, square, avenue, etc.)
  • /OfferRequestApi/GetPreOrderMaxDays (number)
  • /OfferRequestApi/GetCountyList (counties of Hungary)
  • /DocumentApi/AktualisDokumentumLista (gets legal document links fo the site)

Keywords

FAQs

Last updated on 02 Jun 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc