Vehicle Positions

When agencies publish GTFS-RT Vehicle Positions, Transit and other third parties can display the precise location of the vehicles. This allows riders to track vehicles and have more confidence in their trip plans.

We recommend agencies follow the GTFS Realtime standard for Vehicle Positions. If you are using an alternative API format, we have some best practices outlined in the section dedicated to non GTFS-RT API’s

In this article:

Required Fields

Optional Fields

How Transit Displays Vehicle Positions

Automated Checks

Non GTFS-RT API's

Required Fields

Trip Descriptor

• TripDescriptor is used to determine exactly what trip the vehicle is running. A trip_id is required – we cannot not support matching vehicle positions with no trip_Id. The trip_id should also match the GTFS Static data.
  • If a trip_id does not match the static data, but there is a corresponding tripUpdate provided with the same trip_id, we attempt to infer the headsign of the vehicle and match it to a trip in the static data. This allows Transit to continue displaying the vehicle in the app when there are mismatches between realtime and static

Position

• The position field must include both latitude and longitude to display a vehicle on the map.

Timestamp

• Include accurate timestamps for both the vehicle (when the position was recorded) and the feed (when it was last updated). 
• Transit only displays the latest vehicle position timestamp, i.e, how long ago the vehicle location was recorded at that position.
• Provide updates as frequently as possible. Transit will request vehicles positions every 10 seconds by default. This refresh rate is configurable if more frequent updates can be provided.
• Transit discards stale vehicle positions that are older than 3 minutes

Optional Fields

Vehicle Descriptor

• Vehicle Information such as label or id  may be supported. Vehicle information is not automatically consumed and requires manual configuration to set up in Transit’s end. If you would like Transit to display your vehicle information, please get in contact with us at data@transit.app
• If wheelchair_accessible is provided, it is used to overwrite the value in wheelchair_accessible in trips.txt

Occupancy Status

The OccupancyStatus is not required, but will be displayed if provided. The field includes seven levels of vehicle crowding info. Transit only displays three levels and will categorize the RT values as follows:

Crowding information provided in your vehicle positions feed is visible on the vehicle icon, and in the vehicle information sheet that appears when a rider taps a vehicle’s icon.

How Transit Displays Vehicle Positions

Automated Checks

Transit developed a realtime checker that continuously monitors the status of Vehicle Position feeds to provide support for both agencies and users.

When the number of vehicles in a VehiclePosition feed drops significantly below normal levels, (typically because of a complete feed outage or a severe data matching issue). Transit will display a warning banner within the app to notify users.

Non GTFS-RT API's

Matching the vehicle to a trip

In order for Transit to be able to associate a vehicle to the correct route, we need to know either its trip_id, or its route_id and trip_headsign. The best way to associate real time data with a scheduled item is by using the trip_id. If it's impossible to include a trip_id in your API, we can also use fields to match the route and headsign. The route_id or route_short_name can work, as long as they use the same identifiers as the GTFS Static. Similarly, the trip_headsigns should also directly match the static data.

Vehicle Information

Vehicles should have some way of determining how old the location report is, like a timestamp. They must also include latitude and longitude, and ideally should include a vehicle_id. Crowding information may be displayed if provided

Server requirements:

Vehicle locations are fetched every 20 seconds for API requests, and we fetch the state of the entire network – not just vehicles for a specific user. For this reason, we prefer unitary endpoints that provide all vehicles in revenue service, or requests by route. Requesting vehicle locations per stop may be feasible for some very small agencies, but we tend not to support this method as it results in unsustainably high server requirements for both Transit and the agency in question.