gitphp 0.2.9.1 :: busui.git/blame

2011-08-23 07:32:41	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	}