/
GTFS-RT Broadcasters

GTFS-RT Broadcasters

Owned by Alban Peignier
Last updated: Jul 29, 2024 by Renaud Vignery
5 min read

Support GTFS-RT requests

If the user adds a GTFS-RT broadcaster to a Partner, like gtfs-rt-trip-updates-broadcaster, gtfs-rt-vehicle-positions-broadcaster, gtfs-rt-service-alerts-broadcaster , etc

For example:

POST /<referential_slug>/partners { "slug": "test", "connectorTypes": [ "gtfs-rt-trip-updates-broadcaster" ], "settings": { "local_credential": "secret", "remote_objectid_kind": "internal" } }

Then the user can perform GTFS requests:

GET /<referential_slug>/gtfs GET /<referential_slug>/gtfs/trip-updates GET /<referential_slug>/gtfs/vehicle-positions GET /<referential_slug>/gtfs/service-alerts

Endpoints

The user can select the expected GTFS-RT entities by using one of the GTFS-RT endpoints:

Global endpoint /<referential_slug>/gtfs

This endpoint provides all entities. If no GTFS-RT broadcaster is defined (gtfs-rt-trip-updates-broadcaster, gtfs-rt-vehicle-positions-broadcaster, etc), this endpoint returns a 501 status code.

Trip Update endpoint /<referential_slug>/gtfs/trip-updates

This endpoint provides only Trip Update entities. If the gtfs-rt-trip-updates-broadcaster is not defined into the associated Partner, this endpoint returns a 501 status code.

Vehicle Position endpoint /<referential_slug>/gtfs/vehicle-positions

This endpoint provides only Trip Update entities. If the gtfs-rt-vehicle-positions-broadcaster is not defined into the associated Partner, this endpoint returns a 501 status code.

Service Alert endpoint /<referential_slug>/gtfs/service-alerts

This endpoint provides only Alert entities. If the gtfs-rt-service-alerts-broadcaster is not defined into the associated Partner, this endpoint returns a 501 status code.

Authentication

The user can specify a credential in the GTFS-RT request by using an HTTP header Authorization with this syntax : for secret token, Authorization: Token token=secret

GET /<referential_slug>/gtfs Authorization: Token token=secret

If a token is given into the GTFS-RT request, the Partner associated to the request will be find by local_credential.

If no token is given into the GTFS-RT request, the Partner without local_credential will be associated to the request.

For example, with the following Partners:

  • Partner A, with local_credential: secret

  • Partner B, with local_credential: other

  • Partner C, with no local_credential

The following request:

GET /bibus/gtfs Authorization: Token token=secret

will be associated to the Partner A.

The following request:

GET /bibus/gtfs

will be associated to the Partner C.

The following request:

GET /bibus/gtfs Authorization: Token token=dummy

will return a 401 HTTP status code.

GTFS-RT response

The GTFS-RT response contains a Feed Message structure as described in the GTFS-RT reference.

The following content is managed by Ara:

FeedMessage

  • FeedHeader

    • Incrementality

  • FeedEntity

    • TripUpdate

      • TripDescriptor

      • StopTimeUpdate

        • StopTimeEvent

    • VehiclePosition

      • TripDescriptor

      • Position

    • Alert

      • ActivePeriod

      • InformedEntity

      • Cause

      • Effect

      • HeaderText

      • DescriptionText

      • SeverityLevel

 

All GTFS-RT responses respect this structure.

The TripUpdate entities are provided only if the user request selects them and if the gtfs-rt-trip-updates-broadcaster is associated to the Partner. See the associated story for content details.

The VehiclePosition entities are provided only if the user request selects them and if the gtfs-rt-vehicle-positions-broadcaster is associated to the Partner. See the associated story for content details.

The Alert entities are provided only if the user request selects them and if the gtfs-rt-service-alerts-broadcaster is associated to the Partner. See the associated story for content details.

Complete example (in pseudo json content)

{ "header": { "gtfs_realtime_version": "2.0", "incrementality": "FULL_DATASET", "timestamp": "1580136888" }, "entity": [ { "id": "trip:281721", "trip_update": { "trip": { "trip_id": "281721", "route_id": "3001I", "start_time": "16:36:00" }, "stop_time_update": [ { "stop_sequence": 1, "departure": { "time": "1580135775" }, "stop_id": "1020503" }, { "stop_sequence": 2, "arrival": { "time": "1580136050" }, "departure": { "time": "1580136050" }, "stop_id": "1174501" }, { "stop_sequence": 3, "arrival": { "time": "1580136234" }, "stop_id": "1250501" } ] } }, { "id": "vehicle:943", "vehicle": { "trip": { "trip_id": "281721", "route_id": "3001I", "start_time": "16:36:00" }, "position": { "latitude": 60.27628707885742, "longitude": 24.856653213500977, "bearing": 133 }, "vehicle": { "id": "943" } } }, { "id": "d2fd41c5-8bee-4920-9c75-e3d505f82f01", "alert": { "active_period": [ { "start": 1720418400, "end": 1723671900 } ], "informed_entity": [ { "route_id": "7" } ], "cause": 10, "effect": 9, "header_text": { "translation": [ { "text": "route change" } ] }, "description_text": { "translation": [ { "text": "Route change from July 10th to July 14th" } ] }, "severity_level": 3 } } ] }

General attributes

FeedHeader attribute

Value

FeedHeader attribute

Value

gtfs_realtime_version

“2.0”

incrementality

FULL_DATASET

timestamp

According to the current time on response creation

Broadcast Vehicle Journey data via a GTFS-RT Trip Updates Broadcaster

When the user requests the GTFS-RT Trip Updates, Ara returns a GTFS-RT Trip Update entity for each Vehicle Journey which have at least a Stop time in the future, with the following attributes:

FeedEntity attribute

Value

id

“trip:<vehicle journey.objectid>”

TripDescriptor attribute

Value

trip_id

Vehicle Journey objectid

route_id

Line objectid

start_time

First Stop Visit actual or expected or aimed departure time

StopTimeUpdate attribute

Value

stop_sequence

Stop Visit PassageOrder

stop_id

Stop Area objectid

arrival

Stop Visit absolute actual or expected or aimed arrival time if defined

departure

Stop Visit absolute actual or expected or aimed departure time if defined

Trip Update Entity example (in pseudo json content)

{ "id": "trip:281721", "trip_update": { "trip": { "trip_id": "281721", "route_id": "3001I", "start_time": "16:36:00" }, "stop_time_update": [ { "stop_sequence": 1, "departure": { "time": "1580135775" }, "stop_id": "1020503" }, { "stop_sequence": 2, "arrival": { "time": "1580136050" }, "departure": { "time": "1580136050" }, "stop_id": "1174501" }, { "stop_sequence": 3, "arrival": { "time": "1580136234" }, "stop_id": "1250501" } ] } }

Broadcast Vehicle data via a GTFS-RT Vehicle Position Broadcaster

When the user requests the GTFS-RT Trip Updates, Ara returns a GTFS-RT Vehicle Position entity for each Vehicle with the following attributes:

TripDescriptor attribute

Value

trip_id

Vehicle Journey objectid

route_id

Line objectid

start_time

First Stop Visit actual or expected or aimed departure time

StopTimeUpdate attribute

Value

stop_sequence

Stop Visit PassageOrder

stop_id

Stop Area objectid

arrival

Stop Visit absolute arrival time (actual or expected or aimed) if defined

departure

Stop Visit absolute departure time (actual or expected or aimed) if defined

VehiclePosition attribute

Value

latitude

Vehicle latitude

longitude

Vehicle longitude

bearing

Vehicle bearing if defined

VehicleDescription attribute

Value

id

Vehicle objectid

Vehicle Position Entity example (in pseudo json content)

{ "id": "vehicle:943", "vehicle": { "trip": { "trip_id": "281721", "route_id": "3001I", "start_time": "16:36:00" }, "position": { "latitude": 60.27628707885742, "longitude": 24.856653213500977, "bearing": 133 }, "vehicle": { "id": "943" } } }

 

Broadcast Alert data via a GTFS-RT Service Alert Broadcaster

When the user requests the GTFS-RT Service Alert, Ara returns a GTFS-RT Alert entity for each Situation with the following attributes:

TimeRange attribute

Value

start

Beginning of period when the Alert will be displayed

end

End of period when the Alert will be displayed

EntitySelector attribute

Value

route_id

Line code

stop_id

Stop Area code

Cause attribute

Value

cause

Cause of the Alert

Effect attribute

Value

effect

Effect of the Alert

HeaderText attribute

Value

Translation attribute

text → An UTF-8 string containing the message

language → BCP-47 language code

DescriptionText attribute

Value

Translation attribute

text → An UTF-8 string containing the message

language → BCP-47 language code

SeverityLevel attribute

Value

severity_level

Severity of the Alert

Alert Entity example (in pseudo json content)

{ "id": "d2fd41c5-8bee-4920-9c75-e3d505f82f01", "alert": { "active_period": [ { "start": 1720418400, "end": 1723671900 } ], "informed_entity": [ { "route_id": "7" } ], "cause": 10, "effect": 9, "header_text": { "translation": [ { "text": "route change", "language": "en" } ] }, "description_text": { "translation": [ { "text": "Route change from July 10th to July 14th", "language": "en" } ] }, "severity_level": 3 } }

Related content