GTFS-RT Broadcasters

Owned by Alban Peignier
Last updated: Apr 30, 2020
6 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, 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

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.

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:

will be associated to the Partner A.

The following request:

will be associated to the Partner C.

The following request:

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

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.

Complete example (in pseudo json content)

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)

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)