Skip to content

Simplify enum for occupancy, add occupancy_percentage #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gcamp merged 12 commits into from
Apr 9, 2020
Merged

Simplify enum for occupancy, add occupancy_percentage #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
4727b20
Simplify enum for occupancy, add occupancy_percentage
gcamp Apr 8, 2020
58822d4
Fix typo
gcamp Apr 8, 2020
aa5a556
Add more details for seating + standing capacity
gcamp Apr 8, 2020
2727f97
Add more details
gcamp Apr 8, 2020
c376f4a
Re-phrase comment
gcamp Apr 8, 2020
3f3ab98
Add more details about use of percent
gcamp Apr 8, 2020
28de1ae
Use new phrasing
gcamp Apr 8, 2020
39bbf1c
Add more details
gcamp Apr 8, 2020
5843b80
Update standing value to STANDING_AVAILABLE to match SIRI
gcamp Apr 9, 2020
50309af
Add privacy requirement for occupancy_percentage
gcamp Apr 9, 2020
b298543
Remove comment not relevant anymore
gcamp Apr 9, 2020
73a092a
Merge branch 'draft/occupancy_v2' of github.com:TransitApp/transit in…
gcamp Apr 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 20 additions & 23 deletions gtfs-realtime/proto/gtfs-realtime.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,43 +347,40 @@ message VehiclePosition {
}
optional CongestionLevel congestion_level = 6;

// The degree of passenger occupancy of the vehicle. This field is still
// experimental, and subject to change. It may be formally adopted in the
// future.
// The degree of passenger occupancy of the vehicle
enum OccupancyStatus {
// The vehicle is considered empty by most measures, and has few or no
// passengers onboard, but is still accepting passengers.
EMPTY = 0;
// Deprecated, if you need more granularity than the available enum please use occupancy_percentage
EMPTY = 0 [deprecated=true];

// The vehicle has a relatively large percentage of seats available.
// What percentage of free seats out of the total seats available is to be
// considered large enough to fall into this category is determined at the
// discretion of the producer.
MANY_SEATS_AVAILABLE = 1;
// The vehicle has seats available.
SEATS_AVAILABLE = 1;

// The vehicle has a relatively small percentage of seats available.
// What percentage of free seats out of the total seats available is to be
// considered small enough to fall into this category is determined at the
// discretion of the feed producer.
FEW_SEATS_AVAILABLE = 2;
// Deprecated, if you need more granularity than the available enum please use occupancy_percentage
FEW_SEATS_AVAILABLE = 2 [deprecated=true];

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

// The vehicle can currently accommodate only standing passengers
// and has limited space for them.
CRUSHED_STANDING_ROOM_ONLY = 4;
// Deprecated, if you need more granularity than the available enum please use occupancy_percentage
CRUSHED_STANDING_ROOM_ONLY = 4 [deprecated=true];

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

// The vehicle is not accepting additional passengers.
NOT_ACCEPTING_PASSENGERS = 6;
// Deprecated, if you need more granularity than the available enum please use occupancy_percentage
NOT_ACCEPTING_PASSENGERS = 6 [deprecated=true];

}
optional OccupancyStatus occupancy_status = 9;

// A percentage value representing the degree of passenger occupancy of 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.
// It is possible that the value goes over 100 if there are currently more passengers than what the vehicle was designed for.
// The precision of precision should be low enough that you can't track a single person boarding and alighting for privacy reasons.
optional OccupancyStatus occupancy_percentage = 10;

// 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.
Expand Down
17 changes: 6 additions & 11 deletions gtfs-realtime/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,8 @@ Realtime positioning information for a given vehicle.
| **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. |
| **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | 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](#enum-congestionlevel) | Optional | One |
| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _Optional_ | One | The degree of passenger occupancy of the vehicle.<br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.|
| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | The degree of passenger occupancy of the vehicle. More detail can be provided with _occupancy_percentage_. |
| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for including both seating and standing capacity. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of precision should be low enough that you can't track a single person boarding and alighting for privacy reasons. |

## _enum_ VehicleStopStatus

Expand Down Expand Up @@ -235,21 +236,15 @@ Congestion level that is affecting this vehicle.

## _enum OccupancyStatus_

The degree of passenger occupancy for the vehicle.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
The degree of passenger occupancy for the vehicle. OccupancyStatus should be used to display a textual or iconic representation of occupancy

#### _Values_

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ |
| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ |
| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ |
| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accommodate only standing passengers._ |
| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accommodate only standing passengers and has limited space for them._ |
| _**SEATS_AVAILABLE**_ | _The vehicle has seats available._ |
| _**STANDING_AVAILABLE**_ | _The vehicle can currently accommodate standing passengers._ |
| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ |
| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ |

## _message_ Alert

Expand Down Expand Up @@ -359,7 +354,7 @@ To specify a single trip instance, in many cases a `trip_id` by itself is suffic
* If the trip lasts for more than 24 hours, or is delayed such that it would collide with a scheduled trip on the following day, then `start_date` is required in addition to `trip_id`
* If the `trip_id` field can't be provided, then `route_id`, `direction_id`, `start_date`, and `start_time` must all be provided

In all cases, if `route_id` is provided in addition to `trip_id`, then the `route_id` must be the same `route_id` as assigned to the given trip in GTFS trips.txt.
In all cases, if `route_id` is provided in addition to `trip_id`, then the `route_id` must be the same `route_id` as assigned to the given trip in GTFS trips.txt.

The `trip_id` field cannot, by itself or in combination with other TripDescriptor fields, be used to identify multiple trip instances. For example, a TripDescriptor should never specify trip_id by itself for GTFS frequencies.txt exact_times=0 trips because start_time is also required to resolve to a single trip instance starting at a specific time of the day. If the TripDescriptor does not resolve to a single trip instance (i.e., it resolves to zero or multiple trip instances), it is considered an error and the entity containing the erroneous TripDescriptor may be discarded by consumers.

Expand Down