librailfare

librailfare is an Affero GPL-licensed library to load, query and search the integrated fares database used by all British train operating companies.

Background

Franchised train operating companies (TOCs) in Great Britain are required by their franchise agreements to operate an integrated ticketing and fares system. The system used is inherited from British Rail and has a very complex structure. As far as I'm aware there is no open source software currently available that can work with this data, so I decided to create librailfare in order to

  1. faciliate passengers who want to explore the ticket options available in order to find the most convenient fare for their journey, and
  2. provide a freely available "reference implementation" of software to handle this rail fare data in the hope that this will facilitate the development of better online journey planning systems than are currently available.

The motivation behind this is that whilst the many journey planning websites currently available are very good at finding the cheapest point-to-point fare to travel at a given time on a given "optimum" route between the two points (which they have determined using some black-box algorithm), they are not so good at providing the information necessary for flexible travel planning, when a passenger might wish to use the break-of-journey or flexible routeing options offered by certain tickets, for example. I believe this is because journey planners tend to use off-the-shelf software and are not really optimised to exploit the inherent flexibility in the ticketing system inherited from British Rail. In my opinion this can only be achieved by developing custom software to exploit such flexibility. I hope that this little library will prove to be a starting point for that, and encourage the development of more open railway data websites such as Open Train Times and BRfares. The latter of these sites now includes an API that exposes a lot of the same fares data as librailfare does.

Source Code and Licensing

The library is written in C and provides a C API. I believe this is the best choice for optimum performance, which is particularly important when dealing with large amounts of complex data. It is licensed under the GNU Affero GPL. This is a stricter license than the normal GPL; in addition to the protections afforded by the GPL, it also compels the source code to be provided to any users interacting with the software remotely over a network (N.B. THIS IS NOT A LEGAL DEFINITION - please see the file LICENSE.txt included in the source code distribution for the legal definition of the license). As I hope this software will one day have utility when used interactively through a website, and I want any enhancements made to be preserved and made public, I felt this was an appropriate license.

Structure

The core of the library is a set of C structures, defined in the file include/railfare_core.h, into which the fares data is imported by an import module and upon which higher level functionality such as point-to-point fare queries can be built.

It is envisaged that, in order to provide a more user-friendly API to the core, a wrapper layer would be built on top of this. The structures could for example be wrapped in C++ classes. At present development of a C API with functionality to make fares queries has been started and is defined by the header file include/railfare.h. The source is in the directory capi/. For more advanced functionality at present, direct access to the core structures is still required.

Data Import

At present the only data import module provided is for the National Fares Manual CD-ROM (source code in directory nfmcd/). An updated version of this is released three times per year and can be purchased from The Stationery Office Online Bookshop for approx. £10. It is important to note that the copyright in the fares data is held by the Association of Train Operating Companies, and thus can only be used for personal use and not redistributed.

In future it is planned to write an additional import module for the flat file format used by the Rail Journey Information System (RJIS) data feed interface; this would make the library more useful.

Download

The project is available in source code only and can be downloaded from the SourceForge project page. The Subversion repository may also be browsed online.

Examples

An example program has been provided that illustrates how to perform a simple point-to-point fare query. The source code is in examples/linux/fare_query.c and uses a mix of both the high-level C API and direct access to the core. This is an interactive command-line Linux program and also illustrates use of the station/location name autocompletion feature, included in the high-level C API.


paul@stjohnspoint.co.uk