[Back to Touch & Go]

Understanding the Touch & Go Data Model

This web page documents the data model that underpins the Touch & Go application. This data model is probably best considered to be a logical data model as it captures the essential elements of the various Touch & Go data formats (e.g., Excel, XML), but does not correlate exactly to any one of them.

Consider the UML diagram below (click on the diagram to view in a separate window).

In summary: Each of the above classes is described in greater detail below, as are the various enumerations that support them.

Network

The Network class describes an entire network, including all stops, routes and services. When encoding a timetable in Excel format each file (workbook) encodes a single Network instance. Similarly, when encoding a timetable in XML format each file (document) encodes a single Network instance.

AttributeDescription
id A unique identifier for the network (timetable). For a given installation of Touch & Go, no two networks can have the same id. The recommended format for the id is <country-code>.<state-or-province>.<key>, for example au.act.airliner. If your network is not registered with Funky People, then perhaps use your iPhone 3G's serial number as the key component to ensure uniqueness. The id is not visible to the user.
available A boolean value to indicate if your network is still available for download; set this to false to withdraw the timetable from service.
name The name by which the network will be known to the user within Touch & Go, for example Fred's Bus Lines.
description A concise (e.g., 20 words) blurb about the network.
url The URL from which the network (timetable) is downloaded.
version The current version of the network (timetable). This is a simple integer, and counts up from 1.
regionName The name of the region serviced by the network, for example Canberra (ACT) - AU.
regionFocusLatitude The latitude of the centre-point of the (circular) region serviced by the network.
regionFocusLongitude The longitude of the centre-point of the (circular) region serviced by the network.
regionRadius The radius of the region serviced by the network, specified in metres.
imageUrl The URL from which the image for the network is downloaded. The image should be a 48 x 48 pixel PNG file.
infoUrl A URL that users can browse (e.g., in Safari) to find out more about the network; this might be the network operator's home page.
infoPhone A phone number the user can dial to get more informatino about the network.
minTangoVersion The minimum version of Touch & Go software required to install the timetable. This value is (major-version * 100) + minor-version, so for example version 1.2 has the value 102, and version 2.13 has the value 213. Currently, the only supported value is 100.

Stop

The Stop class describes a physical stop, be it a taxi rank, a bus stop, a tram stop, a train station or an airport. Where a stop is part of multiple routes, it is defined once only. However, where a stop is "on both sides of the road", it is encoded as two separate stops (i.e., one in each direction).

AttributeDescription
id A unique identifier (within the scope of the network) for the stop. This is not visible to the user.
latitude The latitude of the stop.
longitude The longitude of the stop.
range The size of the area serviced by the stop (refer StopRangeEnum). This is used to determine which stops are nearby on the "You are here" screen in Touch & Go.
type The type of stop (refer StopTypeEnum).
description A very brief description of the stop, and the "name" by which it is known to users. For example:
  • Outside 124 Smith Street
  • Opposite Post Office, Smith Street
Do not include the suburb/locality, as this is provided in the attribute below.
locality The suburb/town/locality where the stop is, for example Griffith (ACT) - AU.
enquiryKey An optional enquiry key that can be used to obtain real-time timetable information for this stop. Note, this is provided for future use.

Route

The Route class defines a path along which a vehicle can travel, but without any reference to schedule. The route's path is defined as a sequence of references to stops. Where a route operates in two directions, each direction is encoded as a separate route (but with the same name as its counterpart).

AttributeDescription
id A unique identifier (within the scope of the network) for the route. This is not visible to the user.
name The name of the route as it is known to the user, for example
  • the number 632 bus should have the name 632
  • the Townsville line train should be known as Townsville (irrespective of which direction this route is going)
When Touch & Go displays the route name it will automatically add the vehicle type (e.g., a bus route with the name 632 will be displayed as 632 Bus.
description A concise (say 5-10 words) description of the route, for example Town to City via Technology Park.
days The superset of days on which the route is active.
type The type of route (refer RouteTypeEnum).
vehicleType The type of vehicle used on this route (refer VehicleTypeEnum).
returnRoute [Reference] The return route (i.e., the route that describes this route, but running in the opposite direction).

RouteStop

The RouteStop class defines a stopping point along a route by reference to a stop (i.e., a route is defined by a sequence of stops).

AttributeDescription
sequence The sequence of this stop within the route. This is a simple integer, and counts up from 1.
stopFlags Flags that say how this route actually services this stop (refer ServiceStopFlagEnum). Individual services on this route have their own flags for each stop, and these flags (on the RouteStop class) represent the super-set of those of the services.
enquiryKey An optional enquiry key that can be used to obtain real-time timetable information for this route stopping at this stop. Note, this is provided for future use.
stop [Reference] The stop.

Service

The Service class represents a vehicle travelling along a route to a given schedule.

AttributeDescription
sequence The sequence of this service within the route. When presented as a timetable, services will be ordered by this number (not by any schedule information).
days The days on which this service runs (refer DaysEnum).

ServiceStop

The class ServiceStop defines the time at which a service is at a given stop. Within many timetables (particularly bus timetables) some stops may not have any formal schedule (e.g., the schedule only includes major stops); in this case the ServiceStop instance may be omitted from the data set (i.e., only include ServiceStop instances where there is schedule information available).

AttributeDescription
sequence The sequence of this stop within the route (used to correlate the ServiceStop to the RouteStop, especially where some ServiceStop instances are omitted from the data set).
stopFlags Flags that describe how this service actually services this stop (refer ServiceStopFlagEnum).
arriveMins The scheduled time that the service arrives at this stop, specified as minutes since midnight. Do not specify where there is no explicit schedule for this stop, or where the value is identical to departMins.
departMins The scheduled time that the service departs from this stop, specified as minutes since midnight. Do not specify where there is no explicit schedule for this stop.

Enumerations

The Touch & Go data model includes a number of enumerations

EnumerationDescription
DaysEnum Describes which days of the week a route or service operates. Where multiple values are used, they add together (e.g., WEEKEND + SUNDAY + THURSDAY = SATURDAY + SUNDAY + THURSDAY).
StopTypeEnum Describes the type of stop as one of:
  • TAXI_RANK
  • BUS_STOP
  • TRAM_STOP
  • TRAIN_STATION
  • AIRPORT
Where a single stop supports multiple functions (e.g., train station and bus stop) it should be encoded as two separate stops.
StopRangeEnum Describes the size of the area serviced by a stop as one of:
  • SMALL - currently defined as a circle of radius 1 km
  • MEDIUM - currently defined as a circle of radius 5 km
  • LARGE - currently defined as a circle of radius 50 km
The actual definition of the values SMALL, MEDIUM and LARGE may change over time.
RouteTypeEnum Describes a route as one or more of the following:
  • FREE - a free service
  • SCHOOL - a school service
  • AIRPORT - an airport shuttle
  • TOURIST - a tourist service
  • CORPORATE - a corporate (or otherwise for-private-use-only) service
  • EXPRESS - an express or commuter service
VehicleTypeEnum Describes the type of vehicle travelling on a route:
  • CAR (includes taxis)
  • BUS
  • TRAM
  • TRAIN
  • PLANE
ServiceStopFlagEnum Describes the manner in which a route or service provides service to a given stop. Multiple of the following values may be specified:
  • PICK_UP - passengers may board the vehicle at the stop
  • SET_DOWN - passengers may get off the vehicle at the stop
  • HAIL_DRIVER - the vehicle will only stop when passengers hail the driver
  • SCHEDULED - indicates that there is an actual schedule for this stop. Sometimes smaller bus stops (especially those where passengers must hail the driver) may not have an explicit schedule, with the departure time being somewhere between the stops on either side
  • INTERCHANGE - passengers can connect from one service to another at the stop