1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
## 7. Trip Schedules (calendar.txt & calendar_dates.txt)
*Each of these files are ***optional*** in a GTFS feed, but at least one
of them is ***required***.*
The `calendar.txt` file is used to indicate the range of dates on
which trips are running. It works by including a start date and a finish
date (typically a range of 3-6 months), then a marker for each day of
the week on which it operates. If there are single-day scheduling
changes that occur during this period, then the `calendar_dates.txt`
file can be used to override the schedule for each of these days.
The following table shows the specification for `calendar.txt`.
| Field | Required? | Description |
| :----- | :-------- | :---------- |
| `service_id` | Required | A unique ID for a single service. This value is referenced by trips in `trips.txt`. |
| `start_date` | Required | This indicates the start date for a given service, in `YYYYMMDD` format. |
| `end_date` | Required | This indicates the end date for a given service, in `YYYYMMDD` format. |
| `monday` | Required | Contains `1` if trips run on Mondays between the start and end dates, `0` or empty if not. |
| `tuesday` | Required | Contains `1` if trips run on Tuesdays between the start and end dates, `0` or empty if not. |
| `wednesday` | Required | Contains `1` if trips run on Wednesdays between the start and end dates, `0` or empty if not. |
| `thursday` | Required | Contains `1` if trips run on Thursdays between the start and end dates, `0` or empty if not. |
| `friday` | Required | Contains `1` if trips run on Fridays between the start and end dates, `0` or empty if not. |
| `saturday` | Required | Contains `1` if trips run on Saturdays between the start and end dates, `0` or empty if not. |
| `sunday` | Required | Contains `1` if trips run on Sundays between the start and end dates, `0` or empty if not. |
As mentioned above, the `calendar_dates.txt` file is used to define
exceptions to entries in `calendar.txt`. For instance, if a 3-month
service is specified in `calendar.txt` and a holiday lies on a Monday
during this period, then you can use calendar_dates.txt to override this
single date.
If the weekend schedule were used for a holiday, then you would add a
record to remove the regular schedule for the holiday date, and another
record to add the weekend schedule for the holiday date.
Some feeds choose only to include `calendar_dates.txt` and not
`calendar.txt`, in which case there is an "add service" record for
every service and every date in this file.
The following table shows the specification for `calendar_dates.txt`.
| Field | Required? | Description |
| :----- | :-------- | :---------- |
| `service_id` | Required | The service ID that an exception is being defined for. This is referenced in both `calendar.txt` and in `trips.txt`. Unlike `calendar.txt`, it is possible for a `service_id` value to appear multiple times in this file. |
| `date` | Required | The date for which the exception is occurring, in `YYYYMMDD` format. |
| `exception_type` | Required | This indicates whether the exception is denoting an added service (`1`) or a removed service (`2`). |
### Sample Data
The following is an extract from the `calendar.txt` file in Adelaide
Metro's GTFS feed (<https://openmobilitydata.org/p/adelaide-metro>). This
extract includes schedules from the start of 2014 until the end of March
2014.
| `service_id` | `monday` | `tuesday` | `wednesday` | `thursday` | `friday` | `saturday` | `sunday` | `start_date` | `end_date` |
| :----------- | :------- | :-------- | :---------- | :--------- | :------- | :--------- | :------- | :----------- | :--------- |
| 1 | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 20140102 | 20140331 |
| 11 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 20140102 | 20140331 |
| 12 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 20140102 | 20140331 |
Any trip in the corresponding `trips.txt` file with a `service_id`
value of `1` runs from Monday to Friday. Trips with a `service_id`
of `11` run only on Saturday, while those with `12` run only on
Sunday.
Now consider an extract from `calendar_dates.txt` from the same feed,
as shown in the following table.
| `service_id` | `date` | `exception_type` |
| ------------ | -------- | ---------------- |
| 1 | 20140127 | 2 |
| 1 | 20140310 | 2 |
| 12 | 20140127 | 1 |
| 12 | 20140310 | 1 |
The first two rows mean that on January 27 and March 10 trips with
`service_id` of `1` are not running. The final two rows mean that on
those same dates trips with `service_id` of `12` are running. This
has the following meaning:
**"On 27 January and 10 March, use the Sunday timetable instead of the
Monday-Friday timetable."**
In Adelaide, these two dates are holidays (Australia Day and Labour
Day). It is Adelaide Metro's policy to run their Sunday timetable on
public holidays, which is reflected by the above records in their
`calendar_dates.txt` file.
### Structuring Services
The case described above is the ideal case for specifying services in a
GTFS feed (dates primarily specified in `calendar.txt` with a handful
of exceptions in `calendar_dates.txt`).
Be aware that there are two other major ways that services are specified
in feeds.
1. Using only `calendar_dates.txt` and expressly including every
single date within the service range. Each of these is included as
"service added" (an `exception_type` value of `1`). The
following table shows how this might look.
| `service_id` | `date` | `exception_type` |
| :----------- | :------- | :--------------- |
| 1 | 20140102 | 1 |
| 1 | 20140103 | 1 |
| 11 | 20140104 | 1 |
| 12 | 20140105 | 1 |
2. Not using `calendar_dates.txt`, but creating many records in
`calendar.txt` instead to span various dates. The following table
shows how you can represent Monday-Friday from the sample data in
this fashion.
| `service_id` | `monday` | `tuesday` | `wednesday` | `thursday` | `friday` | `saturday` | `sunday` | `start_date` | `end_date` |
| :----------- | :------- | :-------- | :---------- | :--------- | :------- | :--------- | :------- | :----------- | :--------- |
| 1a | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 20140102 | 20140126 |
| holiday1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 20140127 | 20140127 |
| 1b | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 20140128 | 20140309 |
| holiday2 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 20140310 | 20140310 |
| 1c | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 20140311 | 20140331 |
In this example, each holiday has its own row in `calendar.txt` that
runs for a single day only.
Refer to *Finding Service IDs* to see how to determine
services that are running for a given day.
### Service Name
There are a number of feeds that specify a column in `calendar.txt`
called `service_name`. This is used to give a descriptive name to each
service. For example, the Sedona Roadrunner in Arizona
(<https://openmobilitydata.org/p/sedona-roadrunner>) has services called
"Weekday Service", "Weekend Service" and "New Year's Eve Service".
|
