google / google/transit

Resolve ambiguity in definition of `VehiclePosition.Position.Bearing`

Open
#356 6 comments 0 reactions 0 assignees View on GitHub
GTFS Realtime Status: Stale
Dominant language
No language data
Stars
1.1k
Forks
225
Avg merge
7d 17h
Merged PRs (30d)
3

Description

**Issue:** The definition of `VehiclePosition.Position.Bearing` doesn't sufficiently define the direction of the vehicle because the reference direction could be either true north, an intermediate stop, or other intermediate location and there is nowhere to specify which it is.

# Context

`VehiclePosition.Position.Bearing` is [defined in the spec](https://gtfs.org/realtime/reference/#message-position) as (emphasis mine):

> 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.

The general statement in the [VehiclePositions](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/vehicle-positions.md) documentation has even less detail:

> Bearing - direction that the vehicle is facing

The [TIDES data spec ](https://tides-transit.github.io/TIDES/main/tables/#vehicle-locations) would like to be consistent with GTFS, but without this variable being sufficiently defined we will not be able to do so.

# Options

1. Keep ambiguous definition of `Bearing`, add new enum field to define what it is in reference to i.e. `BearingReference`
2. Keep field name of `Bearing`, but tighten up the definition to be a reference to True North (**potential breaking change if the alternate def is used**)
3. Add new field `Heading` which is tightly defined as degrees clockwise from True North

# Discussion Points / Questions

1. What is the probable universe of data producers which produce bearings that are not relative to True North? Is it a handful, a zillion?
2. If there are a few of the above...then are data-consumers just inferring the reference direction from the data?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.