TRAFFIC

TRAFFIC (Transport Related Augmented File Format Improved & Corrected) is a data format used to represent public transport timetables and related information. Apart from defining format for data at rest, TRAFFIC describes an API used to exchange information between providers and clients. TRAFFIC is inspired by GTFS, but it’s more concise and not human-readable; data can be converted from GTFS format to TRAFFIC, and TRAFFIC is compatible with GTFS Realtime.

Comments are solicited and should be addressed to the mailing list at traffic@git.apiote.xyz.

Copyright (c) Adam Evyčędo

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

The primary goal set before authors of TRAFFIC is ease of use—for both, users of clients, and programmers implementing the spec. This encompasses practicality and simplicity; TRAFFIC was created to be used even on less powerful devices. That’s why TRAFFIC employs multiple indices, and—with the use of modern data structures—timetables use space more efficiently.

TRAFFIC is not meant to replace GTFS—indeed, it works in tandem with GTFS Realtime—and does not fully implement all edge cases covered by GTFS. With time, when more and more schedules will be used by TRAFFIC servers, the specification will cover more and more real-world cases, but the goal of making passengers’ lives easier will always be first.

5.1. Difference from GTFS

TRAFFIC versions are named and not numbered. Each version name starts with next letter of English alphabet and versions are named after metro lines. Data format is not backwards compatible between versions. API is backwards compatible; single version of API defines one or more versions of responses. Clients MUST include accept headers with versions of responses they understand and server MUST respond with the most recent version that both the client asked for and the server can produce, or send an error response if agreement is not possible. As an exception, version 0 is reserved for development and MUST be sent by server if requested, irrelevant of the highest version the server can produce.

• Timetable is a collection of information valid for specific time in one feed.

• Line is what GTFS names a Route

• Stop is a specific point where a vehicle stops to pick up or drop passengers. It may be further subdivided into platforms. Stop’s name SHOULD contain the shortest ID distinguishing it from other stops of the same node.

• Node is an abstract collection of stops. For stops to be part of the same node, they must have the same stop_name in stops.txt file of GTFS feed.

• Stop code is a stable identifier, one that doesn’t change between timetable changes. It may, for example, be used in 2D codes at stops, that link to a website with realtime departures for this stop.

TRAFFIC file consists of multiple files defined below, packed into an xz compressed tar archive. Each TRAFFIC file name must end with two dates in format YYYYMMDD separated by _ which denote first and last day of the timetable validity, followed by .tar.xz or .txz extension.

8.1. Files definitions

CREATE TABLE ix_trips(code text primary key, offset integer);
CREATE TABLE ix_stop_names(name text, offset integer);
CREATE INDEX ix_ix_stop_names on ix_stop_names(name);
CREATE TABLE ix_stop_codes(code text primary key, offset integer);
CREATE TABLE ix_lines(name text, offset integer);
CREATE INDEX ix_ix_lines on ix_lines(name);
CREATE TABLE ix_line_codes(code text primary key, offset integer);

8.2. Lua scripts

API is defined as OpenAPI spec v3.1.0 in file api/api.yml and data structure is defined as BARE schema in file api/api.bare. The spec is extended in following ways:

• added types

• added formats to types which correspond to primitive types used in BARE encoding

• added generic formats to types

• added keys keys and items to type object. Such object defines a map.

9.1. API specification customisation

9.2. Transport layer

Downtown is on of Singapore Mass Rapid Transit lines. It runs from Bukit Panjang station in the north-west of the country towards Expo station in the east via a loop around the city-centre for almost 42 km over 34 stations, with 2.2 km and 3 stations under construction, and another station in planning.

Clockwork Orange is an unofficial tourist name of Glasgow Subway (Fo-thalamh Ghlaschu). It consists of Outer and Inner Circle lines going the same route clockwise and couterclockwise respectively. The trains travel between 15 stations for 10.5 kilometers.

Batong (北京地铁八通线) is one of Beijing Subway lines. This line extends Line 1. It has 15 stations, is over 23 km long but runs only about 4 km underground. It will take you to the Universal Beijing Resort.

AREX (Airport Railroad Express, 인천국제공항철도) is one of Seoul metro lines. It has 14 stations, is over 63 km long and was opened in 2007. It will take you from Seoul Station to Incheon Airport and back.