[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:
- the entire timetable is represented by the class Network
- the timetable includes a master list of all stops (class Stop) from across
all of its routes
- the timetable includes a number of routes (class Route). Each route is essentially
a path along which a vehicle can travel, and is defined by a sequence of stops
(class RouteStop). The route does not include any schedule information
- for each route there will be a number of services (class Service), essentially a vehicle
travelling on the route according to a schedule (the arrival/departure time for each stop is
defined in the class ServiceStop)
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.
| Attribute | Description |
|---|
| 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).
| Attribute | Description |
|---|
| 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).
| Attribute | Description |
|---|
| 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).
| Attribute | Description |
|---|
| 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.
| Attribute | Description |
|---|
| 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).
| Attribute | Description |
|---|
| 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
| Enumeration | Description |
|---|
| 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
|
In summary: