diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 76057b9d4..ce6f77198 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -221,6 +221,33 @@ message TripUpdate { optional ScheduleRelationship schedule_relationship = 5 [default = SCHEDULED]; + // Experimental field, subject to change + // PredictionCertainty represents the certainty of the + // real time information provided. + // This allows the consumer to decide how to display the real time information + // to the user depending on the precision. + // If HIGH and LOW certainty information are both shown to riders, + // consumers should represent these types of information differently in the + // user interface. LOW certainty values should not be represented in the same + // way as schedule data to the rider. + // PredictionCertainty is ignored if schedule_relationship = SKIPPED or NO_DATA + enum PredictionCertainty { + // Precision of the real time is unknown, default behavior + UNKNOWN = 0; + + // Update is based on real time information with high certainty. + // High certainty is usually the certainty users expect when talking + // about real time information. It's used to be constrasted with LOW certainty. + HIGH = 1; + + // Update is based on information from a vehicle that is or was followed + // in real time but is now low certainty. Lower certainty can come from things like + // a bus losing connection after the start of the run or when the prediction + // is dependant on driver behaviour. + LOW = 2; + } + optional PredictionCertainty certainty = 6 [default = UNKNOWN]; + // 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. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index a4a918809..c50b4a54e 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -177,6 +177,21 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | +| **certainty** | [RealTimeCertainty](#enum-realtimecertainty) | Optional | One | The default certainty is UNKNOWN. | + +## _enum_ RealTimeCertainty + +Experimental field, subject to change +RealTimeCertainty represents the certainty of the real time information provided. This allows the consumer to decide how to display the real time information to the user depending on the precision. If HIGH and LOW certainty information are both shown to riders, consumers should represent these types of information differently in the user interface. LOW certainty values should not be represented in the same way as schedule data to the rider. +RealTimeCertainty is ignored if schedule_relationship = SKIPPED or NO_DATA + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **UNKNOWN** | Precision of the real time is unknown, default behavior | +| **HIGH** | Update is based on real time information with high certainty. High certainty is usually the certainty users expect when talking about real time information. It's used to be constrasted with LOW certainty. | +| **LOW** | Update is based on information from a vehicle that is or was followed in real time but is now low certainty. Lower certainty can come from things like a bus losing connection after the start of the run or when the prediction is dependant on driver behaviour. | ## _enum_ ScheduleRelationship