From 24e89c97cbbdd89348b1f02497a129ac8ac0a14f Mon Sep 17 00:00:00 2001 From: isabelle-dr Date: Tue, 22 Mar 2022 19:33:40 -0400 Subject: re arrange repo --- gtfs-realtime-book/ch-03-vehicle-positions.md | 317 ++++++++++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 gtfs-realtime-book/ch-03-vehicle-positions.md (limited to 'gtfs-realtime-book/ch-03-vehicle-positions.md') diff --git a/gtfs-realtime-book/ch-03-vehicle-positions.md b/gtfs-realtime-book/ch-03-vehicle-positions.md new file mode 100644 index 0000000..f247ae7 --- /dev/null +++ b/gtfs-realtime-book/ch-03-vehicle-positions.md @@ -0,0 +1,317 @@ +## 3. Introduction to Vehicle Positions + +A vehicle position message communicates the physical location of a bus, +train, ferry or otherwise. In addition to location of the vehicle, it +can also provide information about the vehicle's speed, bearing (the +direction it is facing), and how to match up the vehicle with a trip in +the static schedule. + +A recent addition to the GTFS-realtime specification (experimental at +time of writing -- see +) is the +ability to indicate how full a vehicle is. Although this element is not +yet formally a part of the specification, it has been included in this +book so it aligns with current documentation. + +### Sample Feed + +The following extract is from the vehicle position feed of MBTA in +Boston (). MBTA also provide separate +feeds for service alerts and trip updates. + +This extract contains a single GTFS-realtime entity, which represents a +single vehicle position. + +``` +entity { + id: "v1211" + + vehicle { + trip { + trip_id: "25906883" + start_date: "20150117" + schedule_relationship: SCHEDULED + route_id: "28" + } + + position { + latitude: 42.267967 + longitude: -71.093834 + } + + current_stop_sequence: 35 + timestamp: 1421565564 + stop_id: "1721" + + vehicle { + id: "y2189" + label: "2189" + } + } +} +``` + +***Note:** This extract has been converted from its binary format into a +human-readable version. *Outputting Human-Readable GTFS-realtime Feeds* +shows you how this is achieved.* + +Rendering the vehicle position and its path on a map along with the +referenced stop looks as follows. + +![Vehicle Position](images/vehicle-position.png) + +The elements of the vehicle position are described below. The outer +`vehicle` element in this entity is of type `VehiclePosition`. The +inner `vehicle` element is a `VehicleDescriptor`, which is described +shortly. + +### Trip + +If specified, this element is used to link the vehicle position to a +specific trip in the corresponding GTFS feed, or to a trip that has been +added to the schedule. Using MBTA's GTFS feed, you can determine that +the trip can be matched to the record below. You can find this in the +trips.txt file at +. + +| `route_id` | `service_id` | `trip_id` | `trip_headsign` | +| :--------- | :----------------------------- | :-------- | :-------------- | +| 28 | BUSS12015-hbs15no6-Saturday-02 | 25906883 | Mattapan Station via Dudley Station | + +**Note:** If the schedule_relationship value was ADDED or UNSCHEDULED, +there would not have been a corresponding record in trips.txt. + +If you then look up the trip's records in stop_times.txt, you can +determine the trip begins at 25:45:00. This means the trip begins at +1:45 AM on the morning following its service date. In this case, the +start date in the vehicle position is specified as January 17. This +means that this trip actually takes place on the morning of January 18. +If the start date was not included with the vehicle position, it may +have been difficult to determine the specific trip being referenced. + +### Position + +This element contains the geographic location of the vehicle. In this +instance, only the latitude and longitude are specified. It is also +possible to include the vehicle's bearing, odometer and speed, however +only that latitude and longitude are required. + +### Current Stop + +A vehicle position can include information about its position relative +to its current or next stop. + +The status of the stop is indicated by the `current_status` value. In +this example, the `current_status` is not specified, which means the +vehicle is currently in transit to the stop (in other words, it is not +stopped there, nor is it about to stop). + +The stop referred to in this instance has a `stop_id` of `1721`. +Referring once again to the MBTA GTFS feed +(), this stop is as +follows. + +| `stop_id` | `stop_code` | `stop_name` | `stop_lat` | `stop_lon` | +| :-------- | :---------- | :------------------------ | :--------- | :--------- | +| 1721 | 1721 | Blue Hill Ave @ River St | 42.267151 | -71.09362 | + +The other value used to identify the upcoming or current stop is the +`current_stop_sequence` value. This refers to the `stop_sequence` +value in `stop_times.txt`. + +***Note:** Technically, you can infer the stop based on the trip and +current_stop_sequence value, so you do not strictly need the stop_id +value. However, in some cases it may not be possible to identify the +trip (and therefore not be able to infer the specific stop), so having +the `stop_id` value available in the vehicle position is useful.* + +By looking up the stop ID and trip ID in `stop_times.txt`, you can +locate the following entry: + +| `trip_id` | `stop_sequence` | `stop_id` | `arrival_time` | `departure_time` | +| :-------- | :-------------- | :-------- | :------------- | :--------------- | +| 25906883 | 35 | 1721 | 26:14:00 | 26:14:00 | + +***Note:** Remember that an hour value of 26 corresponds to 2 AM on the +following day (in this instance, the trip value specifies the trip's +date as January 17, so this stop time is 2 AM on January 18).* + +In plain English, this can be interpreted as "the vehicle is currently +in transit to stop 1721, scheduled to arrive at 2:14 AM." Note however, +that the timestamp value corresponds to 2:19 AM, meaning the bus is +about 5 minutes late. + +Tip: You can quickly find the human-readable version of a timestamp +using the command-line tool date. You may need to set the local timezone +first. In this instance, Boston's timezone can be set using export +TZ=America/New_York. You can then use date -r 1421565564 to find the +value of Sun 18 Jan 2015 02:19:24 EST. + +### Vehicle Descriptor + +The vehicle descriptor provides information to identify the specific +vehicle. In this example, the internal vehicle identifier is `y2189`. +It should remain consistent for this particular vehicle across the +system. Any subsequent vehicle positions or trip updates that refer to +this vehicle should use the same identifier. + +The vehicle ID value is not intended to be presented to end-users. +Instead, the label field should be used. The label could refer to a +particular train number, or perhaps a number painted on the side of a +bus. In the case of vehicle 2189, the number appears as in the following +photograph. + +![MBTA Bus](images/mbta_bus.png) + +The other piece of identifying information that can be presented to +users is the license plate of the vehicle. The MBTA's feed doesn't +specify this value, presumably because it duplicates the `label` +value. + +### Improvements + +Although this sample vehicle position contains the most pertinent +information (the coordinates of the vehicle and its corresponding trip), +knowing the direction that the vehicle is facing can also be useful. + +A common way of presenting vehicle positions on a map is to show all +positions for a given route on a map. If you can provide this extra +piece of information, a passenger can look at a map of all vehicle +positions for a given route and determine which are traveling in their +desired direction, and which are traveling in the opposite direction. + +***Note:** When you can match up a vehicle position to a specific trip, +it may be possible to filter which vehicles appear on the map using the +`direction_id` value for the trip. In some instances though, you may only +know the route of a vehicle and not its specific trip.* + +*Chapter 7. Consuming Vehicle Positions* shows you how to +determine the bearing of a vehicle if it is not included by the data +provider. + +### Specification + +This section contains the specification for the `VehiclePosition` +entity type. Some of this information has been sourced from the +GTFS-realtime reference page +(). + +### VehiclePosition + +A `VehiclePosition` element is used to specify the geographic position +and other attributes of a single vehicle, as well as providing +information to match that vehicle back to the corresponding GTFS feed. + +| Field | Type | Frequency | Description | +| :---- | :--- | :-------- | :---------- | +| `trip` | `TripDescriptor` | Optional | This is used to match the vehicle position to a specific trip from `trips.txt` in the corresponding GTFS feed. | +| `vehicle` | `VehicleDescriptor` | Optional | This element provides information that can be used to identify a particular vehicle. | +| `position` | `Position` | Optional | The vehicle's geographic location, bearing and speed are specified using the `Position` type. | +| `current_stop_sequence` | `int32` (32-bit signed integer) | Optional | The sequence of the current stop, as it appears in the `stop_sequence` value for the trip matched in the corresponding `stop_times.txt` file. | +| `stop_id` | `string` | Optional | This is used to identify the current stop. If specified, the `stop_id` value must correspond to an entry in the `stops.txt` file of the corresponding GTFS feed. | +| `current_status` | `VehicleStopStatus` | Optional | If the current stop is specified (using `current_stop_sequence`), this value specifies what the "current stop" means. If this value isn't specified, it is assumed to be `IN_TRANSIT_TO`. | +| `timestamp` | `uint64` (64 bit unsigned integer) | Optional | This value refers to the moment at which the vehicle's position was measured, specified in number of seconds since 1-Jan-1970 00:00:00 UTC. | +| `congestion_level` | `CongestionLevel` | Optional | This value indicates the status of the traffic flow the vehicle is currently experiencing. The possible values for this element are listed below this table. | +| `occupancy_status` | `OccupancyStatus` | Optional | At time of writing, this field is experimental only. If specified, it indicates how full a given vehicle is. | + +The possible values for the `VehicleStopStatus` enumerator are as +follows: + +| Value | Description | +| :---- | :---------- | +| `INCOMING_AT` | The vehicle is just about to arrive at the specified stop. In some vehicles, there is a visual display or audio announcement when approaching the next stop. This could correspond with `current_status` changing from `IN_TRANSIT_TO` to `INCOMING_AT`. | +| `STOPPED_AT` | The vehicle is currently stationary at the stop. Once it departs the `current_status` would update to `IN_TRANSIT_TO`. | +| `IN_TRANSIT_TO` | The vehicle has departed the previous stop and is on its way to the specified stop. This is the default value if `current_status` is not specified. | + +The possible values for the `CongestionLevel` enumerator are as +follows: + +| Value | Description | +| :---- | :---------- | +| `UNKNOWN_CONGESTION_LEVEL` | If the congestion level is not specified, then this is the default value. | +| `RUNNING_SMOOTHLY` | Traffic is flowing smoothly. | +| `STOP_AND_GO` | Traffic is flowing, but not smoothly. | +| `CONGESTION` | The vehicle is experiencing some level of congestion, and therefore likely to be moving very slowly. | +| `SEVERE_CONGESTION` | The vehicle is experiencing a high level of congestion, and therefore likely to be not moving. | + +While this information can be useful to present to the user, it does not +allow you to make any inference as to whether the vehicle will adhere to +its schedule. Schedules are often designed to account for levels of +congestion, depending on the time of day. + +For this value to be useful in telling a user why their vehicle may be +late, the GTFS `stop_times.txt` would likely also need a field to +indicate the expected congestion level for any given stop time. +Realistically though, this is where the `TripUpdate` element comes +into play. This is covered in *Chapter 4. Introduction to Trip Updates*. + +### TripDescriptor + +The meaning of the trip descriptor differs slightly for a vehicle +position than for a service alert. In a service alert, if the +`route_id` is specified but the `trip_id` is not, then the service +alert applies to all trips for that route. + +In the case of a vehicle position, if the `route_id` is specified but +not the `trip_id`, then it means the vehicle position corresponds to +"some" trip for that route, not "all" trips (it does not make sense for +it to apply to all trips). + +This means that if a user wants to know the vehicle positions for a +given route, you can show them all known positions, even if you are +unable to match the trip back to a trip in the corresponding GTFS feed. + +Refer to Chapter 4 for a description of all elements in a +`TripDescriptor`. + +### VehicleDescriptor + +This element is used to identify a specific vehicle, both internally and +for passengers. Every single vehicle in the system must have its own +identifier, and it should carry across all vehicle positions and trip +updates that correspond to the specific vehicle. + +| Field | Type | Frequency | Description | +| :---- | :--- | :-------- | :---------- | +| `id` | `string` | Optional | A unique identifier for a vehicle. This value is not intended to be shown to passengers, but rather for identifying the vehicle internally. | +| `label` | `string` | Optional | A label that identifies the vehicle to passengers. Unlike the `id` value, this value may be repeated for multiple vehicles, and it may change for a given vehicle over the course of a trip or series of trips. This might correspond to a route number that is displayed on a bus, or a particular train number, or some other identifier that passengers can see. | +| `license_plate` | `string` | Optional | The license plate of the vehicle. | + +### Position + +This element specifies the geographic position of a vehicle, as well as +related attributes such as bearing and speed. + +| Field | Type | Frequency | Description | +| :---- | :--- | :-------- | :---------- | +| `latitude` | `float` | Required | The latitude of the vehicle (a number in the range of `-90` to `90`). | +| `longitude` | `float` | Required | The longitude of the vehicle (a number in the range of `-180` to `180`). | +| `bearing` | `float` | Optional | Degrees, clockwise from True North. 0 is North, 90 is East, 180 is South, 270 is West. This can be either the direction the vehicle is facing, or the direction towards the next stop (GTFS-realtime does not provide a mechanism to determine which). | +| `odometer` | `double` | Optional | A measure of distance in meters. The GTFS-realtime specification does not state exactly what this value should represent. It could represent either the total number of meters the vehicle has ever travelled, or the number of meters travelled since the beginning of its current trip. | +| `speed` | `float` | Optional | The speed of the vehicle at the time of the reading, in meters per second. | + +While the latitude and longitude are the most important pieces of +information in this element, the vehicle's bearing can also be useful +to know. *Determining a Vehicle's Bearing* shows you how to +determine the bearing if it is not specified. + +### OccupancyStatus + +***Warning:** At time of writing the OccupancyStatus enumerator is +considered experimental only.* + +This enumerator is used for indicating how full a vehicle is. This can +be useful for warning passengers waiting for this vehicle that they may +not be able to fit and should instead attempt to use a different +vehicle. + +| Value | Description | +| :---- | :---------- | +| `EMPTY` | Used to indicate there are no (or very few) passengers on board. | +| `MANY_SEATS_AVAILABLE` | The vehicle is not empty, but it has many seats available. | +| `FEW_SEATS_AVAILABLE` | The vehicle has some seats available and is still accepting passengers. | +| `STANDING_ROOM_AVAILABLE` | The vehicle is still accepting passengers, but they will have to stand. | +| `CRUSHED_STANDING_ROOM_ONLY` | The vehicle is still accepting passengers, but they will have to stand and there is very limited space. | +| `FULL` | The vehicle is considered full but may still be accepting new passengers | +| `NOT_ACCEPTING_PASSENGERS` | The vehicle is not accepting new passengers. | + -- cgit v1.2.3