hafas-client

A client for the "mobile APIs" of HAFAS public transport management systems.

Background

A company called HaCon sells a public transport management system called HAFAS. It is used by public transport providers across Europe to provide routing and departure information to their customers.

Most customers get their own, separate HAFAS deployments; They all use the same terminology and API calls, but have slightly different versions, configurations and sets of enabled features. Using endpoint-specific customisations that we call profiles, hafas-client abstracts most of these differences away, and supports additional features in some cases. Check the supported networks/endpoints list for more info.

Note: Currently, hafas-client only supports "mobile API" endpoints, which are designed for and used by the respective official mobile app(s); These endpoints almost always have mgate.exe in the URL. This library does not support "open API" endpoints (often they have rest-proxy or openapi in the URL) yet, but #134 contains work in progress.

Strictly speaking, permission is necessary to use hafas-client with a HAFAS "mobile" endpoint. It merely tries to remove the technical barrier of accessing the data, in order to kick-start an ecosystem or apps and services that would eventually rely on openly available data.

Installing

npm install hafas-client

with react-native

hafas-client as well its dependencies use Node-builtin modules and Node globals. To be able to use it within react-native, follow the instructions at node-libs-react-native.

Usage

The main entry point of this library is a function createClient(profile, userAgent). Pass in a profile and an expressive name for your program.

const createClient = require('hafas-client')
const dbProfile = require('hafas-client/p/db')

// create a client with the Deutsche Bahn profile
const client = createClient(dbProfile, 'my-awesome-program')

You can now use the client object to query the HAFAS endpoint configured in the db profile:

// Berlin Jungfernheide to München Hbf
client.journeys('8011167', '8000261', {results: 1})
.then(console.log).catch(console.error)

journeys() returns a Promise that will resolve with an object with an array journeys that contains one Friendly Public Transport Format (FPTF) 1.2.1 journey.

{
	journeys: [ {
		origin: {
			type: 'station',
			id: '8089100',
			name: 'Berlin Jungfernheide (S)',
			location: { /* … */ },
			products: { /* … */ }
		},
		departure: '2017-12-19T17:05:30+01:00',
		plannedDeparture: '2017-12-19T17:05:00+01:00',
		departureDelay: 30,
		departurePlatform: '5',
		plannedDeparturePlatform: '5',

		destination: {
			type: 'station',
			id: '8000261',
			name: 'München Hbf',
			location: { /* … */ },
			products: { /* … */ }
		},
		arrival: '2017-12-19T22:44:00+01:00',
		plannedArrival: '2017-12-19T22:45:00+01:00',
		arrivalDelay: -60,
		arrivalPlatform: '11A',
		plannedArrivalPlatform: '13',

		legs: [ {
			id: '1|100067|48|81|17122017',
			line: {
				type: 'line',
				id: '41172',
				name: 'S 41',
				public: true,
				mode: 'train',
				product: 'suburban',
				operator: {
					type: 'operator',
					id: 's-bahn-berlin-gmbh',
					name: 'S-Bahn Berlin GmbH'
				}
			},
			direction: 'Ringbahn ->',

			origin: {
				type: 'station',
				id: '8089100',
				name: 'Berlin Jungfernheide (S)',
				location: {
					type: 'location',
					latitude: 52.530291,
					longitude: 13.299451
				},
				products: { /* … */ }
			},
			departure: '2017-12-19T17:05:30+01:00',
			plannedDeparture: '2017-12-19T17:05:00+01:00',
			departureDelay: 30,
			departurePlatform: '5',
			plannedDeparturePlatform: '5',

			destination: {
				type: 'station',
				id: '8089118',
				name: 'Berlin Beusselstraße'
				/* … */
			},
			arrival: '2017-12-19T17:08:00+01:00',
			plannedArrival: '2017-12-19T17:08:00+01:00',
			arrivalDelay: null,
			arrivalPlatform: '2a-b',
			plannedArrivalPlatform: '1'
		},
		/* more legs… */
		{
			walking: true,
			public: true,

			origin: {
				type: 'station',
				id: '730749',
				name: 'Berlin Hauptbahnhof (S+U), Berlin'
				/* … */
			},
			plannedDeparture: '2017-12-19T17:25:00+01:00',
			prognosedDeparture: null,
			departureDelay: null,

			destination: {
				type: 'station',
				id: '8098160',
				name: 'Berlin Hbf (tief)'
				/* … */
			},
			arrival: '2017-12-19T17:33:00+01:00',
			plannedArrival: '2017-12-19T17:33:00+01:00',
			arrivalDelay: null
		}, {
			id: '1|70906|0|81|17122017',
			line: { /* … */ },
			direction: 'München Hbf',

			origin: {
				type: 'station',
				id: '8098160',
				name: 'Berlin Hbf (tief)'
				/* … */
			},
			departure: '2017-12-19T17:35:00+01:00',
			plannedDeparture: '2017-12-19T17:37:00+01:00',
			departureDelay: -120,
			departurePlatform: '1',
			plannedDeparturePlatform: '1',

			destination: {
				type: 'station',
				id: '8000261',
				name: 'München Hbf',
				/* … */
			},
			arrival: '2017-12-19T22:44:00+01:00',
			plannedArrival: '2017-12-19T22:45:00+01:00',
			arrivalDelay: -60,
			arrivalPlatform: '11A',
			plannedArrivalPlatform: '13'
		} ],
		price: {
			amount: null,
			hint: 'No pricing information available.'
		}
		/* … */
	} ]
	/* … */
}

Each of the profiles has more detailed example code.

API

API documentation

supported networks/endpoints

hafas-client has built-in customisations called profiles for these public transportation networks:

HAFAS endpoint	wrapper library	docs	example code	source code
Deutsche Bahn (DB)	db-hafas	docs	example code	src
Polskie Koleje Państwowe (PKP)	pkp-hafas	docs	example code	src
Belgian National Railways (SNCB/NMBS)	-	docs	example code	src
Berlin & Brandenburg public transport (VBB)	vbb-hafas	docs	example code	src
Berlin public transport (BVG)	bvg-hafas	docs	example code	src
Österreichische Bundesbahnen (ÖBB)	oebb-hafas	docs	example code	src
Nahverkehr Sachsen-Anhalt (NASA)/INSA	insa-hafas	docs	example code	src
Nahverkehrsverbund Schleswig-Holstein (NAH.SH)	nahsh-hafas	docs	example code	src
Rhein-Main-Verkehrsverbund (RMV)	-	docs	example code	src
Austin, Texas (CMTA/CapMetro)	-	docs	example code	src
S-Bahn München	-	docs	example code	src
Saarfahrplan/VGS (Saarland)	-	docs	example code	src
Société Nationale des Chemins de Fer Luxembourgeois (CFL)	-	docs	example code	src
Hamburg public transport (HVV)	-	docs	example code	src
Nordhessischer Verkehrsverbund (NVV) (Hesse)	-	docs	example code	src
DB Busradar NRW (DB Regio Bus)	-	docs	example code	src
Verkehrsverbund Süd-Niedersachsen (VSN)	-	docs	example code	src
Ingolstädter Verkehrsgesellschaft (INVG)	-	docs	example code	src
Verkehrsverbund Bremen/Niedersachsen (VBN)	-	docs	example code	src
Rostocker Straßenbahn AG (RSAG)	-	docs	example code	src
Verkehrsverbund Mittelthüringen (VMT)	-	docs	example code	src
Salzburg public transport (SVV)	-	docs	example code	src

There are also libraries that use hafas-client and pass their own profile in:

HAFAS endpoint	library
Betriebsstellen & disturbances in the German rail network	db-netz-hafas

Related

• public-transport-enabler – Unleash public transport data in your Java project.
• TripKit – Swift library for querying data from public transport providers.
• Friendly Public Transport Format – A format for APIs, libraries and datasets containing and working with public transport data.
• db-hafas – JavaScript client for the DB HAFAS API.
• vbb-hafas – JavaScript client for Berlin & Brandenburg public transport HAFAS API.
• observe-hafas-client – Observe all departures/arrivals/etc. returned by hafas-client.
• cached-hafas-client – Pass in a hafas-client instance, cache data from it.
• hafas-client-rpc – Make JSON-RPC calls to hafas-client via WebSockets & stdio.
• hafas-client-health-check – Check if a hafas-client instance and its endpoint work.
• hafas-rest-api – Expose a HAFAS client via an HTTP REST API.
• List of european long-distance transport operators, available API endpoints, GTFS feeds and client modules.
• Collection of european transport JavaScript modules.
• hafas-find-stations – Given a HAFAS client, find all stations in a bounding box.
• hafas-collect-departures-at – Utility to collect departures, using any HAFAS client.
• hafas-monitor-trips – Using a HAFAS client, watch all trips in a bounding box.
• hafas-monitor-departures – Pass in a HAFAS client, fetch all departures at any set of stations.
• hafas-record-delays – Record delays from hafas-monitor-departures into a LevelDB.
• hafas-monitor-journeys – Use hafas-client to monitor journeys from A to B.
• hafas-discover-stations – Pass in a HAFAS client, discover stations by querying departures.
• hafas-estimate-station-weight – Pass in a HAFAS client, estimate the importance of a station.

Contributing

If you have a question, found a bug or want to propose a feature, have a look at the issues page.

This project needs help! Check the list of "help wanted" Issues.