GTFS Carriage Position

[gcamp]

Summary

This proposal adds two new files, platform_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:

• platform_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. Extended an other month to end of September

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
August 31 2026	Extend discussion period

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

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

[gcamp]

I'm a bit worried about data duplication with vehicles.txt if we do support "real" carriage count. However vehicles.txt right now is not setup to support carriage inside vehicles.

To get out of the impasse, the only way out I see is :

• only support virtual carriage count for now
• wait for the vehicles.txt specification to be merged before releasing this

I'd prefer the first option, but let me know if I'm missing some other better in between option.

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

[skalexch]

@gcamp correct me if I am wrong, I think the point of via_pathway_mode is for accessibility? Because otherwise I agree with @nlee-septa and I think that its usage will only be valid when it is the only pathway between stop_id and to_stop_id and its entails having a 100% accurately mapped pathways.txt.

An issue I see, aside from the one mentioned by @nlee-septa, is if multiple pathways are between the platform and to_stop_id. If I have to take an elevator then a walkway then an escalator, the result would not be easy to distinguish. So if the point of the field is accessibility then it should be something like accessible_navigation. If the point is to show the user the first pathway they need to take, the field might be renamed, or a signposting field could be added.

[gcamp]

Yes it's for accessibility, but not only. Basically my process was

1. IDFM has an "equipment type" value
2. however the convention in GTFS is to use number enums that represent values, so I initially switched to that
3. If we use a number, might as well use the number we have already, which is the pathway_type

That value can also differentiate between stairs and escalators, even if yes the main purposes is elevators for accessibility purposes.

[gcamp]

Update today :

• Extended the discussion period for an other month, since we're still in active discussion
• Updated the file name from station_directions.txt to platform_directions.txt (suggested by @rudiejd)

[orhazal]

Hello @gcamp,

Thank you for the proposal, this is valuable information for passengers and commuters.
We use the carriage positioning data provided by IDFM, and it would be great to have it standardized in GTFS.

I have a few questions:

1- For Transilien and RER, a single stop (monomodal stop place) with location_type=0 represents all the platforms, for all routes and directions in a station (e.g. Châtelet les Halles IDFM:monomodalStopPlace:45102 for RER A, B and D). Moreover, direction_id is not enough to pinpoint a "stable" direction within the station. A verifiable case is Pontoise and Saint-Ouen-l'Aumône (line H) : in these two stations, trips sharing the same direction_id can cross the station in opposite directions. Because of this, the (stop_id, route_id, direction_id) tuple from platform_directions.txt is not sufficient to model the direction in these stations.

We currently use a combination of (previous station, next station, terminus), but this approach turns out to be quite unreliable when operating patterns change (skipped stations, etc.).

The question : What information could we use to handle this case, which is problematic for several stations on the Transilien/RER network?

2- On the real vs relative carriage count discussion, I would like to bring up another case : the Seoul Metropolitan Subway. On this network, the boarding information goes one level deeper than the carriage : it is defined at the door level. Every boarding position on the platform is marked with a (car, door) pair, for example "5-1" for car 5, door 1, and journey planners like Naver tell passengers the exact door to board. Given the crowding levels on this network, this granularity is considered genuinely valuable for passengers to transfer or exit quickly in overcrowded stations. It is worth noting that this is not proprietary app data : Seoul Metro publishes it as open data.

The question : should the proposal anticipate a door-level granularity, for instance by keeping the carriage identification scheme compatible with an optional door field or a future extension, or is this considered too detailed for a first version?

Thank you.

[vikiawv]

Since you Mention Seoul's Metro I also have to mention that in Vienna a somewhat similar system is used. It displays the exit directions for each individual door in the train carriage itself including departures of lines at the corresponding exit.
It is however not included in their App, only displayed in the Train itself.
https://de.wikipedia.org/wiki/U-Bahn_Wien_X#/media/Datei:Fahrgastinformationssystem_X-Wagen,_U-Bahn_Wien.jpg

The system itself is properiatory by Siemens Mobility it seems.

The local data provider "Wiener Linien" is probably willing to submit such data also for GTFS. They likely already have the entire system mapped out for the Siemens System.

[orhazal]

@vikiawv Interesting ! Some subways in Paris have a similar display inside, but without door-level detail.

[miklcct]

I have some doubt about this proposal:

1. If a route uses a mix of different length trains, can this spec specify that? For example, on a route where 8-carriage and 12-carriage trains mixes, at some stations, the 8-carriage train stops at the front, at others, the 8-carriage train stops at the middle, while at some stations having short platforms, the last 4 carriages or a 12-carriage train will not open their doors.

2. How can I specify that a train will open its doors on both sides at a specific stop?

[orhazal]

If a route uses a mix of different length trains, can this spec specify that?

On the Transilien network in the Paris region, this information is only available in their realtime API (SIRI), which makes it unpredictable in the static GTFS schedule.

Maybe we could have one row per train composition variant, and the consumer could either show both of them to the traveller (short train -> BACK, long train -> MIDDLE) or pick the right one using the realtime data?

How can I specify that a train will open its doors on both sides at a specific stop?

Is it really useful? In the end, the purpose of this information is to give the closest boarding position relative to the next connection or exit. Let's say subway A stops at a station and the doors open on both sides: the platform on the right has Exit 1 at the rear, and the platform on the left has a connecting tunnel to subway B in the middle. If the traveller wants to transfer to subway B, a single position (car 4 out of 8, or MIDDLE) is enough. If they want to leave through Exit 1, it's the same: car 8 out of 8, or BACK.
We had data on left/right door opening: it was hard to maintain and ultimately not that useful.

[orhazal]

Another thing to consider here: what if we have a shared platform between two lines, where the transfer is just crossing the platform, meaning every position is the "best position"? How should the spec handle this? Do we list all the possible positions in the file (e.g. cars 1 to 8 out of 8 for this transfer), or do we put nothing at all? The first option is too verbose, and the second could be interpreted as missing data.

I lean towards the first option.

EDIT: a strong addition would be a transitive carriage position calculation. Example: I take the RER A to Châtelet les Halles. There, I cross the platform to take the RER B, so all positions are "best". Then at Aéroport CDG, I take the escalator located in the middle of the platform.

In this example, if we could somehow model an "ALL" best position, it would be easy for consumers to tell passengers to board in the middle of the RER A, then in the middle of the RER B, by transitivity. Otherwise, no boarding advice would be given when boarding the RER A, since all positions are equally good for the transfer to the RER B.

But maybe that's too complicated. Then again, it's something a GTFS consumer could easily infer from an "ALL" value, or from listing all cars out of n.

[vikiawv]

For shared plattforms there could be a system that looks up which carriage or door of the current train is equal to the best carriage/door in the second train.

Problem beeing not all such changes have trains with equal carriages and/or lenght. At Station Wien Längenfeldgasse for example the change is from a 6-car train to a 12-car train.
At other stations in comparison the trains have equal lenghts and carriages such as Berlin Mehringdamm, there you can just take the reccomended carriage for the second train also for the first one, if you change on the same plattform.