GTFS Carriage Position

[gcamp]

Summary

This proposal adds two new files, station_directions.txt and carriage_positions.txt, that let a feed express which carriage a rider should board to minimize walking at their destination.

Describe the Problem

To speed up their trip, passengers want to know which carriage to board for a fast transfer or a fast exit at their destination. pathways.txt can give a rider turn-by-turn directions inside a station, yet nothing tells them where to stand on the platform before boarding. Agencies often have this information but GTFS has no way to encode it.

Discussion started in #614. Thanks @vikiawv @jfabi for the comments and suggestions!

Proposed Solution

Two new files:

• station_directions.txt defines which side of the platform the front carriage stops at. One record per platform covers all trips, and optional route_id and direction_id records take priority over that default so special configurations can be modeled, such as a platform on a bidirectional single-track section. Conditionally Required: required when carriage_positions.txt is provided, since a recommendation cannot be interpreted without knowing platform orientation.
• carriage_positions.txt maps an arrival platform, and optionally a specific transfer platform or station entrance/exit, to the recommended carriage to board. The optional facility_type, which reuses the pathways.txt pathway_mode values for stairs, escalator and elevator, covers cases where the elevator serving a destination is several carriages away from the stairs serving the same destination, so riders needing step-free access can be sent to a different carriage.

Recommendations are expressed relative to the front of the train at the arrival platform. When the departure platform is oriented the other way, planners mirror the carriage with carriage_count - recommended_carriage + 1, so a single record stays usable regardless of which end of the train the rider boards from.

recommended_carriage is numbered from 1 for the first carriage in the direction of travel, matching GTFS-realtime CarriageDetails.carriage_sequence. Consumers that already show per-carriage occupancy from real-time data can then combine both without translating between two numbering schemes for the same concept, which would be a likely source of off-by-one errors.

carriage_count is part of the primary key, which lets a platform carry different recommendations for trains of different lengths, and producers without exact carriage positions can use logical divisions instead: carriage_count=3 with recommended_carriage=1 simply means "board near the front".

Here is an example of a dataset I made from the Paris GTFS and the open data carriage position CSV they have.

Type of change

GTFS Schedule

• Functional Change

Additional Information

This proposal is deliberately a small subset of what GTFS-VehicleBoardings attempted: it does not model platform sections or train formations, and instead encodes only the boarding recommendation itself.

PR #636 proposes vehicles.txt along with a vehicle_class on routes.txt and trips.txt. This proposal does not depend on it and stays usable on its own through carriage_count, but if #636 is adopted, an optional vehicle_class in carriage_positions.txt would be a natural follow-up to select the right configuration for a trip.

Proposed Discussion Period

I recommend reserving one month for discussion, since this adds two new files and affects station modeling.

Testing Details

• Consumer(s): Transit
• Producer(s): TBD (please mention if you want to produce!)
• Estimated Testing Period: TBD

Proposal Update Tracker

Date	Update Description
July 29 2026	Initial PR submission

[skalexch]

@gcamp thank you for raising this proposal. Best carriage information is an important addition to the spec.
I have a few remarks/questions:

1. front_car_position should probably be renamed to front_carriage_position, a less regional term and more consistent with the file name.
2. front_car_position does not need to be specified for both the departure and arrival platforms in order to make a recommendation. If someone is going to alight at a platform, they should still be able to get a recommendation for where to board initially, using only the front carriage position at the arrival platform.
3. The primary key for carriage_positions.txt could be extended or made to be the entire row. Sometimes more than one carriage could be "best". For example, a pathway in the middle of the platform can be best accessed via carriages 4 and 5 on an 8-carriage train.
4. In the proposal, to_stop_id can only reference a stop/platform or an entrance/exit, generic nodes are not allowed. Generic nodes aren’t necessarily a bad thing: if the producer links all platforms to generic nodes, those pathways could be used to chain together a best-carriage recommendation (I.e. getting the best carriage that leads to the generic node which leads to the exit).
5. I conceptually like the fact that recommended_carriage and carriage_count could be logical enums (e.g. carriage_count=3 to denote front, middle and back). However, if a consumer uses them literally they might end up recommending carriage_nb=2 while the rider is meant to take the middle carriage. There should be consistency there between what a producer and a consumer interpret. Better to introduce a separate field for categorical boarding positions.

[gcamp]

@skalexch thank you for the comments!

1. front_car_position should probably be renamed to front_carriage_position

👍

2. front_car_position does not need to be specified for both the departure and arrival platforms in order to make a recommendation.

Can you explain me a bit more because I don't see how we can do without. The recommendation of where you board on the origin will matter if the train front carriage is left or right on that station. See this line Edit : Never mind, I though a bit more about and you're right! Did the edit

3. The primary key for carriage_positions.txt could be extended or made to be the entire row. Sometimes more than one carriage could be "best". For example, a pathway in the middle of the platform can be best accessed via carriages 4 and 5 on an 8-carriage train.

👍

4. In the proposal, to_stop_id can only reference a stop/platform or an entrance/exit, generic nodes are not allowed. Generic nodes aren’t necessarily a bad thing

I'm mixed on that one. I don't want to complexify the implementation too much, but I see the benefits. I'm going to change but if others think it's too much let me know.

5. Better to introduce a separate field for categorical boarding positions.

I guess my counter question is why would a consumer care about if the num carriage is true or not in the context of boarding location? If we added a field I'm not sure how we would use it (re guiding principles of speculative features)

[skalexch]

@gcamp thanks for the changes! For the two remaining questions:
4) +1, it will complexify but it's better to not prohibit the usage of generic nodes altogether because they can exist in a station's pathways graph and their use case could be valid. Prohibiting them now will open a versioning or spec correction discussion in the future if someone supporting generic nodes decides to implement best carriage info.

5. I'm not sure if I understood your question. The issue I see arises from this case:
   Assume a consumer displays this phrase "Take carriage {recommended_carriage} out of {carriage_count} from your right to exit easily".
   The consumer gets a GTFS feed with recommended_carriage=2 and carriage_count=3. The producer's implication is to take the MIDDLE (2) carriage out of [FRONT (1), MIDDLE (2), BACK (3)].
   In this case, the consumer will show "Take carriage 2 out of 3 from your right to exit easily". Because the consumer does not know that 3 is not the actual number of carriages, but a logical position enum. If the train in question has 8 carriages, that message might confuse the rider.

As it currently stands, the proposal works 100% clearly and correctly only if the consumer shows a graphic of the relative position of the rider after doing the calculation recommended_carriage/carriage_count. If the consumer wants to be specific on which exact carriage the rider should ride, then carriage_count has to always equate the real carriage count.

I like both concepts of being able to show either the actual carriage or a relative position [FRONT, MIDDLE, BACK]. But I think both of them being modelled using the same fields might cause misinterpretation.

[gcamp]

If the consumer wants to be specific on which exact carriage the rider should ride

My point is that is not something we want to do. I'm not against this use case, but it's a speculative feature unless somebody else ask. What we could do is rename the field and state that it's only a virtual representation of the carriage length, and keep the door open for an other field in the future.

[rudiejd]

since station_directions.txt is actually concerned with only "stops" or "platforms" (location_type = 0), and actually forbids stations (location_type = 1), should the name of this file be changed? Possibly to stop_directions.txt or platform_directions.txt?

[gcamp]

Good point, platform_directions.txt makes sense to me

[rudiejd]

what would an empty stop_id in station_directions.txt signify? Would this select all stops in one direction? I think this behavior should be clarified

[gcamp]

That field is set as required, so you can't have it empty(?)

[rudiejd]

ahh sorry, I incorrectly read "location_type=0 or empty" as meaning that the stop could be a stop of location_type=0 or stop_id could be empty. and Github isn't letting me resolve for some reason 🙃

[nlee-septa]

Thank you for sharing this, @gcamp! This would be valuable information for riders, relatively low effort for producers to implement, and is already being implemented in different ways across consumers.

SEPTA is interested in producing this, with a few clarifications.

[nlee-septa]

Suggested change

	| `carriage_count` | Positive integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. |
	| `carriage_count` | Positive integer | **Required** | Number of carriage positions in this configuration. If `carriage_count_precision=0` or empty, represents logical divisions (e.g., 3 for front/middle/back). If `carriage_count_precision=1`, represents an exact carriage count. |
	| `carriage_count_precision` | Enum | Optional | Indicates if `carriage_count` represents relative divisions or an exact carriage count. Valid options are:<br><br>`0` or empty - `carriage_count` represents relative divisions (e.g., 3 for front/middle/back). <br>`1` - `carriage_count` is an actual count of discrete carriages. <br><br> If no values are provided, all `carriage_count` values should be considered to represent relative divisions. |

@skalexch I had a similar reservation about interpretations of logical vs. exact carriage counts. I think it's important that the producer be able to communicate to the consumer how exactly to interpret these values. What do you and @gcamp think of this option?

[skalexch]

@nlee-septa +1 for any field that clarifies how the boarding position should be considered.

Just one thought: I'd change the name to something other than "precision" (if there is any word that conveys that the distinction is between actual number and category). To me, "precision" give an impression of mathematical approximation.

[gcamp]

carriage_count_is_virtual would be what I would suggest.

I think this opens the door to having a label on each carriage, I asked the questions on how to model that in the vehicle proposal here.

[nlee-septa]

Maybe carriage_count_exactness (or carriage_count_relativeness, since the default is "relative")? Or simply carriage_count_type, though I prefer more descriptive field names where possible.

Inspiration for this field comes from stop_times.timepoint, which conveys a similar meaning of "another field should be taken as exact or inexact". Unfortunately the nomenclature doesn't transfer well.

[nlee-septa]

Missed your earlier response, sorry! I like carriage_count_is_virtual or carriage_count_is_relative.

[nlee-septa]

Suggested change

| `via_pathway_mode` | Enum | Optional | Mode of the pathway the rider takes to reach `to_stop_id`, for which `recommended_carriage` is the closest carriage. Valid options are a subset of [pathways.txt](#pathwaystxt) `pathway_mode`:<br><br>`2` - Stairs.<br>`4` - Escalator.<br>`5` - Elevator.<br><br>Riders with different accessibility needs take different pathways out of the same platform, so a producer may publish one record per mode. When empty, the recommendation applies regardless of how the rider continues. |

| `via_pathway_mode` | Enum | Optional | Mode of the pathway (or series of successive pathways) the rider takes to reach `to_stop_id`, for which `recommended_carriage` is the closest carriage. Valid options are a subset of [pathways.txt](#pathwaystxt) `pathway_mode`:<br><br>`2` - Stairs.<br>`4` - Escalator.<br>`5` - Elevator.<br><br>Riders with different accessibility needs take different pathways out of the same platform, so a producer may publish one record per mode. When empty, the recommendation applies regardless of how the rider continues.<br><br>If `via_pathway_mode=2`, the connecting pathway(s) MAY have any `pathway_mode` value.<br>If `via_pathway_mode=4`, the connecting pathway(s), MUST NOT have `pathway_mode=2` (stairs).<br>If `via_pathway_mode=5`, the connecting pathway(s) MUST NOT have `pathway_mode=2` (stairs) or `pathway_mode=4` (escalator).|

Adding language like this will prevent a possible conflict where carriage_positions.txt indicates an elevator is available, but pathways.txt only contains stair pathways.

[skalexch]

I know that in most stations the hierarchy is this: Either stairs or stairs+escalator or stairs+escalator+elevator.

But to truly avoid conflicts, pathways.txt (if exists) should cover all possible pathways for that pair of station nodes.
So a cleaner logic would be:
If pathways.txt has at least one entry from stop_id to to_stop_id or a bidirectional entry between stop_id and to_stop_id, the value for via_pathway_mode should exist in pathways.txt for that pair of stop_ids.

That would lead to:

1. If pathways for that pair of nodes do not exist, no check is necessary. In this case, carriage_positions.txt is the direct source of truth.
2. If at least one pathway for that pair of nodes exists, then all possible pathways should be in pathways.txt. In this case, carriage_positions.txt is pulling from the COMPLETE source of truth.

[nlee-septa]

What if carriage_positions.txt indicates that an elevator pathway is available between stop_id and to_stop_id, but no such pathway is in pathways.txt? I think the spec should explicitly state that is not valid, because either pathways.txt does not contain all possible pathways, or carriage_positions.txt describes a pathway that does not exist (and it's not obvious which file has the error). Alternatively, instruction on which should prevail could be added.