|
Maxious
|
1 |
// Copyright 2010 Google Inc |
|
|
2 |
// |
|
|
3 |
// The content of this file is licensed under the Creative Commons Attribution |
|
|
4 |
// 3.0 License. |
|
|
5 |
// |
|
|
6 |
// Protocol definition file for GTFS-realtime. |
|
|
7 |
// |
|
|
8 |
// GTFS-realtime lets transit agencies provide consumers with realtime |
|
|
9 |
// information about disruptions to their service (stations closed, lines not |
|
|
10 |
// operating, important delays etc), location of their vehicles and expected |
|
|
11 |
// arrival times. |
|
|
12 |
// |
|
|
13 |
// This protocol is published on http://code.google.com/transit/realtime/ . |
|
|
14 |
|
|
|
15 |
syntax = "proto2"; |
|
|
16 |
|
|
|
17 |
option cc_api_version = 2; |
|
|
18 |
option py_api_version = 1; |
|
|
19 |
|
|
|
20 |
option java_package = "com.google.transit.realtime"; |
|
|
21 |
package transit_realtime; |
|
|
22 |
|
|
|
23 |
// The contents of a feed message. |
|
|
24 |
// A feed is a continuous stream of feed messages. Each message in the stream is |
|
|
25 |
// obtained as a response to an appropriate HTTP GET request. |
|
|
26 |
// A realtime feed is always defined with relation to an existing GTFS feed. |
|
|
27 |
// All the entity ids are resolved with respect to the GTFS feed. |
|
|
28 |
// |
|
|
29 |
// A feed depends on some external configuration: |
|
|
30 |
// - The corresponding GTFS feed. |
|
|
31 |
// - Feed application (updates, positions or alerts). A feed should contain only |
|
|
32 |
// items of one specified application; all the other entities will be ignored. |
|
|
33 |
// - Polling frequency |
|
|
34 |
message FeedMessage { |
|
|
35 |
// Metadata about this feed and feed message. |
|
|
36 |
required FeedHeader header = 1; |
|
|
37 |
|
|
|
38 |
// Contents of the feed. |
|
|
39 |
repeated FeedEntity entity = 2; |
|
|
40 |
} |
|
|
41 |
|
|
|
42 |
// Metadata about a feed, included in feed messages. |
|
|
43 |
message FeedHeader { |
|
|
44 |
// Version of the feed specification. |
|
|
45 |
// The current version is 1.0. |
|
|
46 |
required string gtfs_realtime_version = 1; |
|
|
47 |
|
|
|
48 |
// Determines whether the current fetch is incremental. |
|
|
49 |
enum Incrementality { |
|
|
50 |
FULL_DATASET = 0; |
|
|
51 |
DIFFERENTIAL = 1; |
|
|
52 |
} |
|
|
53 |
optional Incrementality incrementality = 2 [default = FULL_DATASET]; |
|
|
54 |
|
|
|
55 |
// This timestamp identifies the moment when the content of this feed has been |
|
|
56 |
// created (in server time). In POSIX time (i.e., number of seconds since |
|
|
57 |
// January 1st 1970 00:00:00 UTC). |
|
|
58 |
optional uint64 timestamp = 3; |
|
|
59 |
} |
|
|
60 |
|
|
|
61 |
// A definition (or update) of an entity in the transit feed. |
|
|
62 |
message FeedEntity { |
|
|
63 |
// The ids are used only to provide incrementality support. The id should be |
|
|
64 |
// unique within a FeedMessage. Consequent FeedMessages may contain |
|
|
65 |
// FeedEntities with the same id. In case of a DIFFERENTIAL update the new |
|
|
66 |
// FeedEntity with some id will replace the old FeedEntity with the same id |
|
|
67 |
// (or delete it - see is_deleted below). |
|
|
68 |
// The actual GTFS entities (e.g. stations, routes, trips) referenced by the |
|
|
69 |
// feed must be specified by explicit selectors (see EntitySelector below for |
|
|
70 |
// more info). |
|
|
71 |
required string id = 1; |
|
|
72 |
|
|
|
73 |
// Whether this entity is to be deleted. Relevant only for incremental |
|
|
74 |
// fetches. |
|
|
75 |
optional bool is_deleted = 2 [default = false]; |
|
|
76 |
|
|
|
77 |
// Data about the entity itself. Exactly one of the following fields must be |
|
|
78 |
// present (unless the entity is being deleted). |
|
|
79 |
optional TripUpdate trip_update = 3; |
|
|
80 |
optional VehiclePosition vehicle = 4; |
|
|
81 |
optional Alert alert = 5; |
|
|
82 |
} |
|
|
83 |
|
|
|
84 |
// |
|
|
85 |
// Entities used in the feed. |
|
|
86 |
// |
|
|
87 |
|
|
|
88 |
// Realtime update of the progress of a vehicle along a trip. |
|
|
89 |
// Depending on the value of ScheduleRelationship, a TripUpdate can specify: |
|
|
90 |
// - A trip that proceeds along the schedule. |
|
|
91 |
// - A trip that proceeds along a route but has no fixed schedule. |
|
|
92 |
// - A trip that have been added or removed with regard to schedule. |
|
|
93 |
// |
|
|
94 |
// The updates can be for future, predicted arrival/departure events, or for |
|
|
95 |
// past events that already occurred. |
|
|
96 |
// Normally, updates should get more precise and more certain (see |
|
|
97 |
// uncertainty below) as the events gets closer to current time. |
|
|
98 |
// Even if that is not possible, the information for past events should be |
|
|
99 |
// precise and certain. In particular, if an update points to time in the past |
|
|
100 |
// but its update's uncertainty is not 0, the client should conclude that the |
|
|
101 |
// update is a (wrong) prediction and that the trip has not completed yet. |
|
|
102 |
// |
|
|
103 |
// Note that the update can describe a trip that is already completed. |
|
|
104 |
// To this end, it is enough to provide an update for the last stop of the trip. |
|
|
105 |
// If the time of that is in the past, the client will conclude from that that |
|
|
106 |
// the whole trip is in the past (it is possible, although inconsequential, to |
|
|
107 |
// also provide updates for preceding stops). |
|
|
108 |
// This option is most relevant for a trip that has completed ahead of schedule, |
|
|
109 |
// but according to the schedule, the trip is still proceeding at the current |
|
|
110 |
// time. Removing the updates for this trip could make the client assume |
|
|
111 |
// that the trip is still proceeding. |
|
|
112 |
// Note that the feed provider is allowed, but not required, to purge past |
|
|
113 |
// updates - this is one case where this would be practically useful. |
|
|
114 |
message TripUpdate { |
|
|
115 |
// The Trip that this message applies to. There can be at most one |
|
|
116 |
// TripUpdate entity for each actual trip instance. |
|
|
117 |
// If there is none, that means there is no prediction information available. |
|
|
118 |
// It does *not* mean that the trip is progressing according to schedule. |
|
|
119 |
required TripDescriptor trip = 1; |
|
|
120 |
|
|
|
121 |
// Additional information on the vehicle that is serving this trip. |
|
|
122 |
optional VehicleDescriptor vehicle = 3; |
|
|
123 |
|
|
|
124 |
// Timing information for a single predicted event (either arrival or |
|
|
125 |
// departure). |
|
|
126 |
// Timing consists of delay and/or estimated time, and uncertainty. |
|
|
127 |
// - delay should be used when the prediction is given relative to some |
|
|
128 |
// existing schedule in GTFS. |
|
|
129 |
// - time should be given whether there is a predicted schedule or not. If |
|
|
130 |
// both time and delay are specified, time will take precedence |
|
|
131 |
// (although normally, time, if given for a scheduled trip, should be |
|
|
132 |
// equal to scheduled time in GTFS + delay). |
|
|
133 |
// |
|
|
134 |
// Uncertainty applies equally to both time and delay. |
|
|
135 |
// The uncertainty roughly specifies the expected error in true delay (but |
|
|
136 |
// note, we don't yet define its precise statistical meaning). It's possible |
|
|
137 |
// for the uncertainty to be 0, for example for trains that are driven under |
|
|
138 |
// computer timing control. |
|
|
139 |
message StopTimeEvent { |
|
|
140 |
// Delay (in seconds) can be positive (meaning that the vehicle is late) or |
|
|
141 |
// negative (meaning that the vehicle is ahead of schedule). Delay of 0 |
|
|
142 |
// means that the vehicle is exactly on time. |
|
|
143 |
optional int32 delay = 1; |
|
|
144 |
|
|
|
145 |
// Event as absolute time. |
|
|
146 |
// In Unix time (i.e., number of seconds since January 1st 1970 00:00:00 |
|
|
147 |
// UTC). |
|
|
148 |
optional int64 time = 2; |
|
|
149 |
|
|
|
150 |
// If uncertainty is omitted, it is interpreted as unknown. |
|
|
151 |
// If the prediction is unknown or too uncertain, the delay (or time) field |
|
|
152 |
// should be empty. In such case, the uncertainty field is ignored. |
|
|
153 |
// To specify a completely certain prediction, set its uncertainty to 0. |
|
|
154 |
optional int32 uncertainty = 3; |
|
|
155 |
} |
|
|
156 |
|
|
|
157 |
// Realtime update for arrival and/or departure events for a given stop on a |
|
|
158 |
// trip. Updates can be supplied for both past and future events. |
|
|
159 |
// The producer is allowed, although not required, to drop past events. |
|
|
160 |
message StopTimeUpdate { |
|
|
161 |
// The update is linked to a specific stop either through stop_sequence or |
|
|
162 |
// stop_id, so one of the fields below must necessarily be set. |
|
|
163 |
// See the documentation in TripDescriptor for more information. |
|
|
164 |
|
|
|
165 |
// Must be the same as in stop_times.txt in the corresponding GTFS feed. |
|
|
166 |
optional uint32 stop_sequence = 1; |
|
|
167 |
// Must be the same as in stops.txt in the corresponding GTFS feed. |
|
|
168 |
optional string stop_id = 4; |
|
|
169 |
|
|
|
170 |
optional StopTimeEvent arrival = 2; |
|
|
171 |
optional StopTimeEvent departure = 3; |
|
|
172 |
|
|
|
173 |
// The relation between this StopTime and the static schedule. |
|
|
174 |
enum ScheduleRelationship { |
|
|
175 |
// The vehicle is proceeding in accordance with its static schedule of |
|
|
176 |
// stops, although not necessarily according to the times of the schedule. |
|
|
177 |
// At least one of arrival and departure must be provided. If the schedule |
|
|
178 |
// for this stop contains both arrival and departure times then so must |
|
|
179 |
// this update. An update with only an arrival, say, where the schedule |
|
|
180 |
// has both, indicates that the trip is terminating early at this stop. |
|
|
181 |
SCHEDULED = 0; |
|
|
182 |
|
|
|
183 |
// The stop is skipped, i.e., the vehicle will not stop at this stop. |
|
|
184 |
// Arrival and departure are optional. |
|
|
185 |
SKIPPED = 1; |
|
|
186 |
|
|
|
187 |
// No data is given for this stop. The main intention for this value is to |
|
|
188 |
// give the predictions only for part of a trip, i.e., if the last update |
|
|
189 |
// for a trip has a NO_DATA specifier, then StopTimes for the rest of the |
|
|
190 |
// stops in the trip are considered to be unspecified as well. |
|
|
191 |
// Neither arrival nor departure should be supplied. |
|
|
192 |
NO_DATA = 2; |
|
|
193 |
} |
|
|
194 |
optional ScheduleRelationship schedule_relationship = 5 |
|
|
195 |
[default = SCHEDULED]; |
|
|
196 |
} |
|
|
197 |
|
|
|
198 |
// Updates to StopTimes for the trip (both future, i.e., predictions, and in |
|
|
199 |
// some cases, past ones, i.e., those that already happened). |
|
|
200 |
// The updates must be sorted by stop_sequence, and apply for all the |
|
|
201 |
// following stops of the trip up to the next specified one. |
|
|
202 |
// |
|
|
203 |
// Example 1: |
|
|
204 |
// For a trip with 20 stops, a StopTimeUpdate with arrival delay and departure |
|
|
205 |
// delay of 0 for stop_sequence of the current stop means that the trip is |
|
|
206 |
// exactly on time. |
|
|
207 |
// |
|
|
208 |
// Example 2: |
|
|
209 |
// For the same trip instance, 3 StopTimeUpdates are provided: |
|
|
210 |
// - delay of 5 min for stop_sequence 3 |
|
|
211 |
// - delay of 1 min for stop_sequence 8 |
|
|
212 |
// - delay of unspecified duration for stop_sequence 10 |
|
|
213 |
// This will be interpreted as: |
|
|
214 |
// - stop_sequences 3,4,5,6,7 have delay of 5 min. |
|
|
215 |
// - stop_sequences 8,9 have delay of 1 min. |
|
|
216 |
// - stop_sequences 10,... have unknown delay. |
|
|
217 |
repeated StopTimeUpdate stop_time_update = 2; |
|
|
218 |
} |
|
|