transx2gtfs

transx2gtfs is a library for converting public transport data from TransXchange -format (data standard in UK) into a widely used GTFS -format that can be used with various routing engines such as OpenTripPlanner.

Note!

This package is still in a Beta-phase, so use it at your own risk. If you find an issue, you can contribute and help solving them by raising an issue.

Features

• Reads TransXchange xml-files and converts into GTFS feed with all necessary information according the General Transit Feed Specification.
• Works and tested against different TransXchange schemas (TfL schema and TXC 2.1)
• Combines multiple TransXchange files into a single GTFS feed if present in the same folder.
• Finds and reads all XML files present in ZipFiles, nested ZipFiles and unpacked directories.
• Uses multiprocessing to parallelize the conversion process.
• Parses bank holidays (from gov.uk) affecting transit operations at the given time span of the TransXChange feed, which are written to calendar_dates.txt.
• Reads stop information automatically from the NaPTAN API (or from a local NaPTAN CSV file).

Why yet another converter?

There are numerous TransXChange to GTFS converters written in different programming languages. However, after testing many of them, it was hard to find a tool that would:

1. work in general (without ad-hoc modifications)
2. parse all important information from the TransXChange according GTFS specification.
3. work with different TransXChange schema versions
4. be well maintained
5. be easy to use in all operating systems
6. include appropriate tests (crucial for maintenance).

Hence, this Python package was written which aims at meeting the aforementioned requirements. It's not the fastest library out there (written in Python) but multiprocessing gives a bit of boost if having a decent computer with multiple cores.

Install

The package is available at PyPI and you can install it with:

$ pip install transx2gtfs

transx2gtfs requires Python 3.10 or newer and is tested on Python 3.10–3.14 on Linux, macOS and Windows.

If you don't know how to install Python, you can take a look for example these materials.

Requirements

transx2gtfs depends on:

• pandas (>= 2.0)
• pyproj (>= 3.0)
• untangle

Basic usage

After you have installed the library you can use it in a following manner:

>>> import transx2gtfs
>>> data_dir_for_transxchange_files = "data/my_transxchange_files"
>>> output_path = "data/my_converted_gtfs.zip"
>>> transx2gtfs.convert(data_dir_for_transxchange_files, output_path)

There are a few parameters that you can adjust:

input_filepath : str
    File path to data directory or a ZipFile containing one or multiple TransXchange .xml files.
    Also nested ZipFiles are supported (i.e. a ZipFile with ZipFile(s) containing .xml files.)

output_filepath : str
    Full filepath to the output GTFS zip-file, e.g. '/home/myuser/data/my_gtfs.zip'

append_to_existing : bool (default is False)
    Flag for appending to existing gtfs-database. This might be useful if you have
    TransXchange .xml files distributed into multiple directories (e.g. separate files for
    train data, tube data and bus data) and you want to merge all those datasets into a single
    GTFS feed.

worker_cnt : int
    Number of worker processes. By default the number of CPUs minus one is used.

file_size_limit : int
    File size limit (in megabytes) can be used to skip larger-than-memory XML-files (should not happen).

The conversion runs in worker processes. On macOS and Windows those are started with the spawn method, so when you call convert() from a script, put the call under an if __name__ == "__main__": guard:

import transx2gtfs

if __name__ == "__main__":
    transx2gtfs.convert("data/my_transxchange_files", "data/my_converted_gtfs.zip")

Command line

The same conversion is available from the command line (transx2gtfs or python -m transx2gtfs):

$ transx2gtfs data/my_transxchange_files data/my_converted_gtfs.zip
$ transx2gtfs --help

Options: --append (append to the intermediate database of a previous run), --workers N, --file-size-limit MB and --version.

Stop and bank holiday data

Stop coordinates are read from the national NaPTAN dataset, which is downloaded once (about 100 MB) into the system temp directory and reused on later runs. To use a local copy instead (for example when working offline), point TRANSX2GTFS_NAPTAN_PATH at a NaPTAN CSV file downloaded from https://naptan.api.dft.gov.uk/v1/access-nodes?dataFormat=csv. Bank holidays are read from gov.uk, falling back to a copy bundled with the package; TRANSX2GTFS_BANK_HOLIDAYS_PATH can point at a local copy of that JSON file.

Output

After you have successfully converted the TransXchange into GTFS, you can start doing multimodal routing with your favourite routing engine such as OpenTripPlanner:

Citation

If you use this tool for research purposes, we encourage you to cite this work:

• Henrikki Tenkanen. (2020). transx2gtfs (Version v0.4.0). Zenodo. http://doi.org/10.5281/zenodo.3631972

Developers

• Henrikki Tenkanen, Aalto University

Development setup

$ git clone https://github.com/HTenkanen/transx2gtfs.git
$ cd transx2gtfs
$ pip install -e .[test]
$ pytest

The tests run offline: stops come from a small NaPTAN subset in tests/data/ and bank holidays from the bundled file. Code is formatted with black and checked with flake8 (pre-commit install sets up both as git hooks).