aboutsummaryrefslogtreecommitdiff
path: root/gtfs-realtime.proto
blob: 6f243d28e34ddba0c28967694134b4fa6c84faa4 (plain)
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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
// Copyright 2015 The GTFS Specifications Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Protocol definition file for GTFS Realtime.
//
// GTFS Realtime lets transit agencies provide consumers with realtime
// information about disruptions to their service (stations closed, lines not
// operating, important delays etc), location of their vehicles and expected
// arrival times.
//
// This protocol is published at:
// https://github.com/google/transit/tree/master/gtfs-realtime

syntax = "proto2";
option java_package = "GTFS.realtime";
package transit_realtime;

// The contents of a feed message.
// A feed is a continuous stream of feed messages. Each message in the stream is
// obtained as a response to an appropriate HTTP GET request.
// A realtime feed is always defined with relation to an existing GTFS feed.
// All the entity ids are resolved with respect to the GTFS feed.
// Note that "required" and "optional" as stated in this file refer to Protocol
// Buffer cardinality, not semantic cardinality.  See reference.md at
// https://github.com/google/transit/tree/master/gtfs-realtime for field
// semantic cardinality.
message FeedMessage {
  // Metadata about this feed and feed message.
  required FeedHeader header = 1;

  // Contents of the feed.
  repeated FeedEntity entity = 2;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// Metadata about a feed, included in feed messages.
message FeedHeader {
  // Version of the feed specification.
  // The current version is 2.0.  Valid versions are "2.0", "1.0".
  required string gtfs_realtime_version = 1;

  // Determines whether the current fetch is incremental.  Currently,
  // DIFFERENTIAL mode is unsupported and behavior is unspecified for feeds
  // that use this mode.  There are discussions on the GTFS Realtime mailing
  // list around fully specifying the behavior of DIFFERENTIAL mode and the
  // documentation will be updated when those discussions are finalized.
  enum Incrementality {
    FULL_DATASET = 0;
    DIFFERENTIAL = 1;
  }
  optional Incrementality incrementality = 2 [default = FULL_DATASET];

  // This timestamp identifies the moment when the content of this feed has been
  // created (in server time). In POSIX time (i.e., number of seconds since
  // January 1st 1970 00:00:00 UTC).
  optional uint64 timestamp = 3;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// A definition (or update) of an entity in the transit feed.
message FeedEntity {
  // The ids are used only to provide incrementality support. The id should be
  // unique within a FeedMessage. Consequent FeedMessages may contain
  // FeedEntities with the same id. In case of a DIFFERENTIAL update the new
  // FeedEntity with some id will replace the old FeedEntity with the same id
  // (or delete it - see is_deleted below).
  // The actual GTFS entities (e.g. stations, routes, trips) referenced by the
  // feed must be specified by explicit selectors (see EntitySelector below for
  // more info).
  required string id = 1;

  // Whether this entity is to be deleted. Relevant only for incremental
  // fetches.
  optional bool is_deleted = 2 [default = false];

  // Data about the entity itself. Exactly one of the following fields must be
  // present (unless the entity is being deleted).
  optional TripUpdate trip_update = 3;
  optional VehiclePosition vehicle = 4;
  optional Alert alert = 5;

  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional Shape shape = 6;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

//
// Entities used in the feed.
//

// Realtime update of the progress of a vehicle along a trip.
// Depending on the value of ScheduleRelationship, a TripUpdate can specify:
// - A trip that proceeds along the schedule.
// - A trip that proceeds along a route but has no fixed schedule.
// - A trip that have been added or removed with regard to schedule.
//
// The updates can be for future, predicted arrival/departure events, or for
// past events that already occurred.
// Normally, updates should get more precise and more certain (see
// uncertainty below) as the events gets closer to current time.
// Even if that is not possible, the information for past events should be
// precise and certain. In particular, if an update points to time in the past
// but its update's uncertainty is not 0, the client should conclude that the
// update is a (wrong) prediction and that the trip has not completed yet.
//
// Note that the update can describe a trip that is already completed.
// To this end, it is enough to provide an update for the last stop of the trip.
// If the time of that is in the past, the client will conclude from that that
// the whole trip is in the past (it is possible, although inconsequential, to
// also provide updates for preceding stops).
// This option is most relevant for a trip that has completed ahead of schedule,
// but according to the schedule, the trip is still proceeding at the current
// time. Removing the updates for this trip could make the client assume
// that the trip is still proceeding.
// Note that the feed provider is allowed, but not required, to purge past
// updates - this is one case where this would be practically useful.
message TripUpdate {
  // The Trip that this message applies to. There can be at most one
  // TripUpdate entity for each actual trip instance.
  // If there is none, that means there is no prediction information available.
  // It does *not* mean that the trip is progressing according to schedule.
  required TripDescriptor trip = 1;

  // Additional information on the vehicle that is serving this trip.
  optional VehicleDescriptor vehicle = 3;

  // Timing information for a single predicted event (either arrival or
  // departure).
  // Timing consists of delay and/or estimated time, and uncertainty.
  // - delay should be used when the prediction is given relative to some
  //   existing schedule in GTFS.
  // - time should be given whether there is a predicted schedule or not. If
  //   both time and delay are specified, time will take precedence
  //   (although normally, time, if given for a scheduled trip, should be
  //   equal to scheduled time in GTFS + delay).
  //
  // Uncertainty applies equally to both time and delay.
  // The uncertainty roughly specifies the expected error in true delay (but
  // note, we don't yet define its precise statistical meaning). It's possible
  // for the uncertainty to be 0, for example for trains that are driven under
  // computer timing control.
  message StopTimeEvent {
    // Delay (in seconds) can be positive (meaning that the vehicle is late) or
    // negative (meaning that the vehicle is ahead of schedule). Delay of 0
    // means that the vehicle is exactly on time.
    optional int32 delay = 1;

    // Event as absolute time.
    // In Unix time (i.e., number of seconds since January 1st 1970 00:00:00
    // UTC).
    optional int64 time = 2;

    // If uncertainty is omitted, it is interpreted as unknown.
    // If the prediction is unknown or too uncertain, the delay (or time) field
    // should be empty. In such case, the uncertainty field is ignored.
    // To specify a completely certain prediction, set its uncertainty to 0.
    optional int32 uncertainty = 3;

    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features
    // and modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }

  // Realtime update for arrival and/or departure events for a given stop on a
  // trip. Updates can be supplied for both past and future events.
  // The producer is allowed, although not required, to drop past events.
  message StopTimeUpdate {
    // The update is linked to a specific stop either through stop_sequence or
    // stop_id, so one of the fields below must necessarily be set.
    // See the documentation in TripDescriptor for more information.

    // Must be the same as in stop_times.txt in the corresponding GTFS feed.
    optional uint32 stop_sequence = 1;
    // Must be the same as in stops.txt in the corresponding GTFS feed.
    optional string stop_id = 4;

    optional StopTimeEvent arrival = 2;
    optional StopTimeEvent departure = 3;

    // Expected occupancy after departure from the given stop.
    // Should be provided only for future stops.
    // In order to provide departure_occupancy_status without either arrival or
    // departure StopTimeEvents, ScheduleRelationship should be set to NO_DATA. 
    optional VehiclePosition.OccupancyStatus departure_occupancy_status = 7;
    
    // The relation between the StopTimeEvents and the static schedule.
    enum ScheduleRelationship {
      // The vehicle is proceeding in accordance with its static schedule of
      // stops, although not necessarily according to the times of the schedule.
      // At least one of arrival and departure must be provided. If the schedule
      // for this stop contains both arrival and departure times then so must
      // this update. Frequency-based trips (GTFS frequencies.txt with exact_times = 0)
      // should not have a SCHEDULED value and should use UNSCHEDULED instead.
      SCHEDULED = 0;

      // The stop is skipped, i.e., the vehicle will not stop at this stop.
      // Arrival and departure are optional.
      SKIPPED = 1;

      // No StopTimeEvents are given for this stop.
      // The main intention for this value is to give time predictions only for
      // part of a trip, i.e., if the last update for a trip has a NO_DATA
      // specifier, then StopTimeEvents for the rest of the stops in the trip
      // are considered to be unspecified as well.
      // Neither arrival nor departure should be supplied.
      NO_DATA = 2;

      // The vehicle is operating a trip defined in GTFS frequencies.txt with exact_times = 0.
      // This value should not be used for trips that are not defined in GTFS frequencies.txt,
      // or trips in GTFS frequencies.txt with exact_times = 1. Trips containing StopTimeUpdates
      // with ScheduleRelationship=UNSCHEDULED must also set TripDescriptor.ScheduleRelationship=UNSCHEDULED.
      // NOTE: This field is still experimental, and subject to change. It may be
      // formally adopted in the future.
      UNSCHEDULED = 3;
    }
    optional ScheduleRelationship schedule_relationship = 5
        [default = SCHEDULED];

    // Provides the updated values for the stop time.
    // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future.
    message StopTimeProperties {
      // Supports real-time stop assignments. Refers to a stop_id defined in the GTFS stops.txt.
      // The new assigned_stop_id should not result in a significantly different trip experience for the end user than
      // the stop_id defined in GTFS stop_times.txt. In other words, the end user should not view this new stop_id as an
      // "unusual change" if the new stop was presented within an app without any additional context.
      // For example, this field is intended to be used for platform assignments by using a stop_id that belongs to the
      // same station as the stop originally defined in GTFS stop_times.txt.
      // To assign a stop without providing any real-time arrival or departure predictions, populate this field and set
      // StopTimeUpdate.schedule_relationship = NO_DATA.
      // If this field is populated, it is preferred to omit `StopTimeUpdate.stop_id` and use only `StopTimeUpdate.stop_sequence`. If
      // `StopTimeProperties.assigned_stop_id` and `StopTimeUpdate.stop_id` are populated, `StopTimeUpdate.stop_id` must match `assigned_stop_id`.
      // Platform assignments should be reflected in other GTFS-realtime fields as well
      // (e.g., `VehiclePosition.stop_id`).
      // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
      optional string assigned_stop_id = 1;

      // The extensions namespace allows 3rd-party developers to extend the
      // GTFS Realtime Specification in order to add and evaluate new features
      // and modifications to the spec.
      extensions 1000 to 1999;

      // The following extension IDs are reserved for private use by any organization.
      extensions 9000 to 9999;
    }

    // Realtime updates for certain properties defined within GTFS stop_times.txt
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
    optional StopTimeProperties stop_time_properties = 6;

    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features
    // and modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }

  // Updates to StopTimes for the trip (both future, i.e., predictions, and in
  // some cases, past ones, i.e., those that already happened).
  // The updates must be sorted by stop_sequence, and apply for all the
  // following stops of the trip up to the next specified one.
  //
  // Example 1:
  // For a trip with 20 stops, a StopTimeUpdate with arrival delay and departure
  // delay of 0 for stop_sequence of the current stop means that the trip is
  // exactly on time.
  //
  // Example 2:
  // For the same trip instance, 3 StopTimeUpdates are provided:
  // - delay of 5 min for stop_sequence 3
  // - delay of 1 min for stop_sequence 8
  // - delay of unspecified duration for stop_sequence 10
  // This will be interpreted as:
  // - stop_sequences 3,4,5,6,7 have delay of 5 min.
  // - stop_sequences 8,9 have delay of 1 min.
  // - stop_sequences 10,... have unknown delay.
  repeated StopTimeUpdate stop_time_update = 2;

  // The most recent moment at which the vehicle's real-time progress was measured
  // to estimate StopTimes in the future. When StopTimes in the past are provided,
  // arrival/departure times may be earlier than this value. In POSIX
  // time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC).
  optional uint64 timestamp = 4;

  // The current schedule deviation for the trip.  Delay should only be
  // specified when the prediction is given relative to some existing schedule
  // in GTFS.
  //
  // Delay (in seconds) can be positive (meaning that the vehicle is late) or
  // negative (meaning that the vehicle is ahead of schedule). Delay of 0
  // means that the vehicle is exactly on time.
  //
  // Delay information in StopTimeUpdates take precedent of trip-level delay
  // information, such that trip-level delay is only propagated until the next
  // stop along the trip with a StopTimeUpdate delay value specified.
  //
  // Feed providers are strongly encouraged to provide a TripUpdate.timestamp
  // value indicating when the delay value was last updated, in order to
  // evaluate the freshness of the data.
  //
  // NOTE: This field is still experimental, and subject to change. It may be
  // formally adopted in the future.
  optional int32 delay = 5;

  // Defines updated properties of the trip, such as a new shape_id when there is a detour. Or defines the
  // trip_id, start_date, and start_time of a DUPLICATED trip. 
  // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future.
  message TripProperties {
    // Defines the identifier of a new trip that is a duplicate of an existing trip defined in (CSV) GTFS trips.txt
    // but will start at a different service date and/or time (defined using the TripProperties.start_date and
    // TripProperties.start_time fields). See definition of trips.trip_id in (CSV) GTFS. Its value must be different
    // than the ones used in the (CSV) GTFS. Required if schedule_relationship=DUPLICATED, otherwise this field must not
    // be populated and will be ignored by consumers.
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
    optional string trip_id = 1;
    // Service date on which the DUPLICATED trip will be run, in YYYYMMDD format. Required if
    // schedule_relationship=DUPLICATED, otherwise this field must not be populated and will be ignored by consumers.
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
    optional string start_date = 2;
    // Defines the departure start time of the trip when it’s duplicated. See definition of stop_times.departure_time
    // in (CSV) GTFS. Scheduled arrival and departure times for the duplicated trip are calculated based on the offset
    // between the original trip departure_time and this field. For example, if a GTFS trip has stop A with a
    // departure_time of 10:00:00 and stop B with departure_time of 10:01:00, and this field is populated with the value
    // of 10:30:00, stop B on the duplicated trip will have a scheduled departure_time of 10:31:00. Real-time prediction
    // delay values are applied to this calculated schedule time to determine the predicted time. For example, if a
    // departure delay of 30 is provided for stop B, then the predicted departure time is 10:31:30. Real-time
    // prediction time values do not have any offset applied to them and indicate the predicted time as provided.
    // For example, if a departure time representing 10:31:30 is provided for stop B, then the predicted departure time
    // is 10:31:30. This field is required if schedule_relationship is DUPLICATED, otherwise this field must not be
    // populated and will be ignored by consumers.
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
    optional string start_time = 3;
    // Specifies the shape of the vehicle travel path when the trip shape differs from the shape specified in
    // (CSV) GTFS or to specify it in real-time when it's not provided by (CSV) GTFS, such as a vehicle that takes differing
    // paths based on rider demand. See definition of trips.shape_id in (CSV) GTFS. If a shape is neither defined in (CSV) GTFS
    // nor in real-time, the shape is considered unknown. This field can refer to a shape defined in the (CSV) GTFS in shapes.txt
    // or a Shape in the (protobuf) real-time feed. The order of stops (stop sequences) for this trip must remain the same as
    // (CSV) GTFS. Stops that are a part of the original trip but will no longer be made, such as when a detour occurs, should
    // be marked as schedule_relationship=SKIPPED.
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. 
    optional string shape_id = 4;

    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features
    // and modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }
  optional TripProperties trip_properties = 6;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// Realtime positioning information for a given vehicle.
message VehiclePosition {
  // The Trip that this vehicle is serving.
  // Can be empty or partial if the vehicle can not be identified with a given
  // trip instance.
  optional TripDescriptor trip = 1;

  // Additional information on the vehicle that is serving this trip.
  optional VehicleDescriptor vehicle = 8;

  // Current position of this vehicle.
  optional Position position = 2;

  // The stop sequence index of the current stop. The meaning of
  // current_stop_sequence (i.e., the stop that it refers to) is determined by
  // current_status.
  // If current_status is missing IN_TRANSIT_TO is assumed.
  optional uint32 current_stop_sequence = 3;
  // Identifies the current stop. The value must be the same as in stops.txt in
  // the corresponding GTFS feed.
  optional string stop_id = 7;

  enum VehicleStopStatus {
    // The vehicle is just about to arrive at the stop (on a stop
    // display, the vehicle symbol typically flashes).
    INCOMING_AT = 0;

    // The vehicle is standing at the stop.
    STOPPED_AT = 1;

    // The vehicle has departed and is in transit to the next stop.
    IN_TRANSIT_TO = 2;
  }
  // The exact status of the vehicle with respect to the current stop.
  // Ignored if current_stop_sequence is missing.
  optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO];

  // Moment at which the vehicle's position was measured. In POSIX time
  // (i.e., number of seconds since January 1st 1970 00:00:00 UTC).
  optional uint64 timestamp = 5;

  // Congestion level that is affecting this vehicle.
  enum CongestionLevel {
    UNKNOWN_CONGESTION_LEVEL = 0;
    RUNNING_SMOOTHLY = 1;
    STOP_AND_GO = 2;
    CONGESTION = 3;
    SEVERE_CONGESTION = 4;  // People leaving their cars.
  }
  optional CongestionLevel congestion_level = 6;

  // The state of passenger occupancy for the vehicle or carriage.
  // Individual producers may not publish all OccupancyStatus values. Therefore, consumers
  // must not assume that the OccupancyStatus values follow a linear scale.
  // Consumers should represent OccupancyStatus values as the state indicated 
  // and intended by the producer. Likewise, producers must use OccupancyStatus values that
  // correspond to actual vehicle occupancy states.
  // For describing passenger occupancy levels on a linear scale, see `occupancy_percentage`.
  // This field is still experimental, and subject to change. It may be formally adopted in the future.
  enum OccupancyStatus {
    // The vehicle or carriage is considered empty by most measures, and has few or no
    // passengers onboard, but is still accepting passengers.
    EMPTY = 0;

    // The vehicle or carriage has a large number of seats available.
    // The amount of free seats out of the total seats available to be
    // considered large enough to fall into this category is determined at the
    // discretion of the producer.
    MANY_SEATS_AVAILABLE = 1;

    // The vehicle or carriage has a relatively small number of seats available.
    // The amount of free seats out of the total seats available to be
    // considered small enough to fall into this category is determined at the
    // discretion of the feed producer.
    FEW_SEATS_AVAILABLE = 2;

    // The vehicle or carriage can currently accommodate only standing passengers.
    STANDING_ROOM_ONLY = 3;

    // The vehicle or carriage can currently accommodate only standing passengers
    // and has limited space for them.
    CRUSHED_STANDING_ROOM_ONLY = 4;

    // The vehicle or carriage is considered full by most measures, but may still be
    // allowing passengers to board.
    FULL = 5;

    // The vehicle or carriage is not accepting passengers, but usually accepts passengers for boarding.
    NOT_ACCEPTING_PASSENGERS = 6;

    // The vehicle or carriage doesn't have any occupancy data available at that time.
    NO_DATA_AVAILABLE = 7;

    // The vehicle or carriage is not boardable and never accepts passengers.
    // Useful for special vehicles or carriages (engine, maintenance carriage, etc…).
    NOT_BOARDABLE = 8;

  }
  // If multi_carriage_status is populated with per-carriage OccupancyStatus,
  // then this field should describe the entire vehicle with all carriages accepting passengers considered.
  optional OccupancyStatus occupancy_status = 9;

  // A percentage value indicating the degree of passenger occupancy in the vehicle.
  // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%.
  // The value 100 should represent the total maximum occupancy the vehicle was designed for,
  // including both seated and standing capacity, and current operating regulations allow.
  // The value may exceed 100 if there are more passengers than the maximum designed capacity.
  // The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle.
  // If multi_carriage_status is populated with per-carriage occupancy_percentage, 
  // then this field should describe the entire vehicle with all carriages accepting passengers considered.
  // This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional uint32 occupancy_percentage = 10;

  // Carriage specific details, used for vehicles composed of several carriages
  // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
  message CarriageDetails {

    // Identification of the carriage. Should be unique per vehicle.
    optional string id = 1;

    // User visible label that may be shown to the passenger to help identify
    // the carriage. Example: "7712", "Car ABC-32", etc...
    // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
    optional string label = 2;

    // Occupancy status for this given carriage, in this vehicle
    // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
    optional OccupancyStatus occupancy_status = 3 [default = NO_DATA_AVAILABLE];

    // Occupancy percentage for this given carriage, in this vehicle.
    // Follows the same rules as "VehiclePosition.occupancy_percentage"
    // -1 in case data is not available for this given carriage (as protobuf defaults to 0 otherwise)
    // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
    optional int32 occupancy_percentage = 4 [default = -1];

    // Identifies the order of this carriage with respect to the other
    // carriages in the vehicle's list of CarriageDetails.
    // The first carriage in the direction of travel must have a value of 1.
    // The second value corresponds to the second carriage in the direction
    // of travel and must have a value of 2, and so forth.
    // For example, the first carriage in the direction of travel has a value of 1.
    // If the second carriage in the direction of travel has a value of 3,
    // consumers will discard data for all carriages (i.e., the multi_carriage_details field).
    // Carriages without data must be represented with a valid carriage_sequence number and the fields 
    // without data should be omitted (alternately, those fields could also be included and set to the "no data" values).
    // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
    optional uint32 carriage_sequence = 5;

    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features and
    // modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }

  // Details of the multiple carriages of this given vehicle.
  // The first occurrence represents the first carriage of the vehicle, 
  // given the current direction of travel. 
  // The number of occurrences of the multi_carriage_details 
  // field represents the number of carriages of the vehicle.
  // It also includes non boardable carriages, 
  // like engines, maintenance carriages, etc… as they provide valuable 
  // information to passengers about where to stand on a platform.
  // This message/field is still experimental, and subject to change. It may be formally adopted in the future.
  repeated CarriageDetails multi_carriage_details = 11;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// An alert, indicating some sort of incident in the public transit network.
message Alert {
  // Time when the alert should be shown to the user. If missing, the
  // alert will be shown as long as it appears in the feed.
  // If multiple ranges are given, the alert will be shown during all of them.
  repeated TimeRange active_period = 1;

  // Entities whose users we should notify of this alert.
  repeated EntitySelector informed_entity = 5;

  // Cause of this alert.
  enum Cause {
    UNKNOWN_CAUSE = 1;
    OTHER_CAUSE = 2;        // Not machine-representable.
    TECHNICAL_PROBLEM = 3;
    STRIKE = 4;             // Public transit agency employees stopped working.
    DEMONSTRATION = 5;      // People are blocking the streets.
    ACCIDENT = 6;
    HOLIDAY = 7;
    WEATHER = 8;
    MAINTENANCE = 9;
    CONSTRUCTION = 10;
    POLICE_ACTIVITY = 11;
    MEDICAL_EMERGENCY = 12;
  }
  optional Cause cause = 6 [default = UNKNOWN_CAUSE];

  // What is the effect of this problem on the affected entity.
  enum Effect {
    NO_SERVICE = 1;
    REDUCED_SERVICE = 2;

    // We don't care about INsignificant delays: they are hard to detect, have
    // little impact on the user, and would clutter the results as they are too
    // frequent.
    SIGNIFICANT_DELAYS = 3;

    DETOUR = 4;
    ADDITIONAL_SERVICE = 5;
    MODIFIED_SERVICE = 6;
    OTHER_EFFECT = 7;
    UNKNOWN_EFFECT = 8;
    STOP_MOVED = 9;
    NO_EFFECT = 10;
    ACCESSIBILITY_ISSUE = 11;
  }
  optional Effect effect = 7 [default = UNKNOWN_EFFECT];

  // The URL which provides additional information about the alert.
  optional TranslatedString url = 8;

  // Alert header. Contains a short summary of the alert text as plain-text.
  optional TranslatedString header_text = 10;

  // Full description for the alert as plain-text. The information in the
  // description should add to the information of the header.
  optional TranslatedString description_text = 11;

  // Text for alert header to be used in text-to-speech implementations. This field is the text-to-speech version of header_text.
  optional TranslatedString tts_header_text = 12;

  // Text for full description for the alert to be used in text-to-speech implementations. This field is the text-to-speech version of description_text.
  optional TranslatedString tts_description_text = 13;

  // Severity of this alert.
  enum SeverityLevel {
	UNKNOWN_SEVERITY = 1;
	INFO = 2;
	WARNING = 3;
	SEVERE = 4;
  }

  optional SeverityLevel severity_level = 14 [default = UNKNOWN_SEVERITY];

  // TranslatedImage to be displayed along the alert text. Used to explain visually the alert effect of a detour, station closure, etc. The image must enhance the understanding of the alert. Any essential information communicated within the image must also be contained in the alert text.
  // The following types of images are discouraged : image containing mainly text, marketing or branded images that add no additional information. 
  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional TranslatedImage image = 15; 

  // Text describing the appearance of the linked image in the `image` field (e.g., in case the image can't be displayed
  // or the user can't see the image for accessibility reasons). See the HTML spec for alt image text - https://html.spec.whatwg.org/#alt.
  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional TranslatedString image_alternative_text = 16;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features
  // and modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

//
// Low level data structures used above.
//

// A time interval. The interval is considered active at time 't' if 't' is
// greater than or equal to the start time and less than the end time.
message TimeRange {
  // Start time, in POSIX time (i.e., number of seconds since January 1st 1970
  // 00:00:00 UTC).
  // If missing, the interval starts at minus infinity.
  optional uint64 start = 1;

  // End time, in POSIX time (i.e., number of seconds since January 1st 1970
  // 00:00:00 UTC).
  // If missing, the interval ends at plus infinity.
  optional uint64 end = 2;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// A position.
message Position {
  // Degrees North, in the WGS-84 coordinate system.
  required float latitude = 1;

  // Degrees East, in the WGS-84 coordinate system.
  required float longitude = 2;

  // Bearing, in degrees, clockwise from North, i.e., 0 is North and 90 is East.
  // This can be the compass bearing, or the direction towards the next stop
  // or intermediate location.
  // This should not be direction deduced from the sequence of previous
  // positions, which can be computed from previous data.
  optional float bearing = 3;

  // Odometer value, in meters.
  optional double odometer = 4;
  // Momentary speed measured by the vehicle, in meters per second.
  optional float speed = 5;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// A descriptor that identifies an instance of a GTFS trip, or all instances of
// a trip along a route.
// - To specify a single trip instance, the trip_id (and if necessary,
//   start_time) is set. If route_id is also set, then it should be same as one
//   that the given trip corresponds to.
// - To specify all the trips along a given route, only the route_id should be
//   set. Note that if the trip_id is not known, then stop sequence ids in
//   TripUpdate are not sufficient, and stop_ids must be provided as well. In
//   addition, absolute arrival/departure times must be provided.
message TripDescriptor {
  // The trip_id from the GTFS feed that this selector refers to.
  // For non frequency-based trips, this field is enough to uniquely identify
  // the trip. For frequency-based trip, start_time and start_date might also be
  // necessary. When schedule_relationship is DUPLICATED within a TripUpdate, the trip_id identifies the trip from
  // static GTFS to be duplicated. When schedule_relationship is DUPLICATED within a VehiclePosition, the trip_id
  // identifies the new duplicate trip and must contain the value for the corresponding TripUpdate.TripProperties.trip_id.
  optional string trip_id = 1;

  // The route_id from the GTFS that this selector refers to.
  optional string route_id = 5;

  // The direction_id from the GTFS feed trips.txt file, indicating the
  // direction of travel for trips this selector refers to.
  optional uint32 direction_id = 6;

  // The initially scheduled start time of this trip instance.
  // When the trip_id corresponds to a non-frequency-based trip, this field
  // should either be omitted or be equal to the value in the GTFS feed. When
  // the trip_id correponds to a frequency-based trip, the start_time must be
  // specified for trip updates and vehicle positions. If the trip corresponds
  // to exact_times=1 GTFS record, then start_time must be some multiple
  // (including zero) of headway_secs later than frequencies.txt start_time for
  // the corresponding time period. If the trip corresponds to exact_times=0,
  // then its start_time may be arbitrary, and is initially expected to be the
  // first departure of the trip. Once established, the start_time of this
  // frequency-based trip should be considered immutable, even if the first
  // departure time changes -- that time change may instead be reflected in a
  // StopTimeUpdate.
  // Format and semantics of the field is same as that of
  // GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35.
  optional string start_time = 2;
  // The scheduled start date of this trip instance.
  // Must be provided to disambiguate trips that are so late as to collide with
  // a scheduled trip on a next day. For example, for a train that departs 8:00
  // and 20:00 every day, and is 12 hours late, there would be two distinct
  // trips on the same time.
  // This field can be provided but is not mandatory for schedules in which such
  // collisions are impossible - for example, a service running on hourly
  // schedule where a vehicle that is one hour late is not considered to be
  // related to schedule anymore.
  // In YYYYMMDD format.
  optional string start_date = 3;

  // The relation between this trip and the static schedule. If a trip is done
  // in accordance with temporary schedule, not reflected in GTFS, then it
  // shouldn't be marked as SCHEDULED, but likely as ADDED.
  enum ScheduleRelationship {
    // Trip that is running in accordance with its GTFS schedule, or is close
    // enough to the scheduled trip to be associated with it.
    SCHEDULED = 0;

    // An extra trip that was added in addition to a running schedule, for
    // example, to replace a broken vehicle or to respond to sudden passenger
    // load.
    // NOTE: Currently, behavior is unspecified for feeds that use this mode. There are discussions on the GTFS GitHub
    // [(1)](https://github.com/google/transit/issues/106) [(2)](https://github.com/google/transit/pull/221)
    // [(3)](https://github.com/google/transit/pull/219) around fully specifying or deprecating ADDED trips and the
    // documentation will be updated when those discussions are finalized.
    ADDED = 1;

    // A trip that is running with no schedule associated to it (GTFS frequencies.txt exact_times=0).
    // Trips with ScheduleRelationship=UNSCHEDULED must also set all StopTimeUpdates.ScheduleRelationship=UNSCHEDULED.
    UNSCHEDULED = 2;

    // A trip that existed in the schedule but was removed.
    CANCELED = 3;

    // Should not be used - for backwards-compatibility only.
    REPLACEMENT = 5; // [deprecated=true];

    // An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to
    // respond to sudden passenger load. Used with TripUpdate.TripProperties.trip_id, TripUpdate.TripProperties.start_date,
    // and TripUpdate.TripProperties.start_time to copy an existing trip from static GTFS but start at a different service
    // date and/or time. Duplicating a trip is allowed if the service related to the original trip in (CSV) GTFS
    // (in calendar.txt or calendar_dates.txt) is operating within the next 30 days. The trip to be duplicated is
    // identified via TripUpdate.TripDescriptor.trip_id. This enumeration does not modify the existing trip referenced by
    // TripUpdate.TripDescriptor.trip_id - if a producer wants to cancel the original trip, it must publish a separate
    // TripUpdate with the value of CANCELED. Trips defined in GTFS frequencies.txt with exact_times that is empty or
    // equal to 0 cannot be duplicated. The VehiclePosition.TripDescriptor.trip_id for the new trip must contain
    // the matching value from TripUpdate.TripProperties.trip_id and VehiclePosition.TripDescriptor.ScheduleRelationship
    // must also be set to DUPLICATED.
    // Existing producers and consumers that were using the ADDED enumeration to represent duplicated trips must follow
    // the migration guide (https://github.com/google/transit/tree/master/gtfs-realtime/spec/en/examples/migration-duplicated.md)
    // to transition to the DUPLICATED enumeration.
    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
    DUPLICATED = 6;
  }
  optional ScheduleRelationship schedule_relationship = 4;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// Identification information for the vehicle performing the trip.
message VehicleDescriptor {
  // Internal system identification of the vehicle. Should be unique per
  // vehicle, and can be used for tracking the vehicle as it proceeds through
  // the system.
  optional string id = 1;

  // User visible label, i.e., something that must be shown to the passenger to
  // help identify the correct vehicle.
  optional string label = 2;

  // The license plate of the vehicle.
  optional string license_plate = 3;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// A selector for an entity in a GTFS feed.
message EntitySelector {
  // The values of the fields should correspond to the appropriate fields in the
  // GTFS feed.
  // At least one specifier must be given. If several are given, then the
  // matching has to apply to all the given specifiers.
  optional string agency_id = 1;
  optional string route_id = 2;
  // corresponds to route_type in GTFS.
  optional int32 route_type = 3;
  optional TripDescriptor trip = 4;
  optional string stop_id = 5;
  // Corresponds to trip direction_id in GTFS trips.txt. If provided the
  // route_id must also be provided.
  optional uint32 direction_id = 6;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// An internationalized message containing per-language versions of a snippet of
// text or a URL.
// One of the strings from a message will be picked up. The resolution proceeds
// as follows:
// 1. If the UI language matches the language code of a translation,
//    the first matching translation is picked.
// 2. If a default UI language (e.g., English) matches the language code of a
//    translation, the first matching translation is picked.
// 3. If some translation has an unspecified language code, that translation is
//    picked.
message TranslatedString {
  message Translation {
    // A UTF-8 string containing the message.
    required string text = 1;
    // BCP-47 language code. Can be omitted if the language is unknown or if
    // no i18n is done at all for the feed. At most one translation is
    // allowed to have an unspecified language tag.
    optional string language = 2;

    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features and
    // modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }
  // At least one translation must be provided.
  repeated Translation translation = 1;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// An internationalized image containing per-language versions of a URL linking to an image
// along with meta information
// Only one of the images from a message will be retained by consumers. The resolution proceeds
// as follows:
// 1. If the UI language matches the language code of a translation,
//    the first matching translation is picked.
// 2. If a default UI language (e.g., English) matches the language code of a
//    translation, the first matching translation is picked.
// 3. If some translation has an unspecified language code, that translation is
//    picked.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
message TranslatedImage {
  message LocalizedImage {
    // String containing an URL linking to an image
    // The image linked must be less than 2MB. 
    // If an image changes in a significant enough way that an update is required on the consumer side, the producer must update the URL to a new one.
    // The URL should be a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See the following https://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values.
    required string url = 1;

    // IANA media type as to specify the type of image to be displayed. 
    // The type must start with "image/"
    required string media_type = 2;

    // BCP-47 language code. Can be omitted if the language is unknown or if
    // no i18n is done at all for the feed. At most one translation is
    // allowed to have an unspecified language tag.
    optional string language = 3;


    // The extensions namespace allows 3rd-party developers to extend the
    // GTFS Realtime Specification in order to add and evaluate new features and
    // modifications to the spec.
    extensions 1000 to 1999;

    // The following extension IDs are reserved for private use by any organization.
    extensions 9000 to 9999;
  }
  // At least one localized image must be provided.
  repeated LocalizedImage localized_image = 1;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}

// Describes the physical path that a vehicle takes when it's not part of the (CSV) GTFS,
// such as for a detour. Shapes belong to Trips, and consist of a sequence of shape points.
// Tracing the points in order provides the path of the vehicle.  Shapes do not need to intercept
// the location of Stops exactly, but all Stops on a trip should lie within a small distance of
// the shape for that trip, i.e. close to straight line segments connecting the shape points
// NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future.
message Shape {
  // Identifier of the shape. Must be different than any shape_id defined in the (CSV) GTFS.
  // This field is required as per reference.md, but needs to be specified here optional because "Required is Forever"
  // See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules
  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional string shape_id = 1;
  
  // Encoded polyline representation of the shape. This polyline must contain at least two points.
  // For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
  // This field is required as per reference.md, but needs to be specified here optional because "Required is Forever"
  // See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules
  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
  optional string encoded_polyline = 2;

  // The extensions namespace allows 3rd-party developers to extend the
  // GTFS Realtime Specification in order to add and evaluate new features and
  // modifications to the spec.
  extensions 1000 to 1999;

  // The following extension IDs are reserved for private use by any organization.
  extensions 9000 to 9999;
}