• Перевод:
  • Обзор
  • Виды каналов
  • Изменения в рейсах
  • Предупреждения
  • Координаты транспорта
  • Описание
  • Примеры
  • Предупреждения
  • Изменения в рейсах
  • gtfs-realtime.proto
  • Изменения
  • GTFS-realtime Reference

    Перевод версии от 26 октября 2012

    В процессе перевода

    A GTFS-realtime feed 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.

    Version 1.0 of the feed specification is discussed and documented on this site.

    Term Definitions

    • required: Exactly one
    • repeated: Zero or more
    • message: Complex type
    • enum: List of fixed values

    Element Index


    message FeedMessage

    The contents of a feed message. Each message in the stream is obtained as a response to an appropriate HTTP GET request. A real-time feed is always defined with relation to an existing GTFS feed. All the entity ids are resolved with respect to the GTFS feed.

    A feed depends on some external configuration:

    • The corresponding GTFS feed.
    • Feed application (updates, positions or alerts). A feed should contain only items of the appropriate applications; all the other entities will be ignored.
    • Polling frequency, controlled by min_update_delay, max_update_delay.


    Field Name Type Cardinality Description
    header FeedHeader required Metadata about this feed and feed message.
    entity FeedEntity repeated Contents of the feed.

    message FeedHeader

    Metadata about a feed, included in feed messages.


    Field Name Type Cardinality Description
    gtfs_realtime_version string required Version of the feed specification. The current version is 1.0.
    incrementality Incrementality optional
    timestamp uint64 optional 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). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable.

    enum Incrementality

    Determines whether the current fetch is incremental.

    • FULL_DATASET: this feed update will overwrite all preceding realtime information for the feed. Thus this update is expected to provide a full snapshot of all known realtime information.
    • DIFFERENTIAL: currently, this 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.



    message FeedEntity

    A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle' and 'alert' fields should be populated.


    Field Name Type Cardinality Description
    id string required Feed-unique identifier for this entity. The ids are used only to provide incrementality support. The actual entities referenced by the feed must be specified by explicit selectors (see EntitySelector below for more info).
    is_deleted bool optional Whether this entity is to be deleted. Relevant only for incremental fetches.
    trip_update TripUpdate optional Data about the realtime departure delays of a trip.
    vehicle VehiclePosition optional Data about the realtime position of a vehicle.
    alert Alert optional Data about the realtime alert.

    message TripUpdate

    Real-time update on the progress of a vehicle along a trip. Please also refer to the general discussion of the trip updates feed type.

    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 has 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. In most cases information about past events is a measured value thus its uncertainty value is recommended to be 0. Although there could be cases when this does not hold so it is allowed to have uncertainty value different from 0 for past events. If an update's uncertainty is not 0, either the update is an approximate prediction for a trip that has not completed or the measurement is not precise or the update was a prediction for the past that has not been verified after the event occurred.

    Note that the update can describe a trip that has already completed. To this end, it is enough to provide an update for the last stop of the trip. If the time of arrival at the last stop is in the past, the client will conclude 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.


    Field Name Type Cardinality Description
    trip TripDescriptor required 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.
    vehicle VehicleDescriptor optional Additional information on the vehicle that is serving this trip.
    stop_time_update StopTimeUpdate repeated 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.
    timestamp uint64 optional Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC).

    message StopTimeEvent

    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.


    Field Name Type Cardinality Description
    delay int32 optional 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.
    time int64 optional Event as absolute time. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC).
    uncertainty int32 optional If uncertainty is omitted, it is interpreted as unknown. To specify a completely certain prediction, set its uncertainty to 0.

    message StopTimeUpdate

    Realtime update for arrival and/or departure events for a given stop on a trip. Please also refer to the general discussion of stop time updates in the TripDescriptor and trip updates feed type documentation.

    Updates can be supplied for both past and future events. The producer is allowed, although not required, to drop past events.
    The update is linked to a specific stop either through stop_sequence or stop_id, so one of these fields must necessarily be set.


    Field Name Type Cardinality Description
    stop_sequence uint32 optional Must be the same as in stop_times.txt in the corresponding GTFS feed.
    stop_id string optional Must be the same as in stops.txt in the corresponding GTFS feed.
    arrival StopTimeEvent optional
    departure StopTimeEvent optional
    schedule_relationship ScheduleRelationship optional The default relationship is SCHEDULED.

    enum ScheduleRelationship

    The relation between this StopTime and the static schedule.


    Value Comment
    SCHEDULED The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the default behavior. 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. An update with only an arrival, say, where the schedule has both, indicates that the trip is terminating early at this stop.
    SKIPPED The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional.
    NO_DATA No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied.

    message VehiclePosition

    Realtime positioning information for a given vehicle.


    Field Name Type Cardinality Description
    trip TripDescriptor optional The Trip that this vehicle is serving. Can be empty or partial if the vehicle can not be identified with a given trip instance.
    vehicle VehicleDescriptor optional Additional information on the vehicle that is serving this trip. Each entry should have a unique vehicle id.
    position Position optional Current position of this vehicle.
    current_stop_sequence uint32 optional 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.
    stop_id string optional Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed.
    current_status VehicleStopStatus optional The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing.
    timestamp uint64 optional 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).
    congestion_level CongestionLevel optional

    enum VehicleStopStatus


    Value Comment
    INCOMING_AT The vehicle is just about to arrive at the stop (on a stop display, the vehicle symbol typically flashes).
    STOPPED_AT The vehicle is standing at the stop.
    IN_TRANSIT_TO The vehicle has departed the previous stop and is in transit.

    enum CongestionLevel

    Congestion level that is affecting this vehicle.



    message Alert

    An alert, indicating some sort of incident in the public transit network.


    Field Name Type Cardinality Description
    active_period TimeRange repeated 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.
    informed_entity EntitySelector repeated Entities whose users we should notify of this alert.
    cause Cause optional
    effect Effect optional
    url TranslatedString optional The URL which provides additional information about the alert.
    header_text TranslatedString optional Header for the alert. This plain-text string will be highlighted, for example in boldface.
    description_text TranslatedString optional Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header.

    enum Cause

    Cause of this alert.



    enum Effect

    The effect of this problem on the affected entity.



    message TimeRange

    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.


    Field Name Type Cardinality Description
    start uint64 optional 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.
    end uint64 optional 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.

    message Position

    A geographic position of a vehicle.


    Field Name Type Cardinality Description
    latitude float required Degrees North, in the WGS-84 coordinate system.
    longitude float required Degrees East, in the WGS-84 coordinate system.
    bearing float optional Bearing, in degrees, clockwise from True 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 deduced from the sequence of previous positions, which clients can compute from previous data.
    odometer double optional Odometer value, in meters.
    speed float optional Momentary speed measured by the vehicle, in meters per second.

    message TripDescriptor

    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 station sequence ids in TripUpdate are not sufficient, and stop_ids must be provided as well. In addition, absolute arrival/departure times must be provided.


    Field Name Type Cardinality Description
    trip_id string optional The trip_id from the GTFS feed that this selector refers to. For non frequency expanded trips, this field is enough to uniquely identify the trip. For frequency expanded, start_time and start_date might also be necessary.
    route_id string optional The route_id from the GTFS that this selector refers to.
    start_time string optional The scheduled start time of this trip instance. This field should be given only if the trip is frequency-expanded in the GTFS feed. The value must precisely correspond to start_time specified for the route in the GTFS feed plus some multiple of headway_secs. Format of the field is same as that of GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35.
    start_date string optional The scheduled start date of this trip instance. This field 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.
    schedule_relationship ScheduleRelationship optional

    enum ScheduleRelationship

    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 marked as ADDED.


    Value Comment
    SCHEDULED Trip that is running in accordance with its GTFS schedule, or is close enough to the scheduled trip to be associated with it.
    ADDED 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.
    UNSCHEDULED A trip that is running with no schedule associated to it, for example, if there is no schedule at all.
    CANCELED A trip that existed in the schedule but was removed.
    REPLACEMENT A trip that replaces a portion of the static schedule. If the trip selector identifies a certain trip instance, then only that instance is replaced. If the selector identifies a route, then all the trips along that route are replaced.

    The replacement applies only to the portion of the trip supplied. For instance, consider a route that goes through stops A,B,C,D,E,F, and a REPLACEMENT trip provides data for stops A,B,C. Then, the times for stops D,E,F are still taken from the static schedule.

    A feed might supply several REPLACEMENT trips. In this case, the portion of the static schedule that is replaced is the union of what is defined by all the feeds. Normally, all the REPLACEMENT trips should either correspond to the same route or to individual trip instances.

    message VehicleDescriptor

    Identification information for the vehicle performing the trip.


    Field Name Type Cardinality Description
    id string optional Internal system identification of the vehicle. Should be unique per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the label field
    label string optional User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle.
    license_plate string optional The license plate of the vehicle.

    message EntitySelector

    A selector for an entity in a GTFS feed. 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.


    Field Name Type Cardinality Description
    agency_id string optional
    route_id string optional
    route_type int32 optional
    trip TripDescriptor optional
    stop_id string optional

    message TranslatedString

    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: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked.


    Field Name Type Cardinality Description
    translation Translation repeated At least one translation must be provided.

    message Translation

    A localized string mapped to a language.


    Field Name Type Cardinality Description
    text string required A UTF-8 string containing the message.
    language string optional BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag.

    Оригинал: https://developers.google.com/transit/gtfs-realtime/reference